Introduction to .Net Gateway - use external .net library from Cache Object Script

Integrating Cache with .net may be difficult, as we need to know both technologies and tools involved. Let’s follow the simplest possible example and see the pitfalls lurking on our way.

1. Creating .Net Assembly

.Net assembly is unit that contains compiled code and other resources.

Let’s create the simplest .Net assembly that will contain the code we want to execute.

We will use assembly of type Class Library, as we will use classes and their methods contained within. This type of assembly has .dll extension.

For this the easiest way is to use Visual Studio 2015, you can use free edition.

Visual Studio introduces some concepts:

Solution – File that contains collection of Projects and files that together allow creating your product.

Project – collection of files containing Source Code, resources such as images, configuration files etc.

Open Visual Studio, Create new project by selecting : File/New Project

In a Window select: Installed/Templates/Visual C#/Windows/Class Library

You may notice other types of projects such as .Net core Class Library – those may be supported in future but for 2016.2 select only above path

Enter name for your project in "Name:" box and for the Solution in "Solution name:" box. 

You may see already Solution Explorer, if not display it by menu item View / Solution Explorer. Great! You see your new solution containing your one created project. Your project contains one class called Class1.

Right click on Class1 note in tree and change name to Calculator. Add simple method that we will call:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DotNetMathLibrary
{
    public class Calculator
    {
        public int Add(int A, int B)
        {
            return A + B;
        }
    }
}

Note, that both class and methods are public. Otherwise we cannot call this method from outside of Assembly.

Select menu item: Build/Build Solution

Your entire solution should compile well. Let’s locate the Assembly. Right click on the Project (DotNetMathLibrary) and select Open Folder in File Explorer.

In newly opened File Explorer navigate to Bin/Debug and see that:

DotNetMathLibrary.dll

is present!

If you built your solution in release mode, your assembly will be in Bin/Release

2. Starting .net Gateway

First let’s create gateway between .net and Cache words.

We need first to start .net Gateway. Navigate to Cache installation files:

<Cache home>/dev/dotnet/bin/

You will see several directories with binaries, each for different supported .net framework. Check for which version of .net Framework you have created your test assembly. In Visual Studio right click on Project, select Properties and then look at Application/Target framework.

If it starts with 4, select v4.0.30319, if it starts with 2 select v2.0.50727.

Open new CMD console and run the gateway:

C:\>cd C:\InterSystems\Ensemble20162\dev\dotnet\bin\v4.0.30319\

C:\InterSystems\Ensemble20162\dev\dotnet\bin\v4.0.30319>DotNetGatewaySS64.exe 55000 "" gatewaySS.log

Listening on IP:Port - 127.0.0.1:55000

I have run 64 bit version of Gateway (DotNetGatewaySS64.exe) as Visual Studio generates by default Class Library compatible with both 32 and 64 execution environment. If you use third party .net assembly check first if it is created for 64 or 32 bit version.

My gateway is exposing port 55000 and waiting for instructions from Cache side.

3. Generating Cache proxy classes corresponding to .net Assembly

Now it’s time to introduce this assembly to Cache world. We will use tool that will generate Cache classes automatically looking at classes exposed in the assembly.

Run Studio, connect to namespace that you will use – I have used User namespace.

Select menu item Tools/addins/Addins…

In the list select .NET Gateway Wizard. From now on it will stay in Tools/Addins… menu, great!

In new window check wizard can find .net gateway that we started before. IP points to your computer: 127.0.0.1 and the port is the same – 55000.

Now select the .net assembly that we have generated in first step.

Once done we start generation of Proxy. Wizard will show the classes detected, in our case it is only one:

DotNetMathLibrary.Calculator

So now let’s see what our amazing wizard created. In Studio, in Workspace View, let’s go to Namespace tab and select Classes. Yes! Our DotNetMathLibrary.Calculator proxy class is there!

Now that we have state of the art class having 6 lines and two methods, let’s bring it to life!

To instantiate object of this class, we first need to create another object – connection to the .NET Gateway which is still there waiting for our commands.

Lets do it with simple code:

ClassMethod Calculate()
{
    Set Port="55000"
    Set Host="127.0.0.1"
    Set NameSpace="User"
    Set AssemblyFileNameWithPath="C:\Users\Wojtek\Documents\visual studio 2015\Projects\DotNetMathLibrarySolution\DotNetMathLibrary\bin\Debug\DotNetMathLibrary.dll"
    Set gateway=##class(%Net.Remote.Gateway).%New()
    set classpath=##class(%ListOfDataTypes).%New()
    do classpath.Insert(AssemblyFileNameWithPath)
    Set status=gateway.%Connect(Host,Port,NameSpace,10,classpath)
    If status
    {
         set DotNetCalculator = ##class(DotNetMathLibrary.Calculator).%New(gateway)
         Write DotNetCalculator.Add(10,15)
    }
    else
    {
         Write "Problem with .NET Gateway"
    }
}

When we run our Cache Object Script method Calculate() from terminal with :

USER>do ##class(DotNetMathLibrary.Calculator).Calculate()

We will see the result, 25

Write DotNetCalculator.Add(10,15) called .net side with aid of .Net Gateway and brought back result – 25!