Skip to content

Commit

Permalink
Update the documentation to document the new feature.
Browse files Browse the repository at this point in the history
  • Loading branch information
bclothier committed Sep 23, 2024
1 parent 0989a11 commit fb03884
Showing 1 changed file with 33 additions and 3 deletions.
36 changes: 33 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -115,6 +116,8 @@ dSPACE.Runtime.InteropServices supports the following methods and classes:

- TypeLibConverter
- ConvertAssemblyToTypeLib
- TypeLibEmbedder
- EmbedTypeLib
- RegistrationServices
- RegisterTypeForComClients
- UnregisterTypeForComClients
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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. <br/> Default value: `false` |
| _DsComExportTypeLibraryTargetFile | Path to the resulting file. <br/> Default value: `$(TargetDir)\$(TargetName)$(_DsComTlbExt)` * |
| _DsComExportTypeLibraryAssemblyFile | Path to the source assembly file. <br/> Default value: `$(TargetPath)` * |

| DsComTypeLibraryEmbedAfterBuild | Embeds the generated type library into the source assembly file. <br /> 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):
Expand Down

0 comments on commit fb03884

Please sign in to comment.