From fb038844422b0ab73bd19cf2a3a4efdce6d8eccc Mon Sep 17 00:00:00 2001 From: bclothier Date: Mon, 23 Sep 2024 03:58:18 -0500 Subject: [PATCH] Update the documentation to document the new feature. --- README.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 59a7f629..b7f7b748 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The `dSPACE.Runtime.InteropServices.BuildTasks` library provides build tasks whi - [Limitations](#limitations) - [RegisterAssembly](#registerassembly) -## Introducing +## Introduction Fortunately, .NET still supports COM, but there is no support for generating TLBs. From the Microsoft documentation: @@ -62,6 +62,7 @@ The command-line interface (CLI) tool `dscom` is a replacement for `tlbexp.exe` It supports the following features: - Convert an assembly to a type library + - Optionally embed the generated type library into the assembly - Convert a type library to `YAML` file - Register a type library - Unregister a type library @@ -115,6 +116,8 @@ dSPACE.Runtime.InteropServices supports the following methods and classes: - TypeLibConverter - ConvertAssemblyToTypeLib +- TypeLibEmbedder + - EmbedTypeLib - RegistrationServices - RegisterTypeForComClients - UnregisterTypeForComClients @@ -172,6 +175,33 @@ public class TypeLibConverterCallback : ITypeLibExporterNotifySink } ``` +### TypeLibEmbedder.EmbedTypeLib + +.NET +8 introduced ability to embed type library into assemblies with the ComHostTypeLibrary property. However, using this is not fully compatible with the dscom build tools as it requires a type library to be already generated prior to the build. This class provides the impleementation for embedding a type library into an assembly via Win32 API p/invoke calls. + +The class and method are static, so you only need to create a settings to provide parameter for the source type library and the target assembly for where the type library will be embedded. + +It is important to note that type libraries are _not_ bit-agnostic and therefore, it will not make sense to embed them in an AnyCPU assemblies. For .NET 5.0 and greater, that is not an issue since the generated *.comhost.dll are tied to a specific bitness. For .NET 4.8, it is strongly recommended that the assembly be built with either x64 or x86 rather than AnyCPU. + +```csharp +public static bool EmbedTypeLib( + TypeLibEmbedderSettings settings +) +``` + +Example: + +```csharp +using dSPACE.Runtime.InteropServices; + +var settings = new TypeLibEmbedderSettings +{ + SourceTlbPath = "C:\\path\\to\\type\\library.tlb", + TargetAssembly = "C:\\path\\to\\assembly.dll" +}; +TypeLibEmbedder.EmbedTypeLib(settings); +``` + ### RegistrationServices.RegisterTypeForComClients The `dSPACE.Runtime.InteropServices.RegistrationServices` provides a set of services for registering and unregistering managed assemblies for use from COM. @@ -242,7 +272,7 @@ The native build task is automatically selected, if a .NET 4.8 or .NET 6.0 assem #### Using the CLI based task -The CLI task is automatically selected, if a .NET Standard 2.0 assembly is build. It is also chosen, if the target platform is set to x86. +The CLI task is automatically selected, if a .NET Standard 2.0 assembly is being build. It is also chosen if the target platform is set to x86. #### Enforcing the usage of the CLI @@ -281,7 +311,7 @@ The build task can be parameterized with the following [properties](https://lear | DsComTlbExportIncludeReferencesWithoutHintPath | If a `Reference` assembly does not provide a `HintPath` Metadata, the item spec shall be task.
Default value: `false` | | _DsComExportTypeLibraryTargetFile | Path to the resulting file.
Default value: `$(TargetDir)\$(TargetName)$(_DsComTlbExt)` * | | _DsComExportTypeLibraryAssemblyFile | Path to the source assembly file.
Default value: `$(TargetPath)` * | - +| DsComTypeLibraryEmbedAfterBuild | Embeds the generated type library into the source assembly file.
Default value: `false` | *) This value cannot be overridden. The build task consumes the following [items](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-items?view=vs-2022):