InterSystems.Data.Bindings 2.5.2

InterSystems IRIS .NET Bindings

InterSystems IRIS .NET Bindings let you interact with InterSystems IRIS ObjectScript objects through proxy objects.

Proxy objects are instances of projections, which are .NET classes generated from ObjectScript classes. Each proxy object communicates (through the projection) with a corresponding object on an InterSystems IRIS server and can be manipulated as if it were the original object.

Generated proxy classes are written in fully compliant .NET-managed code, and can be used anywhere in your project.

Getting Started

Prerequisites

The InterSystems IRIS .NET Bindings package requires the IRISClient library. This dependency is resolved automatically when you install the package.

To generate the proxy classes, you need either the dotnet_generator command line utility or the IRISNetWizard executable (.NET Framework only). Both utilities are distributed with InterSystems IRIS under <InterSystems IRIS install directory>/dev/dotnet/bin.

You also need an InterSystems IRIS instance to use this package. The instance does not need to be on the same machine as the project using this package, but the project must be able to connect to the instance.

Install the Package

To install the InterSystems IRIS .NET Bindings and its dependencies with NuGet:

dotnet add package InterSystems.Data.Bindings

The .nupkg file is also distributed with InterSystems IRIS under <InterSystems IRIS install directory>/dev/dotnet/bin/.

Examples

Generating Proxy Classes

The easiest way to generate proxy classes is on the command line with the dotnet_generator, which can be found in <InterSystems IRIS install directory>\dev\dotnet\bin\<.NET version>.

The dotnet_generator requires the following arguments:

• -conn <connection_string>, where connection_string is a connection string to connect to InterSystems IRIS.
• The location to output the proxy classes, specified by one of the following:
  • -path <file_path>, where <file_path> is the path of the output file, including the filename. This generates a single output file for all classes.
  • -dir <directory_path> -src-kind <file_type>, where <directory_path> is the path of the output directory and <file_type> is either cs or vb. This generates one output file for each class.
• -class-list <full_filename>, where <full_filename> is a text file containing the names of the classes to generate. Each class name must be on a separate line.

You can also supply the following optional arguments:

• -gen-default-args <boolean>, where <boolean> is true (default) or false. This affects whether multiple methods are generated for system methods with default values. For example, for method(a, b) with default/optional parameter b:
  • true generates method(a) and method(a, b), with the former using the default value for b.
  • false only generates method(a, b).
• -skip-system-apis <boolean>, where <boolean> is true (default) or false. This specifies whether to generate system classes and the properties and methods that use them.
• -app-nsp <namespace>, where <namespace> is the namespace that will be added to the names of the generated proxy classes.

The following example is a Batch file that generates proxy classes for all the classes specified in C:\BindingsDemo\Classlist.txt and outputs them to the file C:\BindingsDemo\ProjectedCode\Projection.cs and the directory C:\BindingsDemo\ProjectedCode:

set netgen=C:\InterSystems\IRIS\dev\dotnet\bin\net8.0\dotnet_generator.exe
set clist=C:\BindingsDemo\Classlist.txt
set out=C:\BindingsDemo\ProjectedCode
set conn="Server=localhost;Port=1972;Namespace=USER;Password=SYS;User ID=_SYSTEM;"

rem Generate a single Projection.cs proxy file:
%netgen% -conn %conn% -class-list %clist% -path %out%\Projection.cs

rem Generate one proxy file for each class:
%netgen% -conn %conn% -class-list %clist% -dir %out% -src-kind cs

In the above example, Classlist.txt contains the following:

Sample.Person
Sample.Company
Sample.Employee

Using Proxy Objects

To use a proxy object, create an instance of it in your application and save it to an InterSystems IRIS server. You can then open the object on the server for further modification.

The following example creates a Person proxy object, saves it to an InterSystems IRIS server, and opens it for other operations:

using InterSystems.Data.IRISClient;
using InterSystems.Data.IRISTypes;

// Establish a connection to the InterSystems IRIS server
BindingsConnection conn = new BindingsConnection("localhost", "1972", "BINDINGS", "_SYSTEM", "SYS");
conn.Open();

// Create proxy object and set its properties
Sample.Person person = new Sample.Person(conn);
person.Name = "John Smith";
person.Age = 30;

// Save the object to the InterSystems IRIS server and close it
IRISStatus sc = person.Save();
if (!sc.IsOK) 
{ 
    Console.WriteLine($"Save failed: {sc.Message}");
    return;
}
string id = person.Id();
Console.WriteLine($"Save succeeded, ID is {id}");
person.Close();

// Open the object by ID and get its properties
Sample.Person p = Sample.Person.OpenId(conn, id);
// retrieve properties
Console.WriteLine(p.Name);
Console.WriteLine(p.Age);

// Call a method
p.HaveBirthday();
Console.WriteLine(p.Age);

// Save and close the object
p.Save();
p.Close();

// Delete the object by ID
IRISStatus deleteStatus = Sample.Person.DeleteId(conn, id);
Console.WriteLine($"Delete success? {deleteStatus.IsOK}");

// Close the object and connection
conn.Close();