C# 12 Interceptors are here!

[monkey0506]

C# 12 interceptors are now available to this project!

The interceptors branch was created with a6d0462. This branch uses an incremental generator, which has a dependency on GenericSymbolReferenceTree.

The interceptors branch has now been renamed to v2.0.0 until it is merged into the master branch.

Example

Using interceptors is an improvement from v1.0.0 which does not depend on System.Reflection.Emit for dynamic code generation. Instead, the marshalling behaviors and unmanaged calling conventions are parsed from the invocation site:

nint fpPrint = NativeMethods.GetPrintMethod(); // user-defined: get function pointer from a native library
var print = INativeAction<string>.FromFunctionPointer<nint>(fpPrint, [new MarshalAsAttribute(UnmanagedType.LPUTF8Str)], CallingConvention.Cdecl); // get a native generic delegate for the function pointer
print.Invoke("Hello, World!"); // invoke the native function

Custom marshalling

The MarshalAsAttribute?[]? here specifies the runtime marshalling behavior. The native method takes a single char* to a UTF-8 string, which is marshalled as a System.String in managed code. This parameter must be an array initializer (new[] { ... }) or collection expression ([ ... ]), or a reference to a readonly field.

If a field is referenced for this parameter, it must be readonly and initialized inline with an array initializer or collection expression. Values assigned to this field in a constructor will not be observed.

The elements of the collection must be object creation expressions (new MarshalAsAttribute(...)).

The methods in the INativeFunc<...> interfaces also accept a MarshalAsAttribute? parameter for marshalling the return value. This parameter must be an inline object creation expression or a reference to a readonly field with an inline initialization.

Unmanaged calling convention

The CallingConvention parameter must be a literal value of System.Runtime.InteropServices.CallingConvention. Currently it is not supported to store this value in a field.

Technical implementation detail

The source generator will produce a single class (per assembly) for each combination of type arguments, marshalling behavior, and unmanaged calling convention. These classes define a System.Delegate that is not generic, that accepts parameters of the managed types specified as type parameters to the INativeAction<...> or INativeFunc<...> interface.

The individual call sites (FromAction, FromFunc, or FromFunctionPointer) throughout your code will then be intercepted, and produce an instance of the matching class, which implements the requested interface.

[monkey0506]

This discussion is out-of-date with the current v2.0.0 API. Changes have been made in the way that custom marshalling behaviors are specified. Until this discussion is updated, the v2.0.0 README.md should be used as a reference for the current API.