Server Configuration via .config

Remoting SDK for .N ET provides a server configuration infrastructure that makes it easy to manage server application's network connectivity parameters.

This feature allows to set up the server connectivity parameters using the standard .net .exe.config file, so there is no need anymore to rebuild the server application to change the Server Channel port, its type (i.e. protocol), or even to change the session storage from memory to, say, Olympia Server.

And of course the configurted components can still be accessed via code and customized, if needed.

Network connectivity components and options that can be configured include server channel, one or more server messages, session manager, event sink, event queue manager, TLS, and ZeroConf support component.

Sample Server Application

To create the sample server application please follow the Creating a new Remoting SDK Server tutorial.

When done, add an "Application Configuration File" item to the server app project via the provided template, and add there following settings:

<?xml version="1.0"?>
<configuration>
 <configSections>
   <section name="ServerConfiguration" type="RemObjects.SDK.Server.ServerConfigurationSection,RemObjects.SDK.Server" />
 </configSections>
 <ServerConfiguration>
   <ServerChannel type="superhttp" port="8101" enableZeroConf="true" />
   <ServerMessages>
     <ServerMessage type="bin" />
     <ServerMessage type="soap" />
   </ServerMessages>
   <SessionManager type="Memory" />
 </ServerConfiguration>
</configuration>

Note: To ensure that .NET application config file handlers will be able to properly load custom config sections set the "Copy Local" property of all referenced RemObjects SDK assemblies to true.

After restarting the server, it will expose its services via a SuperHttp Server Channel listening on port 8101. And this without single code line changed.

Now it is possible to change Server Channel protocol (Http, SuperHttp, Tcp, SuperTcp), port it is listening to and other options without need to rebuild the server application.

Limitations

There are some limitations you should be aware of:

  • Options set in code cannot be overridden via the configuration file. This means that if the Program file contains code like server.NetworkServer.ServerChannel = new IpSuperHttpServerChannel(); then it won't be possible to change the server's channel type via its configuration file.

TLS-related options are available in the configutation file only starting from version 9.0.97.

Available Options

The ServerConfiguration can contain the following configuration entries:

Entry Description
ServerChannel Required Contains settings for the server channel.
ServerMessages Optional Contains settings for one or more server messages. By default Binary message is used.
SessionManager Optional Contains settings for the session manager. By default the in-memory session maanger is used.
JavaScriptDispatcher Optional Contains settings for the Java Script dispatcher. By default this dispatcher is disabled.
SslOptions Optional Contains settings for the SSL server channel protection. By default this protection is disabled.

All options are described in more details below.

ServerChannel

This section provides settings needed to configure the server communication channel. Note that some of the options that can be defined in this section are not applicable to some of the available channel types. In case such option is provided it will be ignored, no exception will be raised at run-time.

Available options:

Option Possible values Description
type Http, SuperHttp, Tcp, SuperTcp, SysHttp, SysSuperHttp, NamedPipe, Custom *Required. Type of the server channel.
port 1-65535 Server port. Specifies port the server application will accept connections to. The default value is 8099. Not applicable to the NamedPipe server channel type.
enableZeroConf true, false Defines whether the server application should register its services in the ZeroConf environment. Not applicable to the NamedPipe, SysHttp and SysSuperHttp server channel types. The default value is false
sendClientAccessPolicyXml true, false Defines whether the server application should expose the ClientAccessPolicy.xml resource allowing access to the server servcies. Applicable only to the Http, SuperHttp, SysHttp and SysSuperHttp server channel types. The default value is false
sendCORSHeader true, false Defines whether the server application should accept CORS requests. Applicable only to the Http, SuperHttp, SysHttp and SysSuperHttp server channel types. The default value is false
namedPipeServer Specifies the name of the host running the server. This can be a host name or IP address on the local network, or ".", which indicates the local machine. Applicable only to the NamedPipe server channel type. The default value is .
namedPipePath Defines the unique name of the server to use. The name must match the Path property specified on the Named Pipe client channel in the client application. Applicable only to the NamedPipe server channel type. The default value is DefaultServer

ServerMessages

This configuration node can contain one or more ServerMessage entries defining server messages.

Available options:

Option Possible values Description
type Bin, SOAP, POST, JSON, XmlRpc, Custom Required. Type of the server message.
maxMessageSize Integer value Defines maximal size of the Binary data stream that is accepted by the server. Setting this option to 0 or -1 will disable the message size check. The default value is 5242880. Applicable only to the Bin message type.
password Defines AES password used to encrypt the server-client communications. AES encryption is not used when this property is not set. The default value is an empty string.
soapMode DocumentLiteral, RPCEncoding, RPCLiteral, Unknown Mode of the SOAP serializer/deserializer used to process client-server communications. Applicable only to the SOAP message type. The default value is DocumentLiteral
wrapResult true, false Defines whether the server operation should be wrapped into an object when the result is sent to the client application. For example an operation result would look like {result: 2} when wrapResult is set to false and{result: {Result:2}} when set to true. Applicable only to the JSON message type. The default value is false. Note: This option has to be set to true to allow JavaScript-based clients to consume server data.

SessionManager

This section provides settings needed to configure the Session Manager used by the server application.

Available options:

Option Possible values Description
type Memory, Olympia, Custom Required. Type of the session manager used. The default value is Memory
timeout Integer value Session timeout is seconds. Applicable only to the Memory session manager. The default value is 600
id Appplication Id Application Id used by the Olympia Server server to prevent the server application from accessing session data that doesn't belong to it. Has to be a valid GUID string. Applicable only to the Olympia session manager.
olympiaHost Hostname or IP address of the Olympia Server. Applicable only to the Olympia session manager. The default value is 127.0.0.1.
olympiaPort Integer value Port of the Olympia Server. Applicable only to the Olympia session manager. The default value is 8011.

JavaScriptDispatcher

This configuration node should contain one or more entries defining JavaScript Dispatcher options.

Please note that JavaScript Dispatcher can be enabled only on Http-based channels.

Available options:

Option Possible values Description
enabled true, false Flag indicating whether JavaScript Dispatcher itself should be enabled or not. The default value is false
defaultFile Name of the file that is sent to the client when it tries to list folder contents (i.e. tries to access the server without providing requested file name). The default value is index.html.
path Path that should be used to access resources exposed by the JavaScript Dispatcher. The default value is /js/.
serveFilesFromFolder true, false Flag indicating whether JavaScript Dispatcher should provide access to a physical folder. The default value is false
folder Name of the folder used to provide resources to the JavaScript Dispatcher in case the serveFilesFromFolder option is set to true. The default value is html.
serveROJavaScript true, false Flag indicating whether JavaScript Dispatcher should provide access to the Remoting SDK for JavaScript scripts. The default value is true

SslOptions

This section provides settings needed to configure the optional SSL protection of the server's Server Channel.

Option Possible values Description
generateCertificate optional true, false When this option is set then the server will, if needed, generate a self-signed SSL certificate on the next run. If the certificate file already exists then a new one will not be generated. Setting this option to true also implicitly sets the option useTLS to true as well. The default value if false.
useTLS optional true, false Defines whether the server app should apply SSL protection to its server channel. The default value if false.
certificateFile optional Defines full path to the certificate file. The file should contain a SSL certificate with both public and private keys stored without password.
certificateThumbprint optional Defines certificate thumbprint for certificates stored in the Certificate Store.

Note: When both certificateFile and certificateThumbprint options are set, the certificate defined by the certificateFile will be used. Any options set in the Main method will override the option values set via the .config file. However if in the Main method the server.NetworkServer.UseTLS option is set to false, be sure to also add the line to set the server.AutoCreateSelfSignedCertificate option to false as well. Otherwise it will still be possible to enable the SSL protection using the self-signed certificate.

Advanced Features

While the Server Configuration infrastructure is aimed to be as simple as possible it still provides enough flexibility:

  • It is possible to fine-tune the created components (server channels, messages, etc) by overriding the NetworkServer.AfterConfiguration method.

  • The CreateCustomServerChannel, CreateCustomMessage, CreateCustomSessionManager and CreateCustomMessageQueue methods on the NetworkServer class allow to instantiate appropriate server connectivity component types that are not supported by the Server Configuration out-of-the-box (f.e. come custom SOAP message with extended data serialization options).

  • The LoadConfiguration method on the NetworkServer class allows to load custom server configuration (f.e. server configuration data could be loaded from a database or even from another server app)

Summary

The Server Configuration provides an easy way to manage server application's network connectivity parameters via its configuration file and to change them if needed without rebuilding the server application itself.

See Also