Mistik.MtbTypes 1.0.0

MTB Types

This is an unofficial, community-maintained package providing type declarations for Zeiss's MicroToolBox API under the namespace and assembly name ZEISS.MTB.Api. The use of this namespace is to allow referencing this code as if it were the official code distributed by Zeiss, then loading their DLL at run-time to provide the real types. Class and struct member bodies are stubbed out with an InvalidOperationException.

The type signatures mirror the MTB API surface completely. No Zeiss DLL was decompiled to assist in the development of this package - see Process for our method. All code documentation is unofficial and community-written, and is not derived from the official documentation.

We, Mistik and all contributors to this package, assume no liability for damage caused by misuse of the MTB API, whether due to programmer error, API mismatch, or heeding the community-written documentation. We make no claims about the correctness of any information or code contained in this package. See the attached licence.

This package is developed solely to aid interoperability with the MicroToolBox API.

Usage

1. Reference in your MTB-dependent project as follows:

   <PackageReference Include="Mistik.MtbTypes" Version="0.0.0">
   
     <PrivateAssets>all</PrivateAssets>
   </PackageReference>
   

   Make sure to specify the version you want.
2. Load the real MTB assembly with the following call:

   // We have to find and load MTBApi at run-time (rather than including it in the build output)
   // since we are not allowed to distribute the DLL.
   // This means that we may get an incompatible version.
   System.Reflection.Assembly.LoadFrom(@"C:\Program Files\Carl Zeiss\ZEN 2\ZEN 2 (blue edition)\MTBApi.dll");
   

   The above example simply tries to load the DLL distributed with ZEN 2 blue, an MTB build found to work under modern .NET. It would be wise to try more common locations, catching exceptions and checking the assembly version for compatibility.
3. Create an instance of MTBConnection:

   new MTBConnection()
   

   At this point you will receive an exception if you loaded a .NET Framework-only MTB build; in this case, your exception handler could return to step 3 to try another location.
   Note: In .NET, any use of a newly-loaded assembly must occur in a method called after loading it.
4. Proceed with the help of the official documentation, which may be downloaded from the Zeiss portal as part of their SDK.

MTB Compatibility

This package has been used with the following MTB versions:

• 3.11.9

This is not a guarantee of correctness - as consumer of this package, it is your responsibility to test all MTB functionality that you make use of. We assume no liability for damage caused by your use of the API.

Motivation

Zeiss produces multiple variants of MTBApi.dll, required in most cases for working with one of their microscopes, but the process for obtaining them is highly manual. At minimum each developer must create a Zeiss account and download the SDK from the software portal onto their own machine, since the DLLs may not be redistributed, in order to reference the types from any of their projects (or compile a project that depends on them). Moreover, the SDK's variant of MTBApi.dll only supports .NET Framework, so an email to Zeiss's API support team may be necessary in order to obtain a version for modern projects.

This friction is a great obstacle for development of an open source project that depends on the MTB API to work with Zeiss microscopes, as complex steps are required just to get the project to build. Moreover, it means that the project's compilation depends on something outside of developer control. If Zeiss were to change their DLL in a way that disagreed with your project system, and the in-use copy were lost, you would be stuck.

Mistik's solution is to create type stubs just for referencing during development and at build-time, omit these from the build output, and dynamically load MTBApi.dll from the host machine at run-time. The types live under the same namespace as the real API, and are named identically. We generate these from the MTB documentation without touching Zeiss's library code.

This has the following implications:

• We get out-of-the-box builds and autocomplete without having to decompile or redistribute any Zeiss library.
• We get developer documentation directly in the IDE in cases where we have included community-written doc comments. The technical writing within Zeiss's documentation is not used to create any doc comments, in order not to violate Zeiss's copyright.
• We can publish without fear of accidentally redistributing MTBApi.dll along with our own build output.
• We can guarantee that our builds will keep working, and will work the same for every developer.

Process

All stubs are generated from MTB documentation files by a Python script. The script is hosted at https://codeberg.org/mistik/mtbstub, which also serves as the source for the original, community-written documentation comments.

MTBApi.chm must first be obtained by downloading the SDK from the Zeiss software portal, which requires an account. Once downloaded, its files can be extracted with 7-Zip.

The extracted HTML files have a predictable structure and describe the API almost perfectly, with only a few manual fixes being applied by the script.