Creating Proxy Classes
This chapter covers the following topics:
-
Using the Studio .NET Gateway Wizard — The simplest way to generate proxy classes for a .NET assembly is to use the .NET Gateway Wizard plugin supplied with Studio.
-
Generating Proxy Classes Programmatically — You can also generate proxy classes from within an ObjectScript program. The %Net.Remote.GatewayOpens in a new tab class contains the methods used to import class definitions from .NET assemblies and generate Gateway proxy classes.
See Using Wrapper Classes with .NET APIs for a description of the preferred method for importing third-party DLLs. See the Mapping Specification chapter for a detailed description of how .NET classes are mapped to Caché proxy classes.
The .NET Gateway cannot generate proxy classes for .NET generic classes. It similarly cannot import .NET classes with generic subclasses or subinterfaces.
Using the Studio .NET Gateway Wizard
The following steps summarize the procedure:
-
Start a .NET Gateway server. The server must be running before the Wizard can be used.
-
In Studio, select Tools > Add-ins > Add-ins... to display the list of available add-ins.
-
Select .Net Gateway Wizard from the Add-ins dialog and click OK. The .Net Gateway Wizard Studio template is displayed:
The .NET Gateway Wizard Studio Template
-
Fill out the form. The following items can be defined:
-
Enter the path and name of a DLL assembly file: — Required. DLL name.
-
.NET Gateway server name / IP address: — Required. IP address or name of the machine where the .NET Gateway server executable is located. The default is "127.0.0.1".
-
.NET Gateway server port: — Required. Server port.
-
Additional paths\assemblies to be used in finding dependent classes: — Optional. Specify a list of assembly .dll files or directories, separated by semicolons.
-
Exclude dependent classes matching the following prefixes: — Optional. Specify a list of namespaces and class name prefixes, separated by semicolons.
-
-
The Wizard displays a list of available classes:
Selecting Classes to Import
Check the classes that you want to use, then click Finish.
Generating Proxy Classes Programmatically
This section discusses the following methods of the %Net.Remote.GatewayOpens in a new tab class:
-
%Import() — imports .NET classes or assemblies from the .NET side and generates all the necessary proxy classes for the Caché side.
-
%GetAllClasses() — returns a list of all public classes available in the specified assembly DLL.
-
%ExpressImport() — combines calls to %Connect(), %Import(), and %Disconnect().
See the %Net.Remote.GatewayOpens in a new tab Caché class documentation for a complete listing of all Gateway methods.
The %Import() method of the Gateway class sets off the following chain of sequential events:
-
The Caché session sends an import request.
-
Upon receiving the request, the .NET Gateway worker thread introspects the indicated .NET assemblies and classes.
-
The thread also loads dependent assemblies either from the local directory or from the Global Assembly Cache (GAC).
-
If it finds any .NET classes that are new or changed, or that have no proxy classes on the Caché side, the .NET Gateway worker thread generates new proxy classes for them.
%Import() Method
The %Import() method imports the given class and all its dependencies by creating and compiling all the necessary proxy classes. The %Import() method returns (in the ByRef argument imported) a list of generated Caché proxy classes. For details of how .NET class definitions are mapped to Caché proxy classes, see the “Mapping Specification” chapter in this guide.
%Import() is a onetime, startup operation. It only needs to be called the first time you wish to generate the Caché proxy classes. It is necessary again only if you recompile your .NET code and wish to regenerate the proxies.
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.
While mapping a .NET class into an Caché proxy class and importing it into Caché, 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.
%GetAllClasses() Method
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.
%ExpressImport() Method
%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.
