docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the Object Gateway for .NET  /  Object Gateway Architecture


Using the Object Gateway for .NET
Object Gateway Architecture
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


The InterSystems IRIS™ Object Gateway for .NET (which this book will usually refer to as simply “the Object Gateway”) provides an easy way for InterSystems IRIS to interoperate with Microsoft .NET Framework components. The Object Gateway can instantiate an external .NET object and manipulate it as if it were a native object within InterSystems IRIS.
Using Proxy Classes
The external .NET object is represented within InterSystems IRIS by a proxy class. A proxy object looks and behaves just like any other InterSystems IRIS object, but it has the capability to issue method calls out to the .NET Common Language Runtime (CLR), either locally or remotely over a TCP/IP connection. Any method call on the InterSystems IRIS proxy object triggers the corresponding method of a .NET object inside the CLR.
The following diagram offers a conceptual view of InterSystems IRIS and the Object Gateway at runtime.
.NET Object Gateway Operational Model
Instances of the .NET Object Gateway Server run in the CLR. InterSystems IRIS and the CLR may be running on the same machine or on different machines. The numbered items in the .NET Object Gateway Operational Model diagram point out the following relationships:
  1. An InterSystems IRIS namespace accesses an instance of the .NET Object Gateway Server. Access is controlled by an instance of the InterSystems IRIS %Net.Remote.Service class.
  2. Each InterSystems IRIS session is connected to a separate thread within the Object Gateway server. The connection is controlled by an instance of the InterSystems IRIS %Net.Remote.Gateway class.
  3. Each proxy object communicates with a corresponding .NET object.
A call to any InterSystems IRIS proxy method initiates the following sequence of events:
Using Wrapper Classes with .NET APIs
In most cases, you will use the Object Gateway by creating proxy classes for your custom .NET components (see the chapter on Creating Proxy Classes for details). However, it is also possible to create proxy mappings for an entire third party .NET application interface specification.
It may be tempting to create mappings for extremely large APIs (such as ADO, Remoting, or ASP.Net), which could then be reused in any number of applications, but this is not recommended. Such mappings can create hundreds of proxy classes, even though your application may only need a few of them. You can specify a list of classes that you do not want the proxy generator to map, but a very large exclusion list is difficult to create and manage.
When using a third party DLL in your application, the best approach is to build a small wrapper class for it, and then create a proxy for this wrapper. A wrapper class exposes only the functionality you want, which makes the interface between InterSystems IRIS and the .NET framework very clean and eliminates many potential issues. Wrapper classes provide the following advantages:
Creating and Running an Object Gateway Server
Before you can use the Object Gateway, you must start an instance of the .NET Object Gateway Server and tell InterSystems IRIS the name of the host on which the server is running. Once started, a server runs until it is explicitly shut down.
Once the Object Gateway server is running, each InterSystems IRIS session that needs to invoke .NET class methods must create its own connection to the server, as shown in the following diagram:
Connecting to a .NET Object Gateway Worker Thread
  1. ObjectScript code sends a connection request.
  2. Upon receiving the request, the Object Gateway server starts a worker thread in which the .NET class methods subsequently run.
  3. The connection between this Object Gateway worker thread and the corresponding InterSystems IRIS session remains established until it is explicitly disconnected. As long as it remains connected, the assigned port for the connection stays “in use” and is unavailable for use in other connections.
See Setting Object Gateway Server Properties for a detailed description of how to create an Object Gateway Server property definition, and Running an Object Gateway Server for details on how to start, connect, disconnect, and stop a server.
Importing Proxy Classes
InterSystems IRIS proxy classes are generated by sending a query to the Object Gateway Server, which returns information about the methods for which proxy classes are required. The imported method information is then used to construct the proxy classes, as shown in the following diagram:
Importing .NET Classes
  1. The InterSystems IRIS session sends an import request.
  2. Upon receiving the request, the Object Gateway worker thread introspects the indicated .NET assemblies and classes.
  3. The thread also loads dependent assemblies either from the local directory or from the Global Assembly Cache (GAC).
  4. If it finds any .NET classes that are new or changed, or that have no proxy classes on the InterSystems IRIS side, the Object Gateway worker thread returns the results of the introspection to the InterSystems IRIS session, which uses the information to generate new proxy classes.
See Creating Proxy Classes for details on how to generate proxy classes.
The .NET Object Gateway API
The following classes provide most of the functionality used by your InterSystems IRIS Object Gateway applications:
See the InterSystems IRIS class library documentation for the most complete and up to date information on each of these classes.