This document covers the following topics:
Most applications require some configuration parameters that represent durable applications or user preferences.
The .NET framework includes configuration functionality that loads an application's configuration automatically at runtime without programmer intervention. For a standalone application, named, for example, myapp.exe you must name the configuration file (containing configuration settings in a given XML format) myapp.exe.config. The framework will then be able to load and parse the configuration file automatically when myapp.exe is run. For an ASP.NET Web application the configuration file is named web.config.
.NET Framework assemblies support a strong versioning concept. The specific version of an assembly and the versions of dependent assemblies are recorded in the assembly's manifest. The versions of the dependent assemblies to be loaded at runtime are determined depending on the version policy in effect.
The default version policy is that applications run only with the exact versions of dependent assemblies they were built with. Thus applications that are deployed together with their dependent assemblies are not affected by newer or older versions of some of these assemblies. However, it is sometimes desirable to update an assembly with a newer version. In order to make this possible, the default version policy can be overridden by explicit version policies specified in configuration files, for example, the application configuration file (<appname>.exe.config or web.config for Web applications), the computer's machine configuration file (machine.config) or a publisher's policy file.
The following example shows a configuration file fragment that, when placed in a standalone application's <appname>.exe.config file or a Web application's web.config file or in the machine.config file, directs the .NET runtime loader to load version 10.3.0.0 of the .NET Wrapper runtime whenever earlier versions in the range 7.1.1.0-7.2.1.73 are required.
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="SoftwareAG.EntireX.NETWrapper.Runtime"
publicKeyToken="645917c53ee5c617" />
<bindingRedirect oldVersion="7.1.1.0-7.2.1.73" newVersion="10.3.0.0" />
<codeBase version="10.3.0.0"
href="file:///C:\SoftwareAG\EntireX\bin\SoftwareAG.EntireX.NETWrapper.Runtime.dll"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
Notes:
<inst_root>\EntireX\bin (64-bit)
<inst_root>\EntireX\bin\x86 (32-bit)
runtime configuration fragment must come after the configSections and appSettings sections of the configuration file, otherwise the .NET Wrapper Runtime will report errors.
See also the Microsoft .NET Framework documentation on assembly versioning.
The .NET Wrapper Runtime supports the .NET framework configuration mechanism for several EntireX Broker and (RPC) Service class properties. By making use of this configuration mechanism, .NET Wrapper client applications can avoid constructing Broker and Service objects explicitly and leave this task to the .NET Wrapper Runtime.
There is one section group named EntireX with the two sections Broker and Service where you can specify the settings for EntireX .NET Wrapper Broker and Service class instances respectively. This section covers the following topics:
<sectionGroup name="EntireX"> <!-- EntireX Configuration Section Group Definition -->
<section name="Broker" type="System.Configuration.NameValueSectionHandler" />
<section name="Service" type="System.Configuration.NameValueSectionHandler" />
</sectionGroup>
For an ASP.NET web.config configuration file, the parameters of the NameValueSectionHandler that processes the configuration must be specified in more detail.
<sectionGroup name="EntireX">
<section name="Broker" type="System.Configuration.NameValueSectionHandler,
System,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089,Custom=null" />
<section name="Service" type="System.Configuration.NameValueSectionHandler,
System,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089,Custom=null" />
</sectionGroup>
If the default constructor Broker() is used to construct a Broker object, i.e. if there is no Broker name (or Broker ID) supplied, then the application's configuration file is examined for configuration settings to be taken as values. If no entry is found for a given setting name, the default values listed in the table below will apply.
The following can be configured for Broker instances:
| Key | Description |
|---|---|
| name | Specifies the Broker name (or Broker ID). The default value is
"localhost:1971". Only the URL-style Broker ID is supported.
For secured brokers, the host name starts with "ssl://...".
See Examples.
|
| userID | Specifies the user ID to be used to connect to the Broker; The default value is "NET-USER". |
| password | Specifies the password to be used to connect to the Broker. This
setting is only considered when userID is also specified. The default value is "NET-PASS". |
| securedPassword | The password will be encrypted when the application is started and will be replaced by a secure password in the configuration file. This secured password is re-generated every time the password is specified again. |
| compression | Specifies whether the data sent to the Broker should be
compressed. Possible values are:
The default value is NO_COMPRESSION. Use either Compression or CompressionLevel. |
| compressionLevel | Specifies what compression level should be used. Possible values are in the range 0 to 9 (see CompressionLevel property in the Broker class). Use either Compression or CompressionLevel. |
| forceLogon | Specifies whether a forceLogon should be performed. Possible values are "true" and "false". The default value is "false". For details see |
| token | Specifies a token value to be used in conjunction with the user
ID. The default value is "". |
<Broker> <!-- EntireX Broker Configuration --> <add key="name" value="localhost:1971" /> <add key="userID" value="NET-USER" /> <add key="password" value="NET-PASS" /> <add key="compression" value="NO_COMPRESSION" /> <add key="forceLogon" value="false" /> <add key="token" value="top secret" /> </Broker>
If the default constructor Service() is used to construct a Service object, i.e. there is no Service name (class/server/service) supplied, then the application's configuration file is examined for configuration settings to be taken as values. If no entry is found for a given setting name, then the default values apply as listed below.
The following can be configured for Service instances.
| Key | Description |
|---|---|
| name | Specifies the name of the service. Default value is "RPC/SRV1/CALLNAT". |
| naturalLogon | Specifies whether a Natural logon should be performed. Possible values are "true" and "false". The default value is "false". |
| userID | Specifies the user ID to be used to connect to the RPC Server. |
| password | Specifies a password to be used to connect to the RPC Server. This setting is only considered when userID is also specified. |
| securedPassword | The password will be encrypted when the application is started and will be replaced by a secure password in the configuration file. This secured password is re-generated every time the password is specified again. |
| timeout | Sets or retrieves the timeout value for a given Service instance. timeout = 0 is invalid. If 0 is set, a default of 50 seconds will be used.
|
| encoding | Define an encoding for character translation. Default is System.Text.Encoding.GetEncoding(0) (current locale).
See also the .NET Framework class library documentation for System.Text.Encoding.
|
<Service> <!-- EntireX Service Configuration --> <add key="name" value="RPC/SRV1/CALLNAT" /> <add key="libraryName" value="" /> <add key="naturalLogon" value="false" /> <add key="timeout" value="100" /> <add key="encoding" value="iso-8859-1" /> </Service>
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<sectionGroup name="EntireX"> <!-- EntireX Configuration Section Group Definition -->
<section name="Broker" type="System.Configuration.NameValueSectionHandler" />
<section name="Service" type="System.Configuration.NameValueSectionHandler" />
</sectionGroup>
</configSections>
<EntireX>
<!-- EntireX Configuration Section -->
<Broker>
<!-- EntireX Broker Configuration -->
<add key="name" value="localhost:1971" />
<add key="userID" value="NET-USER" />
<add key="password" value="NET-PASS" />
<add key="compression" value="NO_COMPRESSION" />
<add key="forceLogon" value="false" />
<add key="token" value="top secret" />
</Broker>
<Service>
<!-- EntireX Service Configuration -->
<add key="name" value="RPC/SRV1/CALLNAT" />
<add key="libraryName" value="" />
<add key="naturalLogon" value="false" />
</Service>
</EntireX>
<appSettings>
<!-- other app settings go here -->
</appSettings>
</configuration>
Configuring a .NET Server assembly is described under Locating and Calling the Target Server in the RPC Server for .NET documentation. See also Writing a .NET Server Assembly.