Using the Caché Gateway for .NET
Setting Gateway Server Properties
Using the New Object Gateway Form
While it is possible to specify the settings for a .NET Gateway Server session entirely in ObjectScript code, it is usually simpler to use the New Object Gateway form to create and store a persistent %Net.Remote.ObjectGateway
object. The following steps summarize the configuration procedure:
In the Management Portal, go to [System Administration] > [Configuration] > [Connectivity] > [Object Gateways]
The Object Gateways Page
You can use the options on this page to view a Gateway's log of recent activity, start or stop a Gateway, and create, edit, or delete a Gateway Server definition.
On the Object Gateways
page, click Create New Gateway
. The New Object Gateway form is displayed. Only the first three fields are required. The following example leaves the default values in place for all fields except Gateway Name
, and Log file
is set to the value that would be used if the field were left blank):
The New Object Gateway Form
Fill out the form and click Save
. The following properties of ObjectGateway
can be set:
. A name that you assign to this .NET Gateway definition.
. IP address or name of the machine where the .NET Gateway server executable is located. The default is "127.0.0.1"
If this property is checked, the Gateway will require a passphrase to connect.
Full pathname of the file used to log .NET Gateway messages. These messages include acknowledgment of opening and closing connections to the server, and any difficulties encountered in mapping .NET classes to Caché proxy classes. This optional property should only be used when debugging.
IP address of the local network adapter to which the server listens. Specify 0.0.0.0
(the default) to listen on all IP adapters on the machine (including 127.0.0.1, VPNs, and others) rather than just one adapter. You may not enter more than one address; you must either specify one local IP address, or listen on all of them. You must provide a value for this argument if you define the LogFile
Specifies the full path of the directory where the .NET Gateway server executable is located. This is used to find the target executable and assemble the command to start the .NET Gateway on a local server, and is required only when you want to use an executable that is not in the default location. If you do not specify this setting, the form will use the appropriate default executable for your system and your specified .NET Version.
(applies only to .NET Gateways on 64-bit platforms) If this property is checked, the Object Gateway server will be executed as 64-bit. Defaults to 32-bit execution.
Number of seconds between each communication with the .NET Gateway to check whether it is active. A value of 0 disables this feature. When enabled, valid values are from 1 to 3600 seconds (1 hour). The default is 10 seconds.
Number of seconds to wait for a heartbeat response before deciding that the .NET Gateway is in failure state. If this value is smaller than the HeartbeatInterval
property, the Gateway is in failure state every time the .NET Gateway communication check fails. The maximum value is 86400 seconds (1 day). The default is 30 seconds.
Action to take if the .NET Gateway goes into a failure state. Valid values are "R"
(Restart) or "N"
(None). The default action is Restart, which causes the .NET Gateway to restart.
Number of seconds to wait before retrying the HeartbeatFailureAction
if the .NET Gateway server goes into failure state, and stays in failure state. A value of 0 disables this feature, meaning that once there is a failure that cannot be immediately recovered, there are no attempts at automatic recovery. Valid values when enabled are from 1 to 86400 (24 hours). The default is 300 seconds (5 minutes).
Number of seconds to wait for a response during initialization of the Gateway server. Valid values are from 2 to 300 (5 minutes). The default is 5 seconds.
Number of seconds to wait for a connection to be established with the Gateway server. Valid values are 2 through 300 (5 minutes). The default is 5 seconds.
After saving the form, go back to the Object Gateways page. Your new .NET Gateway Server definition should now be listed there.
Defining Server Properties Programmatically
server properties can also be set programmatically.
In addition to the properties defined by the New Object Gateway form (as shown in the previous section), the Type
property must also be set to "2"
. This defines the server as a .NET Gateway (as opposed to an Ensemble Java Gateway
, which cannot be used in Caché).
The following example creates a server definition identical to the one generated by the New Object Gateway form described in the previous section:
// Create the object and define it as a .NET Gateway
set gw = ##class(%Net.Remote.ObjectGateway).%New()
set gw.Type = "2" // a .NET Gateway, not an Ensemble Java Gateway
// Set the properties
set gw.Name = "GatewayTwo"
set gw.Server = "127.0.0.1"
set gw.Port = "55000"
set gw.PassPhrase = 1
set gw.LogFile = "C:\Temp\GatewayTwo.log"
set gw.AllowedIPAddresses = "0.0.0.0"
set gw.FilePath = "C:\Intersystems\Cache\dev\dotnet\bin\v2.0.50727"
set gw.Exec64 = 1
set gw.DotNetVersion = "2.0"
set gw.HeartbeatInterval = "10"
set gw.HeartbeatFailureTimeout = "30"
set gw.HeartbeatFailureAction = "R"
set gw.HeartbeatFailureRetry = "300"
set gw.InitializationTimeout = "5"
set gw.ConnectionTimeout = "5"
// Save the object
set status = gw.%Save()
The call to %Save()
is only necessary if you wish to add the object to persistent storage, making it available on the Object Gateways page of the Management Portal (as described in the previous section).
Different versions of the .NET Gateway Server assembly are provided for .NET 2.0 and 4.0. The following versions are shipped (where install-dir
is the path that $SYSTEM.Util.InstallDirectory()
returns on your system).
In some applications, these gateways may be used to load unmanaged code libraries. Since a 64-bit process can only load 64-bit DLLs and a 32-bit process can only load 32-bit DLLs, both 32-bit and 64-bit assemblies are provided for each supported version of .NET. This makes it possible to create gateway applications for 64-bit Windows that can load 32-bit libraries into the gateway.
The appropriate version of the .NET Framework must be installed on your system in order to use these assemblies. The Caché installation procedure does not install or upgrade any version of the .NET Framework.