dSPACE COM tools

COM (Component Object Model) remains a critical part of the Windows ecosystem, enabling interoperability between software components. Despite its age, COM is still widely used in many applications and systems. However, with the advent of .NET 5 and later versions, Microsoft has discontinued several tools that were essential for working with COM, such as tlbexp.exe and RegAsm.exe. This has left developers without built-in support for generating or registering COM Type Libraries (TLBs) from .NET assemblies.

There is no support in .NET Core or .NET 5+ for generating a COM Type Library (TLB) from a .NET assembly.
https://docs.microsoft.com/en-us/dotnet/core/native-interop/expose-components-to-com

To address this gap, dscom provides a modern replacement for these tools. It offers a command-line interface (CLI) and libraries that allow developers to:

• Generate and register TLBs from .NET assemblies.
• Embed TLBs into assemblies.
• Register and unregister assemblies for COM.
• Convert TLBs to YAML files for inspection.

dscom aims to replicate the functionality of the discontinued Microsoft tools while introducing additional features to simplify COM-related workflows in .NET 5+ and .NET Framework projects. Whether you are working with legacy systems or building new applications that require COM interoperability, dscom provides the tools you need to bridge the gap.

The dSPACE.Runtime.InteropServices.BuildTasks library provides build tasks which can be used to automatically generate TLBs at compile time.

• dSPACE COM tools
  • Command Line Client
    • Key Features of dscom.exe
    • Installation
    • Usage
  • Library
    • TypeLibConverter.ConvertAssemblyToTypeLib
    • TypeLibEmbedder.EmbedTypeLib
    • RegistrationServices.RegisterTypeForComClients
    • RegistrationServices.RegisterAssembly
  • Build Tasks
    • Build task usage
      • Enforcing to stop the build, if an error occurs
    • Parameters
    • Example
    • Hints
  • 32Bit support
  • Migration notes (mscorelib vs System.Private.CoreLib)
    • Why can I load a .NET Framework library into a .NET application?
  • Limitations
    • .NET 6 support
    • RegisterAssembly
    • RegAsm
  • Contributing

Command Line Client

The command-line interface (CLI) tool dscom serves as a modern replacement for several legacy tools, including tlbexp.exe, OleView (for viewing Type Libraries), and RegAsm.exe. It is designed to simplify and enhance workflows related to COM (Component Object Model) interoperability in .NET applications.

Key Features of dscom.exe

1. Convert an Assembly to a Type Library
   dscom allows you to generate a COM Type Library (TLB) from a .NET assembly. This is particularly useful for enabling COM interoperability with .NET assemblies in environments where a TLB is required.

   • Optional Embedding: The generated Type Library can optionally be embedded directly into the converted assembly, ensuring that the TLB is always available alongside the assembly.

2. Convert a Type Library to a YAML File
   With dscom, you can inspect the contents of a Type Library by converting it into a human-readable YAML file. This feature is helpful for debugging, documentation, or understanding the structure of a TLB.

3. Register a Type Library
   The tool provides functionality to register a Type Library with the system, making it available for use by COM clients.

4. Unregister a Type Library
   If a Type Library is no longer needed, dscom can unregister it, removing its association with the system.

5. Embed a Type Library into an Existing Assembly
   dscom supports embedding an existing Type Library into a specified assembly. This feature is useful for scenarios where you want to bundle the TLB with the assembly for easier distribution and deployment.

6. Register an Assembly (Equivalent to RegAsm.exe)
   The tool can register a .NET assembly for use with COM clients, similar to the functionality provided by RegAsm.exe. This includes creating the necessary registry entries to expose the assembly's classes to COM.

7. Unregister an Assembly (Equivalent to RegAsm.exe)
   If an assembly is no longer required for COM interoperability, dscom can unregister it, cleaning up the associated registry entries.

These features make dscom a versatile and powerful tool for developers working with COM in modern .NET environments, addressing the gaps left by the deprecation of older tools while introducing additional capabilities to streamline the development process.

Installation

The installation is quite simple. You can use dotnet tool to install the dscom binary if you want to create a 64Bit TLB.

dotnet tool install --global dscom

Here you can find all available versions:
https://www.nuget.org/packages/dscom/

Alternatively you can download dscom.exe from the release page.
https://github.com/dspace-group/dscom/releases

Usage

Use dscom --help to get further information.

c:\> dscom --help
Description:
  dSPACE COM tools

Usage:
  dscom [command] [options]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  tlbexport <Assembly>                           Export the assembly to the specified type library
  tlbdump <TypeLibrary>                          Dump a type library
  tlbregister <TypeLibrary>                      Register a type library
  tlbunregister <TypeLibrary>                    Unregister a type library
  tlbembed <SourceTypeLibrary> <TargetAssembly>  Embeds a source type library into a target file
  regasm <TargetAssembly>                        Register an assembly

Example to create a TLB from an assembly:

c:\> dscom tlbexport MyAssembly.dll --out C:\path\to\output\MyAssembly.tlb

For more information about the command line options to create a TLB, use dscom tlbexport --help.

Library

Usage:

dotnet add package dSPACE.Runtime.InteropServices

dSPACE.Runtime.InteropServices supports the following methods and classes:

• TypeLibConverter
  • ConvertAssemblyToTypeLib
• TypeLibEmbedder
  • EmbedTypeLib
• RegistrationServices
  • RegisterTypeForComClients
  • UnregisterTypeForComClients
  • RegisterAssembly
  • UnregisterAssembly

TypeLibConverter.ConvertAssemblyToTypeLib

If you miss the TypeLibConverter class and the ConvertAssemblyToTypeLib method in .NET, then the dSPACE.Runtime.InteropServices might help you. This method should behave compatible to the .NET Framework method.

public object? ConvertAssemblyToTypeLib(
  Assembly assembly,
  string tlbFilePath,
  ITypeLibExporterNotifySink? notifySink)

https://www.nuget.org/packages/dSPACE.Runtime.InteropServices/

Example:

using dSPACE.Runtime.InteropServices;

// The assembly to convert
var assembly = typeof(Program).Assembly;

// Convert to assembly
var typeLibConverter = new TypeLibConverter();
var callback = new TypeLibConverterCallback();
var result = typeLibConverter.ConvertAssemblyToTypeLib(assembly, "MyTypeLib.tlb", callback);

// Get the name of the type library
var typeLib2 = result as System.Runtime.InteropServices.ComTypes.ITypeLib2;
if (typeLib2 != null)
{
    typeLib2.GetDocumentation(-1, out string name, out _, out _, out _);
    Console.WriteLine($"TypeLib name: {name}");
}

// The callback to load additional type libraries, if necessary
public class TypeLibConverterCallback : ITypeLibExporterNotifySink
{
    public void ReportEvent(ExporterEventKind eventKind, int eventCode, string eventMsg)
    {
        Console.WriteLine($"{eventCode}: {eventMsg}");
    }

    public object? ResolveRef(System.Reflection.Assembly assembly)
    {
        // Returns additional type libraries
        return null;
    }
}

TypeLibEmbedder.EmbedTypeLib

.NET +6 introduced ability to embed type library into assemblie