· Nov 10, 2016 5m read

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:


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 -


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: 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:



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=""
    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)
         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!


Discussion (12)0
Log in or sign up to continue

My question is whether .net gateway service can be used when you have to call class library(dll) on Linux hosted ensemble instance.

I know it's ridiculous to expect .net framework on Linux(can be done with .net core, mono), but how you can overcome a situation where complex logic is built in c# class and a dll is given to you for quick implementation.

OK. I understand.
- I doubt if a Linux distribution of Caché contains any Windows mechanics. ( to be checked with WRC )
- on the other hand I don't believe it's possible or make sense  to run Caché Win distribution in a Win-Shell ...
So suggested workaround:
Have a VM (or small machine) with Windows +Caché and connect via ECP or similar (REST, WebService, JDBC, ...)  to your main Caché instance on Linux. 


Wrap some C# around your DLL on a Windows box and present it as a WebService that you call from Linux.