DLL Interface

A DLL file, or dynamic-link library file, is a library that contains code and data and that can be used by more than one program at the same time. The DLL4 interface is a custom wrapper that can be used to access such a DLL file, and as such can be used to retrieve data from any system. The interface allows you to set a DLL file as the interface script. A DLL file can for example be a C# Class Library.

Knowledge of the Ometa Business Connector and how to set it up is required before being able to understand and use this document.

Important

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

Articles

1. Configuration

Context Records

Methods can be executed with context multiple times for example in synchronisations or list item functions. Handling these context records can be done either by the custom dll implementation, or by the DLL4 interface itself.

If the custom DLL hasn't moved context records after finishing, while the method still has more context records, the DLL 4 interface will invoke the custom DLL again with the next context record.

Processing Context Records In Custom DLLs

Looping through the context records available can be done using the snippet below.

Copy

public async Task ProcessRequestAsync(CancellationToken cancellationToken = default)
{
    do {
        // Do something.
    } while (Interface.Method.MoveToNextContextRecord() && Interface.ResultWriter.AcceptingRecords);
}

If you wish for the custom DLL to fully stop processing other context records if an error occurred, be sure to move to the next context record so the DLL 4 interface is aware that the custom DLL is managing context records itself. The snippet below shows how to stop the entire method execution on a CriticalException, but continue on a Exception.

Copy

public async Task ProcessRequestAsync(CancellationToken cancellationToken = default)
{
    do {
        try {
            // Do something.
        }
        catch (CriticalException ce)
        {
            // Example to stop the entire method.
            Interface.ResultWriter.WriteError(ce.Message);
            Interface.Method.MoveToNextContextRecord()
            throw;
        }
        catch (Exception e) 
        {
            // Example to continue processing the other context records.
            Interface.ResultWriter.WriteContextRecordError(e.Message);
        }
    } while (Interface.Method.MoveToNextContextRecord() && Interface.ResultWriter.AcceptingRecords);
}

Default Context Record Behavior In DLL 4 Interface

If you do not account for context records in your custom DLL, the following behavior is default:

• If there are no additional context records given for the execution, the dll is executed once.
• If there are additional context records, each context record will invoke the entry point (default ReceiveMessage) of your dll sequentially. Keep in mind that static fields and properties therefore are not reset between executions.
  • If errors occur during the execution of one of the context records, execution will continue for the other context records.