Using an application configuration file

You have the option of using an application configuration file to specify configuration information—such as the host name and port, time-out values, and log file settings—for your .NET client application. Your xfNetLink .NET distribution includes the xfNetLink .NET Configuration Utility, which can be used to create and edit configuration files.

What is an application configuration file and when should I use one?

An application configuration file (config file, for short) contains settings that are used by .NET applications. Default values for the configuration settings used by xfNetLink .NET are built into the program. These program defaults, shown in the table below, cannot be changed. If they are suitable for your application, you do not need to use a config file. If they are not suitable, you can use a config file to override some or all of the settings.

Default Configuration Settings
Setting	Program default
connect timeout	120 seconds
encoding^a	ISO-8859-1
host	localhost
initialize timeout	30 seconds
logfile	c:\xfnlnet.log
logging	none (i.e., logging is off by default)
pool return	false
port	2356
single log file	off

a. The program default for the encoding setting cannot be changed using the xfNetLink .NET Configuration utility. If you need to change the default character encoding, such as to access the Euro symbol, see Synergex Knowledgebase article 2496.

xfNetLink .NET employs a standard .NET configuration file, which uses XML to record configuration settings. In general, there is one config file per application. (This rule does not always strictly apply; see Naming the configuration file below.) Within the config file, you can create default settings that will be used by all assemblies that use that particular configuration file. These default config file settings override the program defaults. In addition, you have the option of creating settings for individual procedural classes within your assemblies. Settings at the class level override the default settings.

If you use an explicit connect() to establish the connection with xfServerPlus, you can override at runtime the host and port settings specified in the config file (or the program defaults). See step 4 in Using your Synergy .NET assembly: The basics and the Method reference for more information. (Note that when you are using pooling, you do not call the connect() method, so you will need to either use the default host and port values or specify them in the config file.)

Naming the configuration file

xfNetLink .NET uses the standard .NET naming conventions for config files. Your file must adhere to these conventions in order for xfNetLink .NET to find and use the file.

If the application uses pooling, the file must be named dllhost.exe.config and reside in the %windir%\system32 directory (for an application registered as 64-bit) or %windir%\SysWOW64 (for an application registered as 32-bit). (For more information about the bitness of the registered application, see A word about bitness.) This means that if you have multiple applications (of the same bitness) residing on the same machine, they must all use a single config file. If those multiple applications require different configuration settings, you can implement the settings at the class level.

For a web application that does not use pooling, the file must be named web.config and reside in the root directory for the web application. If you have multiple web applications residing on the same machine and want each one to use a different config file, create a separate directory for each application.

When you create a Visual Studio project for a web application, it will include a config file named web.config. We recommend that you use this file (assuming your web application does not use pooling). See To open an existing config file below for instructions on adding the xfNetLink .NET configuration information to the file.

For a Windows (i.e., non-web) application that does not use pooling, the file must be named with the application filename (including extension) plus the .config extension. It must reside in the same directory as the application. For example, if your application were named myApp.exe, the file would be named myApp.exe.config.

When you create a Visual Studio project for a Windows application, it will include a config file named App.config. We recommend that you use this file (assuming your application does not use pooling). When you build the project, Visual Studio will copy the file to the bin\release or bin\debug directory and rename it with the application name. See To open an existing config file below for instructions on adding the xfNetLink .NET configuration information to the file.

Creating and editing configuration files

The xfNetLink .NET Configuration Utility (synnetcfg.exe) enables you to create and edit application configuration files for your xfNetLink .NET applications. Although you may need to edit the config file to add information required by your application, we do not recommend manually editing the xfNetLink .NET portions of the file.

To start the utility

From the Windows Control Panel, select Synergy Control Panel > xfNetLink .NET Configuration.

You can also run the utility from the menu option in Workbench. Select Synergy/DE > Utilities > xfNetLink .NET Configuration.

To open an existing config file

Select File > Open or click the Open config file toolbar button and then navigate to the location of the file.

If the file was created by Visual Studio and this is the first time it’s been opened in the xfNetLink .NET Configuration Utility, you’ll be prompted to add the xfNetLink .NET configuration information. Click Yes.

When you are done editing, select File > Save or click the Save config file toolbar button.

To create a new config file

Select File > New or click the New config file toolbar button.

Configure settings for the default class or add a class and configure settings for it. See To add a class to a configuration file and To configure settings for a class below for instructions.

When you are through editing the settings, select File > Save As or click the Save config file toolbar button. Give the file a valid name. See Naming the configuration file.

To add a class to a configuration file

With a config file open, click the Add Class button.

Type the name in the Class name field. The class name is case sensitive. Be careful to type the name correctly; the xfNetLink .NET Configuration Utility does not validate the name you enter.

Click OK. You can now configure settings for the class; see below for instructions.

To configure settings for a class

Select the class from the list of Synergy Classes. Any settings currently defined for the class will display in the Class Settings list.

Click the Add button to display the Add Class Setting dialog box.

In the Key field, select the setting you want to add.

In the Value field, specify the value for the selected key. Refer to the table below.

Click OK. Repeat this procedure for each setting you want to add.

Class Settings

Key^a

Set value to

connect timeout

The number of seconds xfNetLink will wait for an acknowledgment from the session started by the logic server in xfServerPlus. (This is ‘B’ in figure 1.) The default for normal operation is 120 seconds; for debug it is 600 seconds. Both the normal time-out and the debug time-out will change to the value you specify here. This value is also used to set the request for session time-out (‘A’ in figure 1).

1. xfNetLink time-outs.

host

The name or IP address of your xfServerPlus machine.

initialize timeout

(pooling only) The number of seconds xfNetLink will wait for a return from a remote call to xfServerPlus when any of the five pooling support methods are called. The default is 30 seconds. This value should be set to less than the connect timeout. If it is not, the connect timeout is used instead.

logfile

The path and filename of the file to use for client-side logging. Do not use logicals to specify the filename location.

logging

The type of information to be logged. When you select logging in the Key field, the Logging Options become available. Check the boxes to indicate what information you want logged. See Using client-side logging for more information and a sample log.

None. Turns logging off for this class. You can also turn off logging by deleting the logging setting. However, this option enables you to have logging on by default but off for a specific class.
All. Includes all types of logging listed below.
Errors. Logs errors only. Recommended for production environments.
User-defined methods. Logs calls to methods in the SMC. Includes parameters passed in and shows what is in the parameter after the call.
Utility methods. Logs calls to the utility methods in the class (e.g., connect( ), disconnect( )  ). Includes parameters passed in and out.
Configuration settings. Logs messages regarding configuration settings.
Packets. Logs the complete packets that are sent and received on the client; includes date/time stamp. If encryption is enabled, the log displays a string of 10 asterisks instead of the packet contents.

pool return

(pooling only) When you select pool return in the Key field, the Pool Options become available. Select the “Return objects to pool” check box if you want the objects instantiated from this class returned to the pool after they are used. See Reusing objects for more information.

port

The port number that xfServerPlus is listening on.

single log file

“On” to use a single log file for all sessions. If not set, or if set to “off”, a separate log file is used for each class that instantiates a connection to xfServerPlus, and a date/time stamp is appended to the end of the log filename (before the file extension) to differentiate the logs. See Using client-side logging for additional information.

a. In the config file itself, multi-word keys are written without spaces: connecttimeout, initializetimeout, poolreturn, singlelogfile.

To modify a setting

Select the class from the list of Synergy Classes. The current settings for that class will display in the Class Settings list.

In the Class Settings list, select the setting you want to change.

Click the Modify button.

In the Modify Class Setting dialog box, type or select a new value for the key. See the table above for details on key values.

Click OK.

To delete a setting

Deleting a setting from a class causes the class to use the default value for that setting or, if there is no default defined in the config file, to use the program default.

Select the class from the list of Synergy Classes.

In the Class Settings list, select the setting you want to delete.

Click the Delete button, and then click Yes at the confirmation prompt.

To delete a class

Deleting a class removes the class and all its settings from the config file. As a result, this class will use the settings from the default class or, if there is no default class, it will use the program defaults.

Select the class from the list of Synergy Classes.

Click the Delete Class button, and then click Yes at the confirmation prompt.