Using XJIntegration.dll in a C# project

N.B. XJIntegration is built using .NET Framework version 4.8; it can only be used with C# projects that are built against .NET Framework version 4.8 or later. It cannot be used in projects built against any version of .NET Core or against .NET 5 or later.

Adding project references

The usual way to add a reference to .NET assembly from a C# project would be to reference the assembly directly in the location which it is installed in. However, referencing XJIntegration.dll in this way will cause runtime errors in your project when executing XJIntegration code, because the compiler will try to copy XJIntegration.dll and DLLs that it depends on to be copied to the output directory of the program.

This should be avoided for the following reasons:

1. The compiler will copy the XJIntegration.dll reference to the bin directory of your project, and also tries to copy all other DLLs which it depends upon.
2. Some of the required DLLs which are installed in the XJTAG Bin directory will not be copied, such as the Visual C runtime DLLs. If the application cannot locate the Visual C runtime DLLs it will not work because some of the XJTAG DLLs are written in C++.
3. The combined size of all the required DLLs is large.

In fact, only XJIntegration.dll needs to be copied to the output directory of the project, because it is able to locate all DLLs that it requires as long as the correct version of XJTAG is installed on the PC.

To ensure that only XJIntegration.dll is copied to the output directory, XJIntegration.dll should be copied to the same directory as the project. It is this copy that should be referenced, with the Copy Local property set to True. It should not be necessary to reference any other XJTAG DLLs.

When XJTAG is upgraded to a new major (e.g. v3.7 → v3.8) or minor (e.g. v3.7.3 → v3.7.4) version, the integration assembly may have changed. Therefore, the copy of XJIntegration.dll which is referenced by the project should be replaced with a copy of the new version of the DLL from the XJTAG install directory.

Resolving XJIntegration dependencies

As explained above, to use the integration in a C# project, only XJIntegration.dll needs to be referenced. However, in some cases, the dependencies of XJIntegration need to be resolved manually using the AssemblyResolver class. The AssemblyResolver's Initialise method allows dependencies to be loaded before they are required. A static constructor which calls this method should be added to the class which is the entry point to XJIntegration in order to prevent unexpected exceptions from being thrown whilst calling the XJIntegration code. For example:

using XJTAG.Integration

namespace XJIntegrationProject
{
    class Program
    {
        static Program()
        {
            AssemblyResolver.Initialise();
        }
        ...
    }
}

Deployment

When distributing an application that uses the XJIntegration .NET assembly, an MSI installer should be used rather than publishing using ClickOnce.

There is a known issue when publishing using ClickOnce that when trying to install the application using setup.exe, the installation will fail with the error "Reference in the manifest does not match the identity of the downloaded assembly..." referring to one of the dependencies of XJIntegration.dll.