Using the Object Gateway for .NET
Using the Object Gateway in a Production
|
|
This chapter describes how to use the Object Gateway within a production.
There are different ways to invoke the basic Object Gateway
Start,
Connect,
Import,
Disconnect, and
Stop commands. Practical approaches to this functionality include:
This chapter describes each approach and explains how to work with it. Related topics include:
While it is possible to start the Object Gateway server from the command prompt, the simplest way to use the Object Gateway with a production is to configure the
EnsLib.DotNetGateway.Service class as a business service within the production. You can only do this if the Object Gateway server is on the local machine where you are running the production.
Otherwise, you need to start the Object Gateway server from the command prompt. For details, see the
Using the Command Prompt section.
-
From the Management Portal main menu, choose
.
-
Find your production in the list and click
Configure beside its name.
-
Click
Add Service to start the Business Service Wizard.
-
-
Click
OK to display the updated production diagram that now contains the Object Gateway business service. Click the
EnsLib.DotNetGateway.Service box to configure it.
IP address or name of the machine where the Object Gateway server executable is located.
TCP port number for communication between the Object Gateway server and the proxy classes in the production. The default is
55000.
Location of the Object Gateway server executable. It is used to find the target executable and assemble the command to start the Object Gateway on a local server. If you do not specify this setting, the service uses the default directory
...\Dev\dotnet\bin\ under the installation directory.
IP addresses allowed to connect to the Object Gateway server. If this setting is
0.0.0.0 (default) or
"", any system (local or remote) may connect; otherwise any listed IP addresses are allowed to connect.
If you select this check box, the business service uses the 64–bit version of the Object Gateway executable. Otherwise, it uses the 32–bit version of the executable. This setting is available only on Windows 64-bit platforms.
Select the .NET version to use: 2.0 or 4.0.
Full pathname of the file where the Object Gateway logs messages. These messages include acknowledgment of opening and closing connections to the server, and any difficulties encountered in mapping .NET classes to proxy classes.
Number of seconds between each communication with the Object Gateway to check whether it is active. When enabled, the minimum value is 5 seconds and the maximum value is 3600 seconds (1 hour). The default is 10 seconds. A value of 0 disables this feature.
Heartbeat Failure Timeout
Number of seconds without responding to the heartbeat, to consider that the Object Gateway is in failure state. If this value is smaller than the
HeartbeatInterval property, the gateway is in failure state every time the Object Gateway communication check fails. The maximum value is 86400 seconds (1 day). The default is 30 seconds.
Action to take if the Object Gateway goes into a failure state. Setting it to Restart (default) causes the Object Gateway to restart. Setting it to Alert generates an alert entry in the Event Log. This is independent of the
Alert on Error setting.
Time to wait before retrying the
HeartbeatFailureAction if the Object Gateway server goes into failure state, and stays in failure state. The default is 300 seconds (5 minutes). 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.
Once you have added and configured the Object Gateway business service, it automatically manages the Object Gateway as follows:
-
When the production starts, the Object Gateway business service starts an instance of the Object Gateway server, using the settings that you specify on the configuration page.
-
When the production receives a signal to stop, the Object Gateway business service attaches to the Object Gateway server and instructs it to stop, as well.
The Object Gateway business service provides methods that you can use to start, connect to, and stop the Object Gateway engine. You can call the following methods from the production code after you have configured the Object Gateway business service as a member of the production:
EnsLib.DotNetGateway.Service:StartGateway(pFilePath As %String,
pPort As %String,
pAllowedIPAddresses As %String,
pLogfile As %String = "",
ByRef pDevice As %String = "",
pServer As %String = "127.0.0.1",
pCmdLine As %String = "")
This class method starts the Object Gateway server using the specified arguments. If
pLogFile specifies a valid file name, then messages regarding gateway activities are written to this file. These messages include acknowledgment of opening and closing connections to the server, and difficulties encountered (if any) in mapping .NET classes to the production proxy classes.
EnsLib.DotNetGateway.Service:ConnectGateway(pEndpoint As %String,
ByRef pGateway As %Net.Remote.Gateway,
pTimeout As %Integer = 5,
pAdditionalPaths As %String = "")
This class method connects to the Object Gateway server at the specified
pEndpoint (hostname:port:namespace).
EnsLib.DotNetGateway.Service:StopGateway(pPort As %String,
pServer As %String = "127.0.0.1",
pTimeout As %Integer = 5)
This class method connects to the Object Gateway server and shuts it down.
Call the
GetConnection() method to verify there is a valid Object Gateway connection. For example:
Set tSC = ..GetConnection(.tGateway)
If $$$ISOK(tSC) {
// Start using the Object Gateway connection object tGateway
...
}
This method returns a private gateway connection object to be used with the proxy classes.
You can configure the Object Gateway IP address and port in the business operation settings when you add the business operation to the production. Note that the connection to the Object Gateway instance is made during
OnInit() and closed in
OnTearDown(). You must override these methods in the business operation class to implement your own setup and tear down procedures.
In addition to using connect, disconnect, and stop from the business service, the following methods are also available in the
%Net.Remote.Gateway class. You can use them when the business service model is not appropriate for your situation:
-
-
The
%Import method, which imports .NET classes or assemblies from the .NET and generates all the necessary proxy classes for the InterSystems IRIS™ side.
-
-
Method %Connect(host As %String,
port As %Integer,
namespace As %String,
timeout As %Numeric = 5,
additionalClassPaths As %ListOfDataTypes = "")
As %Status [ Final ]
The
%Connect() method establishes a connection with the Object Gateway engine. It accepts the following arguments:
Method %Disconnect() As %Status [ Final ]
The
%Disconnect() method closes a connection to the Object Gateway engine.
Method %Shutdown() As %Status [ Final ]
The
%Shutdown() method shuts down the Object Gateway engine.
Method %Import(class As %String,
ByRef imported As %ListOfDataTypes,
additionalClassPaths As %ListOfDataTypes = "",
exclusions As %ListOfDataTypes = "")
As %Status [ Final ]
%Import() is a onetime, startup operation. It only needs to be called the first time you wish to generate the proxy classes. It is necessary again only if you recompile your .NET code and wish to regenerate the proxies. The following sections provide further details about the
%Import() method:
Before you invoke
%Import(), prepare the
additionalClassPaths and
exclusions arguments. That is, for each argument, create a new
%ListOfDataTypes object and call its
Insert() method to fill the list. The optional
additionalClassPaths argument can be used to supply additional path arguments, such as the names of additional assembly DLLs that contain the classes you are importing via the Object Gateway. List elements should correspond to individual additional assembly DLL entries, which require the following format:
" rootdir\...\mydll.dll "
You can try to load an assembly from a directory outside of where
DotNetGatewaySS.exe is running, but you might experience a load error for your assembly when you try to use a class in the assembly. InterSystems recommends that you put all local assemblies in the same directory as
DotNetGatewaySS.exe. You can also specify assemblies in the GAC by using partial names for them,
System.Data, for example.
Import Dependencies and Exclusions
While mapping a .NET class into a proxy class and importing it into InterSystems IRIS, the Object Gateway loops over all class dependencies discovered in the given .NET class, including all classes referenced as properties and in argument lists. In other words, the Object Gateway collects a list of all class dependencies needed for a successful import of the given class, then walks that dependency list and generates all necessary proxy classes.
You can control this process by specifying a list of assembly and class name prefixes to exclude from this process. While this situation would be rare, it does give you some flexibility to control what classes get imported. The Object Gateway automatically excludes a small subset of assemblies such as
Microsoft.* assemblies.
ClassMethod %ExpressImport(name As %String,
port As %Integer,
host As %String = "127.0.0.1",
silent As %Boolean = 0,
additionalClassPaths As %ListOfDataTypes = "",
exclusions As %ListOfDataTypes = "")
As %Status [ Final ]
%ExpressImport() is a one-step convenience class method that combines calls to
%Connect(),
%Import(), and
%Disconnect(). It returns a list of generated proxies. It also logs that list, if the
silent argument is set to 0. The
name argument is a semicolon-delimited list of classes or assembly DLLs.
%GetAllClasses(jarFileOrDirectoryName As %String,
ByRef allClasses As %ListOfDataTypes)
As %Status
This method returns, in the ByRef argument
allClasses, a list of all public classes available in the assembly DLL specified by the first argument,
jarFileOrDirectoryName.
Usually you start and stop the Object Gateway server automatically, by configuring the
EnsLib.DotNetGateway.Service business service as a member of the production. Once this is done, the Object Gateway server starts and stops automatically with the production. The
StartGateway() class method is also available to manually start the Object Gateway server.
DotNetGatewaySS 55000 "" ./gatewaySS.log
Note:
When using classes in local side-by-side assemblies (assemblies are not installed into the GAC), run
DotNetGatewaySS.exe from the same directory as those assemblies to resolve their dependencies.
You can import a DLL assembly file from .NET and create a set of corresponding classes using the .NET Object Gateway wizard built into Studio. To start the wizard:
-
-
From the
menu, point to and click
.
-
-
Enter the path and name of a DLL assembly file; or click
Browse to help navigate to one.
-
-
-
Click
Next to generate proxy classes. The wizard displays the class name as it generates each proxy class.
-
When the import operation is complete, click
Finish to exit the wizard.
The Object Gateway provides error checking as follows:
-
When an error occurs while executing proxy methods, the error is, in most cases, a .NET exception, coming either from the original .NET method itself, or from the Object Gateway engine. When this happens, an error is trapped.
-
In both cases, InterSystems IRIS records the last error value returned from a .NET class (which in many cases is the actual .NET exception thrown) in the local variable
%objlasterror.
Do $system.OBJ.DisplayError(%objlasterror)
Should you encounter problems while using the Object Gateway it is always a good idea to turn logging on. That might be necessary for InterSystems staff to help you troubleshoot problems. To activate logging, simply identify a log file when you start the Object Gateway. You can do this whether you start from the command line or use the
StartGateway() API method.
Sometimes, while using the Object Gateway in a debugging or test situation, you may encounter problems with a Terminal session becoming unusable, or with write errors in the Terminal window. It is possible that a Object Gateway connection terminated without properly disconnecting. In this case, the port used for that connection may be left open.
If you suspect this is the case, to close the port, type the following command at the Terminal prompt:
Where
port is the port number to close.