Using the .NET Gateway in a Production

Creating a Business Service

While it is possible to start the .NET Gateway server from the command prompt, the simplest way to use the .NET Gateway with an Ensemble production is to configure the EnsLib.DotNetGateway.ServiceOpens in a new tab class as a business service within the production. You can only do this if the .NET Gateway server is on the local machine where you are running Ensemble.

Otherwise, you need to start the .NET Gateway server from the command prompt. For details, see the Using the Command Prompt section.

To configure the EnsLib.DotNetGateway.ServiceOpens in a new tab class as a business service:

1. From the Management Portal main menu, choose Productions.

2. Find your production in the list and click Configure beside its name.

3. Click Add Service to start the Business Service Wizard.

4. Click Other and in the ServiceClass list, click EnsLib.DotNetGateway.Service.

5. Click OK to display the updated production diagram that now contains the .NET Gateway business service. Click the EnsLib.DotNetGateway.Service box to configure it.

The wizard fills in the associated .NET Gateway adapter class. The Business Service Settings for the .NET Gateway section lists the configurable settings.

Calling Business Service Methods

The .NET Gateway business service provides methods that you can use to start, connect to, and stop the .NET Gateway engine. You can call the following methods from Ensemble code after you have configured the .NET Gateway business service as a member of the production:

• StartGateway()

• ConnectGateway()

• StopGateway()

See the EnsLib.DotNetGateway.ServiceOpens in a new tab entry in the Class Reference for details on these methods.

StartGateway() Method

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 .NET 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 Ensemble proxy classes.

ConnectGateway() Method

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 .NET Gateway server at the specified pEndpoint (hostname:port:namespace).

StopGateway() Method

EnsLib.DotNetGateway.Service:StopGateway(pPort As %String,
     pServer As %String = "127.0.0.1",
     pTimeout As %Integer = 5)

This class method connects to the .NET Gateway server and shuts it down.

Creating a Business Operation

An abstract business operation is available as a base for building .NET Gateway oriented business operations for Ensemble productions. You can simply subclass the abstract class EnsLib.DotNetGateway.AbstractOperationOpens in a new tab and implement the appropriate message handlers.

Call the GetConnection() method to verify there is a valid .NET Gateway connection. For example:

 Set tSC = ..GetConnection(.tGateway)
     If $$$ISOK(tSC) { 
        // Start using the .NET Gateway connection object tGateway 
      ... 
     }

This method returns a private gateway connection object to be used with the proxy classes.

You can configure the .NET 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 .NET 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.

See the EnsLib.DotNetGateway.AbstractOperationOpens in a new tab entry in the Class Reference for details on these methods and also the AdditionalPaths, ConnectTimeout, DotNetServer, and Port properties.

Calling API Methods

In addition to using connect, disconnect, and stop from the business service, the following methods are also available in the %Net.Remote.GatewayOpens in a new tab class. You can use them when the business service model is not appropriate for your situation:

The %Net.Remote.GatewayOpens in a new tab class provides the following types of methods:

• API methods that let you %Connect to the .NET Gateway server, %Disconnect from it, and %Shutdown the .NET Gateway server.

• The %Import method, which imports .NET classes or assemblies from the .NET and generates all the necessary proxy classes for the Ensemble side.

• The %ExpressImport method, which combines calls to %Connect, %Import, and %Disconnect.

• The utility method %GetAllClasses.

%Connect() Method

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 .NET Gateway engine. It accepts the following arguments:

Argument	Description
host	Identifies the machine on which the .NET Gateway server is running.
port	Port number over which the proxy classes communicate with the .NET classes.
namespace	Ensemble namespace.
timeout	Number of seconds to wait before timing out, the default is 5.
additionalClassPaths	Optional — use this argument to supply additional class paths, such as the names of additional assembly DLLs that contain the classes you are importing via the .NET Gateway. See the Import Arguments section for details using this argument.

%Disconnect() Method

Method %Disconnect() As %Status [ Final ]

The %Disconnect() method closes a connection to the .NET Gateway engine.

%Shutdown() Method

Method %Shutdown() As %Status [ Final ]

The %Shutdown() method shuts down the .NET Gateway engine.

%Import() Method

Method %Import(class As %String,
               ByRef imported As %ListOfDataTypes,
               additionalClassPaths As %ListOfDataTypes = "",
               exclusions As %ListOfDataTypes = "")
    As %Status [ Final ]

The %Import() method imports the given class and all its dependencies by creating and compiling all the necessary proxy classes. The %Import() method returns, by reference, a list (in imported) of generated Ensemble proxy classes. For details of how .NET class definitions are mapped to Ensemble proxy classes, see the “Mapping Specification” chapter in Using the Caché Gateway for .NET guide.

%Import() is a onetime, startup operation. It only needs to be called the first time you wish to generate the Ensemble 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:

• Import Arguments

• Import Dependencies and Exclusions

Import Arguments

Before you invoke %Import(), prepare the additionalClassPaths and exclusions arguments. That is, for each argument, create a new %ListOfDataTypesOpens in a new tab 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 .NET 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 an Ensemble proxy class and importing it into Ensemble, the .NET 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 .NET 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 .NET Gateway automatically excludes a small subset of assemblies such as Microsoft.* assemblies.

%ExpressImport() Method

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()Method

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

Using the Command Prompt

Usually you start and stop the .NET Gateway server automatically, by configuring the EnsLib.DotNetGateway.ServiceOpens in a new tab business service as a member of the production. Once this is done, the .NET Gateway server starts and stops automatically with the production. The StartGateway() class method is also available to manually start the .NET Gateway server.

However, during development or debugging, or when Ensemble and the .NET Gateway server run on different machines, you may find it useful to start the gateway server from a command prompt. Copy the file DotNetGatewaySS.exe to the directory where you load an assembly. By default, DotNetGatewaySS.exe is shipped in the directory install-dir\dev\dotnet\bin. Run DotNetGatewaySS.exe from install-dir\dev\dotnet\bin as follows:

DotNetGatewaySS port listener logfile

For example:

DotNetGatewaySS 55000 "" ./gatewaySS.log

Using the .NET Gateway Wizard

You can import a DLL assembly file from .NET and create a set of corresponding classes using the .NET Gateway wizard built into Studio. To start the wizard:

1. Start Studio.

2. From the Tools menu, point to and click Add-Ins.

3. Click .NET Gateway Wizard to start the .NET Gateway Wizard dialog.

4. Enter the path and name of a DLL assembly file; or click Browse to help navigate to one.

5. Enter the .NET Gateway server name / IP address and .NET Gateway server port for the .NET Gateway server.

6. You can also enter Additional paths\assemblies to be used in finding dependent classes and Exclude dependent classes matching the following prefixes as instructed in the dialog.

7. Click Next to generate Ensemble proxy classes. The wizard displays the class name as it generates each proxy class.

8. When the import operation is complete, click Finish to exit the wizard.

Error Checking

The .NET Gateway provides error checking as follows:

• When an error occurs while executing Ensemble proxy methods, the error is, in most cases, a .NET exception, coming either from the original .NET method itself, or from the .NET Gateway engine. When this happens, an error is trapped.

• The .NET Gateway API methods like %Import() or %Connect() return a typical Ensemble %StatusOpens in a new tab variable.

In both cases, Ensemble 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.

You can retrieve the complete text of the error message by calling $system.OBJ.DisplayError(), as follows:

 Do $system.OBJ.DisplayError(%objlasterror)

Troubleshooting

Should you encounter problems while using the .NET 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 .NET Gateway. You can do this whether you start from the command line or use the StartGateway() API method.

Sometimes, while using the .NET 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 .NET 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:

 Close "|TCP|port"

Where port is the port number to close.