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 9.5.1.n 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="9.5.1.n" />
<codeBase version="9.5.1.n"
href="file:///C:\SoftwareAG\EntireX\bin\SoftwareAG.EntireX.NETWrapper.Runtime.dll"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
Note:
The <runtime> configuration fragment
must come after the <configSections>
and <appSettings> sections of the
configuration file, otherwise the .NET 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.
<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. See URL-style Broker ID. |
| 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". |
| 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. |
| encryptionLevel | Specifies the encryption level used for the Broker. Possible values are 0,1,2. See ENCRYPTION-LEVEL.
|
| forceLogon | Specifies whether a forceLogon should be performed. Possible values are "true" and "false". The default value is "false". |
| 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="locationTransparency" value="false" /> <add key="locationTransparencySet" value="DefaultSet" /> <add key="userID" value="NET-USER" /> <add key="password" value="NET-PASS" /> <add key="compression" value="NO_COMPRESSION" /> <add key="encryptionLevel" value="0" /> <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". |
| encryption | Specifies whether the data sent to the RPC Server should be
encrypted. Possible values are "true" and "false". The default value is "false". Note: |
| 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. |
<Service> <!-- EntireX Service Configuration --> <add key="name" value="RPC/SRV1/CALLNAT" /> <add key="locationTransparency" value="false" /> <add key="locationTransparencySet" value="DefaultSet" /> <add key="libraryName" value="" /> <add key="naturalLogon" value="false" /> </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="locationTransparency" value="false" />
<add key="locationTransparencySet" value="DefaultSet" />
<add key="userID" value="NET-USER" />
<add key="password" value="NET-PASS" />
<add key="compression" value="NO_COMPRESSION" />
<add key="encryptionLevel" value="0" />
<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="locationTransparency" value="false" />
<add key="locationTransparencySet" value="DefaultSet" />
<add key="libraryName" value="" />
<add key="naturalLogon" value="false" />
</Service>
</EntireX>
<appSettings>
<!-- other app settings go here -->
</appSettings>
</configuration>
The requirements for the .NET RPC Server are: the EntireX RPC Server (rpcserver.exe), dotNetServer.dll and dotNetServer.cfg from the EntireX bin directory, Software AG's .NET Wrapper (SoftwareAG.EntireX.NETWrapper.Runtime.dll) and a .NET Server DLL (Assembly).
See Administering the EntireX RPC Server.
Before starting the EntireX RPC server, ensure that all dynamically loaded objects (server stubs and server) can be accessed using the search path.
To start the EntireX RPC server manually
Use the format
RPCserver CFG=<name> [-option] [Brokerid] [Class] [ServerName] [Service]
where <name> determines the configuration file in use.
Options:
-smhport number
Sets the RPC server parameter smhport to
number. Typically used by SMH Facility.
-serverlog <file>
Defines
an alternative log file for Window services. Typically used by Windows Services.
See Running an EntireX RPC Server as a Windows Service in the Windows administration documentation.
-s[ilent]: Run server in silent mode, that is: no terminal input will be required (e.g. acknowledge error messages). The job will terminate automatically. Recommended for background jobs.
-TraceDestination <file>
Set
the trace destination parameter.
-TraceLevel None.Standard.Advanced. Set the trace level parameter.
Note:
The server input arguments will be resolved from left to right. Thus
parameters that can be applied on the command line as well in the
configuration file may be overriden.
To start the EntireX RPC server using Windows services
See Running an EntireX RPC Server as a Windows Service in the Windows administration documentation.
Note:
For reasons of compatibility with versions before 5.1.1, the old command
to start the server
RPCserver <Brokerid> <Class> <ServerName> <Service>
will continue to be supported. However, a server started with this call
will use the default parameters. Parameters other than Broker
ID, Class,
ServerName, Service require the
CFG= form of the server start command.
To start the EntireX RPC server using System Mangagement Hub
See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows for information on adding an EntireX RPC server to the System Management Hub.
The System Management Hub facility "Adding a Local RPC Server" will use the batch script startcserver.bat of the EntireX Installation to apply the server parameters. Change the batch script according to your system installation or add parameters to the System Management Hub "Start Command" input property.
To stop the EntireX RPC server
Use one of the System Management Hub functions Deregister a Service or Deregister a Server. This method ensures that the deregistration from the Broker will be complete and correct.
See also EntireX RPC Server Return Codes.
A file that corresponds to dotNetServer.cfg must be used as configuration file (configuration of the EntireX RPC Server for use with the .NET Wrapper). The .NET Server Assembly (containing one IDL library) will then be loaded when a program from this library is first accessed. With the .NET Framework there are two distinct ways to locate the .NET Server Assembly:
If the rpcserver.exe, our .NET Wrapper and the .NET Server Assembly are all in the same directory, the .NET Server Assembly will also be loaded from this directory.
If rpcserver.exe, our .NET Wrapper and the .NET Server Assembly are in different libraries, the rpcserver.exe must be configured in the context of the .NET Framework (Configuring the EntireX RPC Server for the .NET Framework). The Server Assembly must also have a strong name. This is described in the Microsoft documentation for the .NET Framework (in our example server in EntireXDir\Examples\NET Wrapper\server\calc the Server Assembly has a strong name and in Configuring the EntireX RPC Server for use with the .NET Framework).
Whereas method 1 is very well suited for test and development purposes, method 2 is to be recommended for more complex production environments. The user can decide which method to use.
For the EntireX RPC Server to function with the .NET Wrapper properly, the file dotNetServer.cfg from the installation or a similar file, should be used. The entries
Class=RPC
ServerName=dotNetServer
Service=CALLNAT
CallExit=dotNetServer
RunOption=Reset
should not be changed or deleted. No other run options should be added. All of the other settings for the configuration of an EntireX RPC Server are available. See Administering the EntireX RPC Server.
Note:
Any server name can be used. However, we recommend using the name
dotNetServer to distinguish this one from any other RPC
servers.
Due to an incompatibility of the .NET Framework 2.0 to the earlier versions, we had to add an additional section in the configSections part of rpcserver.exe.config:
<configSections>
<!-- EntireX Configuration Section Group Definition -->
<sectionGroup name="EntireX">
<section name="Assemblies" type="System.Configuration.NameValueSectionHandler, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089, Custom=null" />
</sectionGroup>
</configSections>
<EntireX>
<!-- EntireX Assembly Configuration -->
<Assemblies>
<add key="SoftwareAG.EntireX.NETWrapper.Runtime" value="C:\SoftwareAG\EntireX\bin\SoftwareAG.EntireX.NETWrapper.Runtime.dll" />
</Assemblies>
</EntireX>
where the location of our .NET Runtime is replaced by the location used in your EntireX installation. Add an entry in the Assemblies section for each of your server assemblies:
<add key="MyAssembly", value="MyLocation"/>
where MyAssembly and MyLocation represent the name and location of your server assembly. If versioning is required for your assemblies, follow the rules under Assembly Versioning.