Configuring a .NET Wrapper Application

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.


Assembly Versioning

.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:

  1. After installation you will find the .NET Wrapper Runtime at the following locations:
    • <inst_root>\EntireX\bin (64-bit)

    • <inst_root>\EntireX\bin\x86 (32-bit)

  2. The 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.

Client Configuration

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:

Example

    <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>

Broker Configuration Section

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:
  • NO_COMPRESSION (CompressionLevel=0)

  • BEST_COMPRESSION (CompressionLevel=9)

  • DEFAULT_COMPRESSION (CompressionLevel=6) this.compression=Compression.DEFAULT_COMPRESSION;

  • BEST_SPEED (CompressionLevel=1)

  • DEFLATED (CompressionLevel=8)

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 FORCE-LOGON under Writing Applications using EntireX Security.

token Specifies a token value to be used in conjunction with the user ID.
The default value is "".

Broker Configuration Example

<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 Configuration Section

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 Configuration Example

<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>

Sample Configuration File

<?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>

Server 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.