DLL4 interface

Template and Profile

A template for the DLL4 interface contains the following parameters, it only has internal parameters:

Field name	Type	Description
IP	Internal	Specifies the ip or hostname of the server on which the interface of this profile is installed.
Port	Internal	The port of the Ometa Business Connector Slave Listener (BCSL.exe; default: 2002).
KeepConnectionOpen	Internal	True or False. If True, connections made to this interface will stay open when the client disconnects. The next request for this interface with the same profile fields and values will reuse this open connection. Profile fields of the type Dynamic are ignored when this check happens.
OpenConnectionIdleTimeAllowed	Internal	Specifies the minutes a connection can stay open without a connected client. Only used if KeepConnectionOpen is True.
Isolation	Internal	Indicates the isolation in which methods using this profile should be executed. Available options are: Default: methods are executed on the same process on the same AppDomain, statics are shared. Dedicated: methods are executed on the same process on separate AppDomains, statics are not shared. This setting is patched to 'Dedicated' on profiles to maintain backwards compatibility. Visit the migration guide for DLL 4 on docs.ometa.net for more information.

External File

The external file of the DLL4 interface is the DLL file of an application. Simply place the file in the interface folder of the Ometa Business Connector. The interface folder is located in Ometa BVBA\Ometa Software Suite\TopDir\BC\Bin\Interfaces\BCS_DLL 4.

As you can see we have created a custom application called PrintToPDF. By placing the DLL file in the interface folder it is reachable by the DLL4 interface.

Next we have created a method called CreateInvoice in the Ometa Business Connector. The interface script of this method contains the filename.

Examples

Creating a Class Library in Visual Studio 2019

Important

The DLL4 interface only supports .NET Framework 4.8. It does NOT support .NET Core or .NET 5 and higher.

This example guides you through the steps to create a new Class Library.

1. Open Visual Studio.
2. Click on File > New > Project.
3. Select C# as language.
4. Select Windows as platform.
5. Select Class Library (.NET Framework).

6. Click on Next.

   

Important

Make sure to select Class Library (.NET Framework) as the project template. A very similar Class Library (.NET Standard) exists aswell. This second template will not work.

Implement IRequestProcessor

The next step is to write the code that the DLL4 interface should execute. This can be done by implementing Ometa.Interfaces.IRequestProcessor.

Copy

public class CreateInvoice : IRequestProcessor
{
    public IInterfaceRequest Interface { get; set; }

    public async Task ProcessRequestAsync(CancellationToken cancellationToken = default)
    {
        // Do something.
    }
}

Statics

The default behavior of the DLL4 interface is to run the code in the same AppDomain. This means that static properties and fields are shared with other DLL methods running at the same time. The static values are kept until the DLL4 process is recycled.

We recommend using adequate locks, or using thread safe types (for example ConcurrentDictionary) to prevent concurrency issues.

The code can be isolated from other DLL method calls by using Isolation : Dedicated in the profile. This will execute the code in a separate AppDomain without sharing the statics with other method executions. AppDomains may still be reused if KeepConnectionOpen : True is configured in the profile. Keep in mind that opening new AppDomains will bring a performance penalty.

Method Configuration

You can tell the DLL4 interface which code to call by putting the name of the dll file and the name of the class in the interface script.

Note

In previous framework versions, the name of a function could be specified in the interface script. This will still work if Isolation : Dedicated is configured in the profile. Visit DLL Migration Guide for more information.

Accessing the DLL of the Project

Once we have finished our custom application we need the DLL of our project.

1. Go to the directory of the Visual Studio project you created.
2. Go to \bin\Release.
3. Copy the DLL file located there to the interface folder described in the above chapter External File.

NuGet Packages

The framework comes with NuGet packages that can be used in DLLs to access functionalities of the framework programmatically. The following packages are included:

Package name	Description
Ometa.Framework.Client	The Ometa framework client library allows you to work with an Ometa framework installation.
Ometa.Framework.Core	The core library of the Ometa Framework. For internal use only.
Ometa.Framework.Core.Communication	Core project supporting internal communication via gRPC between Framework components. For internal use only.
Ometa.Framework.Core.OpcUa	Core project supporting the OPC UA protocol within the Ometa Framework. For internal use.
Ometa.Framework.Infra	The infra library of the Ometa Framework. For internal use only.
Ometa.Framework.Shared	Library containing enumerations and constants that are used in the other Ometa.Framework libraries. This NuGet will be automatically installed when installing the other Ometa.Framework NuGets because it's a dependency.
Ometa.Framework.Transfer	Library supporting of export, import and deployment of configuration between Ometa Framework installs. For internal use only.
Ometa.Libraries.Internal.All	This package contains all libraries and their required dependencies needed to work internally with the Ometa Framework (e.g.: via a custom dll) including the Ometa.CommLib, Ometa.DCS, Ometa.DCS.Utilities, Ometa.Data, Ometa.Data.Utilities and the Ometa.Utilities.Client.
Ometa.Libraries.Internal.CommLib	This package contains the Ometa.CommLib, Ometa.Data and the Ometa.Data.Utilities libraries and all their required dependencies.