DEV Community: Maksim Zimin

Bending .NET: How to Stack-Allocate Reference Types in C#

Maksim Zimin — Wed, 30 Apr 2025 19:25:21 +0000

About

In C# interviews, it's quite common to encounter questions like "What are reference and value types?" or "Where are they stored in memory?" - and most of us instinctively answer, "Value types go on the stack, reference types on the heap."

But a good interviewer might follow up with a more thought-provoking question: "Can this ever be the other way around - value types on the heap, or reference types on the stack?"

Storing value types on the heap is relatively straightforward - boxing is a well-known concept. But the idea of placing reference types on the stack often feels counterintuitive or even impossible at first. However, if we take a step back and think logically: both the stack and the heap are just regions of memory within the same
process - they’re used differently, but not fundamentally different in nature.

In this article, we’ll explore whether it’s actually possible to place a reference type on the stack - and, more importantly, what practical benefits that might offer to us as developers.

Theory

Before diving into the demonstration, it’s helpful to refresh how class objects are represented in memory.

The key components are:

Sync Block Index - 8 bytes used internally by the runtime for features like locking and thread synchronization
Method Table Pointer - 8 bytes pointing to metadata about the object, including information about the type and the layout of its methods. This is how C# knows which methods to call and where they are located
Field Data - the remaining bytes are used to store the actual values of the class's fields

If, for example, we have a class:

class MyClass
{
    int    a;    // 4 bytes
    byte   b;    // 1 byte
    bool   c;    // 1 byte
}

then its display will be akin to

Offset	Size	Description
0x00	8 bytes	Sync block (reserved by CLR)
0x08	8 bytes	MethodTable pointer (type metadata)
0x10	4 bytes	`int a = 42`
0x14	1 byte	`byte b = 0xAB`
0x15	1 byte	`bool c = true` (0x01)
0x16	2 bytes	Padding for alignment (optional)

The structure described above corresponds to a 64-bit operating system. On a 32-bit system, pointer sizes are
different: instead of 8 bytes, pointers occupy 4 bytes.

It’s important to note that struct types do not include the initial 16 bytes used in class objects. The field data starts right at offset 0x00, which will be an important detail later on.

General Discussions

After diving into the theory, it becomes tempting to ask: What if we could allocate our new object directly on the stack - just as raw memory? Fortunately, C# gives us the tools to do exactly that. One of the key features here is the stackalloc byte[size] construct, which allows us to reserve a block of memory on the stack.

By default, stackalloc returns a byte*, which lives in the realm of unsafe code. However, thanks to the evolution of .NET and the introduction of Span<T>, we can now safely work with this stack-allocated memory - without leaving the bounds of memory safety or sacrificing performance.

This leads us to two distinct ways of implementing our idea:

Unsafe Approach – leveraging unsafe blocks, pointer arithmetic, and low-level memory manipulation
Safe Approach – using only standard C# language features, without leaving the bounds of memory safety

The current implementations avoid calling the class constructor. Calling the class constructor could introduce additional overhead during object creation. In fact, I ran extra benchmarks to confirm this — and when including a constructor call in the unsafe approach, the execution time increased by up to 5×. Still, even with that overhead, it remained faster than the heap-based version.

Unsafe

This is probably the simplest way to understand how an object can be manually constructed (allocated). If we break it down step by step, the process looks like this:

Allocate memory for the future object - this can be done using stackalloc byte[size]
Initialize the first 8 bytes to zero, which typically represent the sync block index
Set the next 8 bytes to a pointer referencing the MethodTable - metadata that describes the object's type
Convert the MethodTable pointer into a managed reference to a C# class instance. Up to this point, everything was treated as raw pointers, similar to how you would work in C++

An important step in this process is calculating the total size of the object to allocate. This can be expressed as IntPtr.Size * 2 + Unsafe.SizeOf<T>(), which accounts for the size of the object's actual data plus two pointer-sized fields: one for the sync block and one for the MethodTable reference.

Another critical detail is how to obtain a pointer to the MethodTable. This can be done using the following construct:
typeof(T).TypeHandle.Value, which gives you a raw pointer to the runtime type information associated with the target class.

Putting all the pieces together, the final code looks like this:

Of course, most of these operations will require you to work within an unsafe context

byte* buffer = stackalloc byte[IntPtr.Size * 2 + Unsafe.SizeOf<T>()]; // Buffer for storage on the stack

var pointer = (IntPtr*)stackBuffer; // Transform it for ease of use

*(pointer + 0) = IntPtr.Zero; // Optional
*(pointer + 1) = typeof(T).TypeHandle.Value; // Set MethodTable pointer

var ptr = (IntPtr)(pointer + 1); // Get a pointer to MethodTable and cast it into a managed IntPtr

var obj = Unsafe.As<IntPtr, T>(ref ptr); // Convert IntPtr to T as if we had done *(T*)ptr

As a result, we obtain an obj that behaves like a fully functional object. However, it’s crucial to keep in mind the
following important points:

The object exists outside the visibility of the Garbage Collector (GC) - it is not tracked or managed by the GC
When the method where stackalloc was called exits, the stack frame is torn down, and any attempt to use or return the object afterward can lead to undefined behavior

Safe

Now let’s move on to something even more interesting - constructing an object using pure C#, without resorting to raw pointers.

The sequence of steps remains essentially the same as in the unsafe approach. We’ll still rely on the same techniques to calculate the required size and to retrieve the pointer to the MethodTable.

In the end, the resulting code looks like this:

Span<byte> buffer = stackalloc byte[IntPtr.Size * 2 + Unsafe.SizeOf<T>()]; // Buffer for storage on the stack

var buffer = MemoryMarshal.Cast<byte, IntPtr>(stackBuffer); // Transform it for ease of use

buffer[0] = IntPtr.Zero; // Optional
buffer[1] = typeof(T).TypeHandle.Value; // Set MethodTable pointer

var objBuffer = buffer[1..]; // Get a Span<IntPtr> that starts with a MethodTable pointer

var obj = Unsafe.As<Span<IntPtr>, T>(ref objBuffer); // Convert Span<IntPtr> to T bytes to bytes

Both approaches are generally quite similar, but there’s an interesting distinction - the line Unsafe.As<Span<IntPtr>, T>(ref objBuffer), where we convert a Span<IntPtr> into T.

To understand what’s happening, let’s recall how struct types are laid out in memory. It doesn’t have an object header - its field data starts right at the beginning of the memory block.

So, what does the Span<> structure actually look like under the hood?

public readonly ref struct Span<T>
{
    internal readonly ref T _reference; // Reference to array of elements
    private readonly int _length; // Element array length

    /* Another code */
}

In other words, the first 8 bytes of the Span<> structure represent a pointer - and in our case, that memory contains
the MethodTable. So when we cast a Span<T> into T, we’re effectively interpreting its first field as a reference to our object. C# then treats that pointer as a managed reference to a class instance - which is precisely what we need in this scenario.

It’s also important to mention some limitations. This approach only works on .NET 9.0 and later, because Unsafe.As<,> started supporting allows ref struct as arguments only from that version onward. In earlier versions, such usage is not allowed, which means you can’t simply pass a Span<> this way.

To work around this restriction, I wrote a custom implementation using IL emit. You can find an example here.

A few more fun tricks.

Inheritance

One of the reasons we love classes is for inheritance and all the powerful features it brings. And nothing stops us from leveraging that power - even on the stack.

As a result, we can write a test that looks something like this:

[Theory, AutoData]
public void Safe_ShouldAllocateAndChange_WhenItIsDerivedClass(DerivedClass expected)
{
    // Arrange

    // Act
    var obj = Stack<DerivedClass>.Safe(stackalloc byte[Stack<DerivedClass>.Size]);

    obj.X = expected.X - 1;
    obj.Y = expected.Y;

    BaseClass based = obj;

    based.X = expected.X;

    // Assert

    based.Should().BeEquivalentTo(expected);
    based.ToString().Should().Be(expected.ToString());
}

The entire array is on the stack

How about placing an array on the stack, with all of its elements stored nearby - also on the stack? Turns out, it’s surprisingly straightforward.

There are a couple of important points to keep in mind:

The total size is calculated as Unsafe.SizeOf<T>() * length + 4, which includes space for the array elements plus 4 bytes reserved for the array’s length field
Initializing the array is slightly more involved (just one extra line compared to creating a single object), and essentially boils down to the following:

buffer[0] = IntPtr.Zero; // Optional
buffer[1] = typeof(T[]).TypeHandle.Value; // MethodTable pointer
buffer[2] = length; // Array length

[Theory, AutoData]
public void Safe_ShouldAllocate_WhenItIsArray(ExampleClass[] expected)
{
    // Arrange

    // Act
    var obj = Stack<ExampleClass>.Safe(stackalloc byte[Stack<ExampleClass>.Size * expected.Length + 4], expected.Length);

    for (var i = 0; i < obj.Length; i++)
    {
        var element = Stack<ExampleClass>.Safe(stackalloc byte[Stack<ExampleClass>.Size]);

        element.X = expected[i].X;
        element.Y = expected[i].Y;

        obj[i] = element;
    }

    // Assert
    obj.Should().BeEquivalentTo(expected);
}

Verification & Benchmarking

Perhaps the most interesting and meaningful challenge for our theory is to put it to the test - through real-world benchmarking. Only by measuring actual performance can we understand whether our stack-based approach offers tangible benefits... or not.

To get a clearer picture, we'll walk through a couple of focused scenarios:

Allocating a single class instance on the heap vs. the stack
Allocating 1000 class instances sequentially - again comparing stack and heap memory

Below, you’ll find sample code used to run these benchmarks. We've also included an alternative version that uses the Unsafe approach for direct memory access and control.

[Benchmark]
public void SingleAllocateHeap()
{
    var obj = new ExampleClass();

    obj.X = 1;
    obj.Y = 2;

    GC.KeepAlive(obj);
}

[Benchmark]
public void SingleAllocateStack()
{
    var obj = Stack<ExampleClass>.Safe(stackalloc byte[Stack<ExampleClass>.Size]);

    obj.X = 1;
    obj.Y = 2;
}

[Benchmark]
public void ManyAllocateHeap()
{
    for (var i = 0; i < _n; i++)
    {
        var obj = new ExampleClass();

        obj.X = 1;
        obj.Y = 2;

        GC.KeepAlive(obj);
    }
}

[Benchmark]
public void ManyAllocateStack()
{
    for (var i = 0; i < _n; i++)
    {
        var obj = Stack<ExampleClass>.Safe(stackalloc byte[Stack<ExampleClass>.Size]);

        obj.X = 1;
        obj.Y = 2;
    }
}

And in the end, here's what we get:

Safe

Method	Job	Runtime	Mean	Error	StdDev	Median	Gen0	Allocated
SingleAllocateHeap	.NET 7.0	.NET 7.0	1.9396 ns	0.0553 ns	0.0517 ns	1.9181 ns	0.0029	24 B
SingleAllocateStack	.NET 7.0	.NET 7.0	8.6831 ns	0.1932 ns	0.3677 ns	8.7082 ns	-	-
ManyAllocateHeap	.NET 7.0	.NET 7.0	2,452.9738 ns	22.3611 ns	20.9166 ns	2,454.1597 ns	2.8687	24000 B
ManyAllocateStack	.NET 7.0	.NET 7.0	2,723.5996 ns	0.8523 ns	0.6654 ns	2,723.6259 ns	-	-
SingleAllocateHeap	.NET 8.0	.NET 8.0	1.7152 ns	0.0029 ns	0.0025 ns	1.7155 ns	0.0029	24 B
SingleAllocateStack	.NET 8.0	.NET 8.0	8.7965 ns	0.1961 ns	0.3382 ns	8.6271 ns	-	-
ManyAllocateHeap	.NET 8.0	.NET 8.0	2,478.6933 ns	24.0770 ns	22.5216 ns	2,480.5584 ns	2.8687	24000 B
ManyAllocateStack	.NET 8.0	.NET 8.0	2,684.2186 ns	1.9118 ns	1.4926 ns	2,684.7157 ns	-	-
SingleAllocateHeap	.NET 9.0	.NET 9.0	2.2176 ns	0.0048 ns	0.0045 ns	2.2161 ns	0.0029	24 B
SingleAllocateStack	.NET 9.0	.NET 9.0	0.7736 ns	0.0076 ns	0.0064 ns	0.7749 ns	-	-
ManyAllocateHeap	.NET 9.0	.NET 9.0	2,705.4946 ns	11.6700 ns	10.9161 ns	2,705.4497 ns	2.8687	24000 B
ManyAllocateStack	.NET 9.0	.NET 9.0	1,273.6940 ns	0.3620 ns	0.3023 ns	1,273.7439 ns	-	-

The results clearly show that stack-based allocation outperforms heap allocation - not only in terms of memory usage (
which is expected), but also in raw execution speed when running on .NET 9.0.
However, for .NET 8.0 and 7.0, there’s a noticeable slowdown compared to heap allocation.
This is primarily due to the overhead of generating Unsafe.As<,> dynamically via IL emit at runtime.

Unsafe

Method	Job	Runtime	Mean	Error	StdDev	Gen0	Allocated
SingleAllocateHeap	.NET 7.0	.NET 7.0	1.6922 ns	0.0486 ns	0.0455 ns	0.0029	24 B
SingleAllocateStack	.NET 7.0	.NET 7.0	0.4787 ns	0.0159 ns	0.0149 ns	-	-
SingleAllocateStackOnSpan	.NET 7.0	.NET 7.0	0.9192 ns	0.0174 ns	0.0162 ns	-	-
ManyAllocateHeap	.NET 7.0	.NET 7.0	2,560.6623 ns	18.9084 ns	17.6869 ns	2.8687	24000 B
ManyAllocateStack	.NET 7.0	.NET 7.0	944.7791 ns	5.6593 ns	4.7257 ns	-	-
ManyAllocateStackOnSpan	.NET 7.0	.NET 7.0	1,296.3634 ns	9.2856 ns	8.6857 ns	-	-
SingleAllocateHeap	.NET 8.0	.NET 8.0	2.0119 ns	0.0159 ns	0.0133 ns	0.0029	24 B
SingleAllocateStack	.NET 8.0	.NET 8.0	0.3722 ns	0.0141 ns	0.0118 ns	-	-
SingleAllocateStackOnSpan	.NET 8.0	.NET 8.0	0.5997 ns	0.0182 ns	0.0170 ns	-	-
ManyAllocateHeap	.NET 8.0	.NET 8.0	2,515.6083 ns	8.5975 ns	7.6214 ns	2.8687	24000 B
ManyAllocateStack	.NET 8.0	.NET 8.0	948.0459 ns	7.3097 ns	6.1039 ns	-	-
ManyAllocateStackOnSpan	.NET 8.0	.NET 8.0	1,132.9332 ns	4.7512 ns	4.4443 ns	-	-
SingleAllocateHeap	.NET 9.0	.NET 9.0	2.2379 ns	0.0386 ns	0.0361 ns	0.0029	24 B
SingleAllocateStack	.NET 9.0	.NET 9.0	0.2845 ns	0.0182 ns	0.0161 ns	-	-
SingleAllocateStackOnSpan	.NET 9.0	.NET 9.0	0.4485 ns	0.0133 ns	0.0118 ns	-	-
ManyAllocateHeap	.NET 9.0	.NET 9.0	2,786.9785 ns	23.1452 ns	19.3273 ns	2.8687	24000 B
ManyAllocateStack	.NET 9.0	.NET 9.0	824.4629 ns	1.3196 ns	1.0303 ns	-	-
ManyAllocateStackOnSpan	.NET 9.0	.NET 9.0	962.2158 ns	1.0145 ns	0.8472 ns	-	-

In some cases, the stack-based approach achieved up to a 10x performance boost, clearly demonstrating the raw power and
efficiency of using the stack over the heap - especially when compared to the fully safe alternative.

These results highlight how, with the right setup, stack allocation can significantly outperform more traditional approaches.

Conclusion

This exploration demonstrates that allocating class instances on the stack in C# - while unconventional - is not only technically feasible, but can also yield substantial performance gains in certain scenarios.

We’ve shown that:

Unsafe techniques provide maximum control and efficiency, though they require deep knowledge of memory layout and careful handling to avoid undefined behavior
Safe techniques, made possible in .NET 9 (or emulated in previous versions), offer a surprising degree of flexibility without stepping outside the boundaries of memory safety

These methods aren’t meant to replace the heap in everyday development - but they open up exciting opportunities for
advanced use cases, such as high-performance systems, embedded scenarios, or low-level experimentation.

Mocking gRPC Clients in C#: Fake It Till You Make It

Maksim Zimin — Sun, 08 Dec 2024 11:46:08 +0000

About problem

In the process of developing any software product, one of the key stages is creating tests, as they help ensure the system operates correctly. An integral part of this process is dependency mocking, which allows for isolating the components being tested and minimizing the influence of external factors.

Mocking is an approach that involves creating simulations of system objects or components used during testing. Essentially, mocks are fake implementations of real objects. They are employed to isolate the code under test from its dependencies, whether these are databases, external APIs, or other services. Using mocks helps focus on testing the
logic of a specific component without being reliant on external systems, which might be unavailable, unstable, or complex to emulate.

With the advancement of technology and the shift towards microservice architectures, developers increasingly choose gRPC as a means of service-to-service communication due to its performance, scalability, and сonvenience.

gRPC (Google Remote Procedure Call) is a powerful framework for remote procedure calls (RPC) developed by Google. It enables efficient and fast connections between applications written in different programming languages by leveraging the HTTP/2 protocol and compact binary serialization through Protocol Buffers. This approach makes gRPC an ideal solution for modern distributed systems.

However, with the widespread adoption of gRPC, developers face a new challenge: integrating gRPC clients into tests. Since a gRPC client inevitably becomes one of the core dependencies of an application, it also becomes a critical part of the testing process—and, unfortunately, often introduces additional complexities. Simulating gRPC requests and their
handling requires the use of mocks or specialized tools, which may feel unfamiliar to those accustomed to more traditional REST APIs.

Therefore, a well-thought-out approach to mocking gRPC dependencies is a crucial step towards achieving comprehensive test coverage and ensuring the stability of the system as a whole.

In this article, we will focus on mocking gRPC clients, as the process of mocking the server-side (ServiceBase) does not require any specific actions. Typically, testing the server-side is similar to testing controllers in web applications and is already familiar to many developers.

gRPC clients, on the other hand, are more complex to test due to the nature of their interactions with the server. This process requires modeling various call scenarios, each differing in how they handle data streams. Let's review the main scenarios:

UnaryCall - A standard request-response call. The client sends a request to the server and receives a single response. This scenario is the most common and resembles traditional REST calls.
ClientSideStreaming - A call where the client sends a stream of data to the server. The stream is built progressively, and data is not sent all at once, as is the case with UnaryCall.
ServiceSideStreaming - A call where the client sends a single request to the server and receives a stream of data in response. The server's response is delivered in parts rather than as a single package, as in UnaryCall.
DuplexStreaming - The most complex scenario, where the client and server simultaneously exchange streams of data. This requires implementing bidirectional communication, making both development and testing more challenging.

Each of these scenarios introduces unique challenges to the process of mocking and testing, making the gRPC client a more complex object to work with compared to traditional REST clients.

Options for Mocking gRPC Clients

Moq - One of the most popular mocking libraries in the .NET ecosystem. It allows you to emulate gRPC client methods, define return values, and verify method calls.
Grpc.Core.Testing - A library specifically designed for testing gRPC clients. It provides helper classes like MockCall to simplify mock setup.
Grpc.Net.Testing.Moq - An extension of the Moq library optimized for Grpc.Net.Client. It is a convenient tool that helps minimize the amount of test code required.
Grpc.Net.Testing.NSubstitute - An alternative to the previous option, built on the NSubstitute library. It is ideal for those who prefer its syntax for mocking.

Each of these approaches has its strengths and unique features. Depending on the tools and requirements of your project, you can select the most suitable method for creating gRPC client mocks. In the following sections, we will delve deeper into each option to help you decide which one best meets your needs.

In our testing, we will not consider cases where values are precomputed outside the delegate passed to the Returns<> method.

Let's prepare a sample client

First, let's create a small sample client that will serve as the foundation for the mocking process. This client will be simple yet functional enough to demonstrate the key principles and approaches to testing with mocks.

The client will act as a starting point for developing and testing various interaction scenarios.

syntax = "proto3";

package tests;

service TestService {
  rpc Simple(TestRequest) returns(TestResponse);
  rpc SimpleClientStream(stream TestRequest) returns(TestResponse);
  rpc SimpleServerStream(TestRequest) returns(stream TestResponse);
  rpc SimpleClientServerStream(stream TestRequest) returns(stream TestResponse);
}

message TestRequest {
  int32 val = 1;
}
message TestResponse {
  int32 val = 1;
}

The created service includes four methods, each demonstrating different interaction scenarios typical for gRPC. These methods serve as examples for exploring key service operation models and testing their functionality. Here's a description of each:

Simple - UnaryCall

This method implements a standard request-response interaction. It accepts data from the client and returns an identical response. It's a straightforward example, perfect for demonstrating the basic principles of gRPC.
SimpleClientStream - ClientSideStreaming

This method is designed to handle a stream of data sent by the client. Its task is to calculate the sum of all transmitted values and return it as the result. This illustrates a model where the client sends data incrementally, and the server responds with an aggregated result.
SimpleServerStream - ServiceSideStreaming

This method demonstrates a model where the server returns a stream of data in response to a single client request. The method generates and sends N messages to the client based on the parameters of the request. This approach is often used for transmitting large volumes of data.
SimpleClientServerStream - DuplexStreaming

The most complex and powerful interaction scenario. This method accepts a stream of data from the client, sums it up, and sends the result back as N messages. This example showcases bidirectional interaction, where the client and server exchange data simultaneously.

Simply use Moq

For this implementation, we will exclusively use the Moq library, which is one of the most popular and powerful tools in the .NET ecosystem for creating mocks.

UnaryCall

One of the simplest and most intuitive methods for mocking is the UnaryCall scenario. Its essence lies in the classic "request-response" interaction model, where the client sends a request to the server and expects a single response.

This approach forms the foundation for many systems and scenarios, making it an excellent starting point for learning the mocking process. Its simplicity allows you to focus on the key aspects of testing without having to deal with the complexities of stream-based interactions.

In this example, we will demonstrate how to use Moq to emulate the behavior of a UnaryCall method and configure it to correctly process requests and return the expected results.

[Fact]
public void SimpleTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    mock
        .Setup(c => c.Simple(It.IsAny<TestRequest>(), It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
        .Returns<TestRequest, Metadata, DateTime?, CancellationToken>((r, _, _, _) => new TestResponse { Val = r.Val });

    var client = mock.Object;

    var testRequest = new TestRequest { Val = 42 };

    // Act
    var response = client.Simple(testRequest);

    // Assert
    response.Val.Should().Be(testRequest.Val);
}

[Fact]
public async Task SimpleAsyncTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    mock
        .Setup(c => c.SimpleAsync(It.IsAny<TestRequest>(), It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
        .Returns<TestRequest, Metadata, DateTime?, CancellationToken>(
            (r, _, _, _) => new AsyncUnaryCall<TestResponse>(
                responseAsync: Task.FromResult(new TestResponse { Val = r.Val }),
                responseHeadersAsync: Task.FromResult(new Metadata()),
                getStatusFunc: () => Status.DefaultSuccess,
                getTrailersFunc: () => [],
                disposeAction: () => { }));

    var client = mock.Object;

    // Act
    var request = new TestRequest { Val = 42 };
    var response = await client.SimpleAsync(request);

    // Assert
    response.Val.Should().Be(request.Val);
}

Even a seemingly simple scenario, like mocking a UnaryCall in its asynchronous version, can feel somewhat challenging due to the need to work with AsyncUnaryCall. This class requires specifying multiple parameters, such as tasks for the response, headers, status, and metadata, which significantly increases the workload.

If you aim to implement more complex scenarios, for example, configuring the method's return value based on the parameters of the incoming Request, the task becomes even more complicated. In such cases, you need to dynamically create instances of AsyncUnaryCall<TestResponse>, which adds more code and makes the testing infrastructure more complex.

This can lead to additional time and resource costs for maintaining the tests, especially as the number of such methods grows or if they involve intricate data processing logic.

ClientSideStreaming

This scenario is more complex as it requires handling a stream of incoming messages. Unlike a simple "request-response" call, you need to account for the sequence of data sent by the client. This inevitably makes the mocking code more extensive and harder to comprehend.

In this example, we will emulate a service behavior where all incoming parameters are processed and summed, with the resulting sum returned as the response. This approach requires configuring the mocks to handle each message in the stream correctly, which adds an extra layer of complexity to the implementation of the tests.

To execute this task successfully, it is crucial not only to set up the mock properly but also to ensure that it accurately models the real service's behavior, particularly in the context of streaming data. This will help not only to validate the application's logic but also to uncover potential issues in data processing early in the development cycle.

[Fact]
public async Task SimpleClientStreamTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    var sum = 0;

    var taskCompletionSource = new TaskCompletionSource<TestResponse>();

    var streamWriter = new Mock<IClientStreamWriter<TestRequest>>(MockBehavior.Strict);
    streamWriter
        .Setup(c => c.WriteAsync(It.IsAny<TestRequest>()))
        .Callback<TestRequest>(m => sum += m.Val)
        .Returns(Task.CompletedTask);
    streamWriter
        .Setup(c => c.CompleteAsync())
        .Callback(() => taskCompletionSource.SetResult(new TestResponse { Val = sum }))
        .Returns(Task.CompletedTask);

    var asyncClientStreamingCall = new AsyncClientStreamingCall<TestRequest, TestResponse>(
        requestStream: streamWriter.Object,
        responseAsync: taskCompletionSource.Task,
        responseHeadersAsync: Task.FromResult(new Metadata()),
        getStatusFunc: () => Status.DefaultSuccess,
        getTrailersFunc: () => [],
        disposeAction: () => { });

    mock
        .Setup(c => c.SimpleClientStream(It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
        .Returns(asyncClientStreamingCall);

    var client = mock.Object;

    var requests = Enumerable
        .Range(1, 10)
        .Select(i => new TestRequest { Val = i })
        .ToArray();

    // Act
    var call = client.SimpleClientStream();
    await call.RequestStream.WriteAllAsync(requests);

    // Assert
    var response = await call.ResponseAsync;

    var expected = requests.Sum(c => c.Val);

    expected.Should().Be(response.Val);
}

In this scenario, there arises a need to explicitly define a TaskCompletionSource, which allows deferring the execution of the response calculation until a specific moment. This approach enables delivering the result to the client only after explicitly calling the CompleteAsync method, making it useful for modeling asynchronous behavior.

However, such an implementation significantly complicates the code and increases its size, which can be problematic for large projects or when frequent test updates are required. These additional steps demand more time and resources and also increase the likelihood of errors in the test logic.

ServiceSideStreaming

This example examines a scenario where the client sends a single request containing a number, based on which the server generates and returns a stream of N responses, each including that number.

This approach is commonly used to implement server-side streaming, where the server gradually sends data to the client in response to a single request. It can be useful in cases where large amounts of data need to be transmitted, but not all at once — for instance, when delivering data in batches, updates, or processing results.

When mocking this scenario, it is essential to properly configure the method's behavior to return a data stream that accurately models the real service's functionality. This involves generating a sequence of responses based on the input value and setting up asynchronous behavior to simulate incremental data delivery.

Such tests help ensure that the client logic correctly processes streaming responses and can handle delays, sequential processing, and other aspects of working with data streams effectively.

[Fact]
public async Task SimpleServerStreamTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    mock
        .Setup(
            c => c.SimpleServerStream(
                It.IsAny<TestRequest>(),
                It.IsAny<Metadata>(),
                It.IsAny<DateTime?>(),
                It.IsAny<CancellationToken>()))
        .Returns<TestRequest, Metadata, DateTime?, CancellationToken>(
            (r, _, _, _) =>
            {
                var reader = new Mock<IAsyncStreamReader<TestResponse>>(MockBehavior.Strict);

                var current = reader.SetupSequence(c => c.Current);
                var moveNext = reader.SetupSequence(c => c.MoveNext(It.IsAny<CancellationToken>()));

                for (var i = 0; i < r.Val; i++)
                {
                    moveNext = moveNext.ReturnsAsync(true);
                    current = current.Returns(new TestResponse { Val = r.Val });
                }

                moveNext = moveNext.ReturnsAsync(false);

                return new AsyncServerStreamingCall<TestResponse>(
                    responseStream: reader.Object,
                    responseHeadersAsync: Task.FromResult(new Metadata()),
                    getStatusFunc: () => Status.DefaultSuccess,
                    getTrailersFunc: () => [],
                    disposeAction: () => { });
            });

    var client = mock.Object;

    var testRequest = new TestRequest { Val = 42 };

    // Act
    var call = client.SimpleServerStream(testRequest);

    // Assert
    var responses = await call.ResponseStream
        .ReadAllAsync()
        .ToArrayAsync();

    responses.Should()
        .HaveCount(testRequest.Val).And
        .AllSatisfy(c => c.Val.Should().Be(testRequest.Val));
}

As evident from this scenario, testing server-side streaming requires defining a complex delegate that involves detailed configuration of the Mock<IAsyncStreamReader<>> object. This object plays a crucial role as it handles the sequential delivery of stream data, making its correct configuration essential.

While it is possible to move the setup of Mock<IAsyncStreamReader<>> outside the delegate to improve code readability and structure, this also allows linking the delegate's logic to an external context, making it more manageable. However, even with such an approach, it is not feasible to completely avoid explicitly defining AsyncServerStreamingCall<TestResponse> and creating a mock for IAsyncStreamReader<TestResponse>. These steps are integral to mocking a server-side stream and enable the emulation of asynchronous behavior.

Thus, although this approach is complex to implement, it remains practically the only way to model intricate streaming scenarios in gRPC. That said, creating helper methods for mock configuration or leveraging specialized libraries can significantly simplify the process and reduce the amount of code required, especially when such scenarios frequently appear in tests.

DuplexStreaming

This example combines elements from the two previous scenarios and illustrates the process of mocking more complex logic. In this case, the server receives a stream of messages from the client, processes them, and then returns a stream of N messages, where each message contains the sum of all values sent by the client.

This scenario represents a combination of client-side streaming and server-side streaming, making it one of the most complex types of interactions in gRPC. It requires simultaneous handling of the asynchronous incoming data stream and the generation of an asynchronous outgoing response stream.

When mocking this interaction, it is crucial to address two key aspects:

Emulating the input stream: Configuring the behavior of the Mock<IClientStreamWriter<>> object or a similar structure to handle data sent by the client.
Generating the output stream: Using AsyncServerStreamingCall<> to create a sequence of responses that accurately models the real behavior of the service.

This example highlights the complexity of mocking streaming interactions in gRPC while also demonstrating the importance of precisely configuring mock behavior to simulate real-world scenarios effectively.

[Fact]
public async Task SimpleClientServerStreamTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    mock
        .Setup(c => c.SimpleClientServerStream(It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
        .Returns<Metadata, DateTime?, CancellationToken>(
            (_, _, _) =>
            {
                var requestStream = new Mock<IClientStreamWriter<TestRequest>>(MockBehavior.Strict);
                var responseStream = new Mock<IAsyncStreamReader<TestResponse>>(MockBehavior.Strict);

                var requests = new List<TestRequest>();
                var responses = new List<TestResponse>();

                // Request handling: Collect all incoming messages
                requestStream
                    .Setup(c => c.WriteAsync(It.IsAny<TestRequest>()))
                    .Callback<TestRequest>(r => requests.Add(r))
                    .Returns(Task.CompletedTask);

                requestStream
                    .Setup(c => c.CompleteAsync())
                    .Callback(
                        () =>
                        {
                            // Create responses based on the requests
                            var sum = requests.Sum(r => r.Val);
                            responses.AddRange(Enumerable.Repeat(new TestResponse { Val = sum }, requests.Count));
                        })
                    .Returns(Task.CompletedTask);

                // Response stream setup
                var index = -1;

                responseStream
                    .Setup(c => c.MoveNext(It.IsAny<CancellationToken>()))
                    .Returns(() => Task.FromResult(++index < responses.Count));

                responseStream
                    .SetupGet(c => c.Current)
                    .Returns(() => responses[index]);

                return new AsyncDuplexStreamingCall<TestRequest, TestResponse>(
                    requestStream: requestStream.Object,
                    responseStream: responseStream.Object,
                    responseHeadersAsync: Task.FromResult(new Metadata()),
                    getStatusFunc: () => Status.DefaultSuccess,
                    getTrailersFunc: () => [],
                    disposeAction: () => { });
            });

    var client = mock.Object;

    var testRequests = Enumerable
        .Range(start: 1, count: 42)
        .Select(_ => new TestRequest { Val = 1 })
        .ToArray();

    // Act
    var call = client.SimpleClientServerStream();

    await call.RequestStream.WriteAllAsync(testRequests);

    // Assert
    var responses = await call.ResponseStream
        .ReadAllAsync()
        .ToArrayAsync();

    var expected = testRequests.Sum(c => c.Val);

    responses.Should()
        .HaveCount(testRequests.Length).And
        .AllSatisfy(c => c.Val.Should().Be(expected));
}

As evident from the example, implementing bidirectional streaming requires writing a significant amount of auxiliary code. To fully emulate stream behavior, additional state variables must be introduced to manually implement a state machine that manages the sequential return of elements in the style of IEnumerable<>.

This approach significantly complicates the code, making maintenance more challenging, especially when the mock needs to be adapted for new scenarios. For instance, if instead of accumulating messages, sequential processing of each element is required, or if new stream processing logic needs to be added, the existing code would demand substantial modifications.

This complexity and the high maintenance cost highlight the need for more elegant solutions, such as specialized libraries or utility tools that can automate part of the work and simplify the implementation of complex streaming interactions.

Conclusion

In my opinion, calling this approach convenient is quite difficult. While it works well for mocking simple endpoints like "request-response" (UnaryCall), where everything looks relatively compact and maintainable, the situation becomes significantly more complicated when it comes to streaming endpoints—be it client-side, server-side, or bidirectional
streaming. Testing such scenarios requires creating and maintaining a considerable amount of auxiliary code, including classes implementing IAsyncStreamReader<> and complex state management logic.

This becomes particularly problematic in projects where mocking such endpoints is frequently needed or where diverse stream processing scenarios must be tested. In these cases, the amount of required code grows significantly, and its maintenance can become a real headache.

If using third-party libraries to simplify the mocking of gRPC clients is not an option, I strongly recommend encapsulating the client logic into a separate class, such as class MyClient : IClient. This approach allows you to create an abstract interface that is decoupled from the classes provided by the Grpc library.

This not only simplifies testing but also makes the code more flexible and easier to maintain. Instead of directly working with gRPC clients, tests can operate on your custom abstraction, allowing it to be easily replaced with a mock or another implementation without embedding complex mocking logic directly into the tests. This approach also improves code readability and makes future extensions easier to implement.

Grpc.Core.Testing

This is a deprecated library that includes the TestCalls class, which provides helper methods for generating gRPC calls, with one method for each call type. In earlier versions, the library handled the proper initialization of additional parameters. However, in its current state, it serves only as a wrapper around constructors.

The Grpc.Core.Testing library is a deprecated tool that was initially created to simplify the testing of gRPC applications. It offers the TestCalls class, which includes a set of helper methods for generating various types of gRPC calls. Specifically, the library provides methods for the main call scenarios: UnaryCall, ClientStreamingCall, ServerStreamingCall, and DuplexStreamingCall.

In the library's earlier stages, it took responsibility for correctly initializing all the additional parameters required for gRPC operations. This significantly eased the developers' workload, reducing the complexity of writing tests and enabling them to focus on testing application logic more quickly.

However, as gRPC evolved and newer versions were introduced, the library's functionality gradually became limited to serving as a simple wrapper around gRPC object constructors. Instead of fully automating the initialization process, it now provides only basic templates that require manual adjustments. This has reduced its usefulness for modern projects,
where developers are still required to handle parameter configuration themselves.

For example, implementing a UnaryCall using the library would look like this:

[Fact]
public async Task SimpleAsyncDelegateTest()
{
    // Arrange
    var mock = new Mock<TestService.TestServiceClient>(MockBehavior.Strict);

    mock
        .Setup(c => c.SimpleAsync(It.IsAny<TestRequest>(), It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
        .Returns<TestRequest, Metadata, DateTime?, CancellationToken>(
            (r, _, _, _) =>  TestCalls.AsyncUnaryCall(
                responseAsync: Task.FromResult(new TestResponse { Val = r.Val }),
                responseHeadersAsync: Task.FromResult(new Metadata()),
                getStatusFunc: () => Status.DefaultSuccess,
                getTrailersFunc: () => [],
                disposeAction: () => { }));

    var client = mock.Object;

    // Act
    var request = new TestRequest { Val = 42 };
    var response = await client.SimpleAsync(request);

    // Assert
    response.Val.Should().Be(request.Val);
}

In my opinion, using this library in modern projects is hardly justified. The main reason is its deprecated status and limited functionality, which no longer offers meaningful simplification for writing tests.

When the library first appeared, it was useful for automating the initialization of complex structures and parameters required for testing gRPC calls. However, over time, its capabilities have become restricted, and it is now essentially a simple wrapper around constructors, failing to address real development challenges.

For projects that require flexibility, convenience, and minimal boilerplate code, using this library tends to add unnecessary complexity rather than reduce it. Instead, I recommend focusing on more modern and relevant tools that provide a user-friendly API and significantly simplify the process of mocking gRPC calls.

Grpc.Net.Testing.Moq

Description

Grpc.Net.Testing.Moq is a library designed to eliminate the excessive boilerplate code that inevitably arises when using other tools for mocking gRPC. Its main advantage lies in its simplicity and ease of use, achieved through integration with the popular Moq library.

Instead of requiring manual setup of complex structures and classes characteristic of gRPC, Grpc.Net.Testing.Moq offers an intuitive approach to mocking. It abstracts away low-level details, allowing developers to focus on testing business logic while minimizing the time spent configuring mocks.

The library provides convenient tools for managing gRPC call mocking, simplifying their use even in complex scenarios, such as data streaming or bidirectional calls. As a result, developers can significantly reduce the amount of auxiliary code and improve the readability of their tests, making it an excellent choice for modern projects.

Using

Let’s review the same scenarios we discussed earlier for the Moq library. Using Grpc.Net.Testing.Moq, the mocking process becomes significantly simpler and requires less boilerplate code while maintaining flexibility and ease of configuration.

// UnaryCall

mock
    .Setup(c => c.SimpleAsync(It.IsAny<TestRequest>(), It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync<TestService.TestServiceClient, TestRequest, TestResponse>(r => new TestResponse { Val = r.Val });

// ClientSideStreaming

mock
    .Setup(c => c.SimpleClientStream(It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync(r => new TestResponse { Val = r.Sum(c => c.Val) });

// ServerSideStreaming

mock
    .Setup(c => c.SimpleServerStream(It.IsAny<TestRequest>(), It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync<TestService.TestServiceClient, TestRequest, TestResponse>(r => Enumerable.Range(1, r.Val).Select(_ => new TestResponse { Val = r.Val }));

// DuplexStreaming

mock
    .Setup(c => c.SimpleClientServerStream(It.IsAny<Metadata>(), It.IsAny<DateTime?>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync(
        r =>
        {
            var sum = r.Sum(c => c.Val);
            return Enumerable.Range(1, sum).Select(_ => new TestResponse { Val = sum });
        });

From the provided code, the key advantage of Grpc.Net.Testing.Moq becomes immediately clear: the minimal amount of code required to configure client mocking. The library significantly simplifies the process and eliminates the need for cumbersome constructs typical of manual approaches or other tools.

Main advantages

Flexibility in mocking configuration - The library supports multiple ways to configure client behavior.
Particularly beneficial for streaming - The most significant improvement is felt when working with streaming methods. Thanks to the library, there is no need to create custom wrappers or implement complex logic to manage incoming and outgoing data streams. This allows developers to focus on testing business logic rather than low-level stream configuration.
Readability and ease of maintenance - Code written using Grpc.Net.Testing.Moq becomes noticeably simpler and easier to understand. This is especially important in large projects where tests can be complex and require frequent updates.

The Grpc.Net.Testing.Moq library clearly excels in convenience and ease of use, particularly in the context of streaming methods. It not only minimizes boilerplate code but also makes the mocking process more intuitive and efficient.

Useful links

Conclusion

Based on the review of various solutions for mocking gRPC clients, we can summarize the findings in a comparison table that highlights their features, advantages, and limitations. This format makes it easier to understand which solution is best suited for a specific project or task.

Library	Advantages	Disadvantages	Recommendations for Use
Moq	+ Flexibility and control over mock configuration + Well-suited for simple calls like `UnaryCall` + Broad support in the .NET ecosystem	+ Requires writing a lot of boilerplate code + Complex for streaming: manual mock creation for streams and state management is needed	Suitable for testing simple calls and scenarios where detailed client behavior configuration is important.
Grpc.Core.Testing	+ Provides wrappers for gRPC calls + Simplifies testing basic scenarios	+ Deprecated + Does not simplify complex scenarios like streaming + Reduced to a wrapper around constructors	Useful for projects using older versions of gRPC, but for modern solutions, it’s better to choose contemporary libraries.
Grpc.Net.Testing.Moq	+ Minimal boilerplate code + Supports various ways to configure mocks (delegates, fixed responses, etc.) + Significantly simplifies streaming + Integration with popular libraries like Moq/NSubstitute	+ Offers less control over low-level aspects of mocking	Ideal for modern projects that need quick and efficient gRPC client mocking, especially when working with streaming scenarios.

The comparison of solutions for mocking gRPC clients shows that the choice of tool depends on the specific requirements of the project, the complexity of the scenarios, and the need to support modern development standards.

If a project involves simple request-response scenarios (UnaryCall) and requires maximum control over mock configuration, the standard approach using Moq remains a reliable option. However, its complexity and the amount of boilerplate code make it less suitable for complex streaming scenarios.
For legacy systems or supporting projects on older versions of gRPC, the Grpc.Core.Testing library can be considered. Nevertheless, due to its deprecated status and limited capabilities, its use is justified only when no other alternatives are available.
For modern projects, especially those heavily utilizing streaming calls, the optimal solution is Grpc.Net.Testing.Moq or Grpc.Net.Testing.NSubstitute. These tools offer minimal boilerplate code, flexibility in mock configuration, and significant simplification of working with streams. They are particularly useful for accelerating development and improving test readability.

Mastering the mocking of gRPC clients is a key step toward building more robust and testable applications. I’ve outlined several approaches, highlighting the advantages and limitations of each tool. Try applying the methods described and choose the one that best aligns with your goals and requirements. Happy coding!

C++ Calls C#: A Tale of Friendship Across Runtimes

Maksim Zimin — Wed, 27 Nov 2024 17:04:51 +0000

A little backstory:

Recently, I faced a task: to create a WFX plugin for Total Commander.

A WFX (Web File System) plugin for Total Commander is a plugin that allows users to access various remote file systems and services directly from the Total Commander interface. The .wfx file is essentially a renamed .dll (dynamic-link
library).

Primarily, I work with C#, but Total Commander, for which I had to create the plugin, is written in C++ and uses LoadLibrary for dynamically loading plugins. This imposes certain constraints and requires a special approach to ensure proper interaction between the runtime environments of the two languages.

С++ and Csharp

Calling C# code from C++ is more challenging for several reasons:

Interoperability Challenges: C++ and C# have different runtime environments. C++ compiles directly into machine code, while C# runs on the .NET virtual machine (CLR). This requires interoperability configurations, adding complexity.
Name Mangling: C++ uses name mangling to support function overloading and templates, which makes calling C++ functions from other languages, including C#, more complicated.
Build Process: C++ requires specific tools for compilation and linking, complicating integration with C# projects built on .NET.

On the other hand, calling C++ code from C# is simpler due to the following:

P/Invoke: C# supports the Platform Invocation (P/Invoke) mechanism, simplifying calls to native C/C++ libraries from C# code.
Pointer Handling: C# provides robust tools for working with pointers and unsafe code, making interaction with native libraries easier.
Minimal Configuration Requirements: The .NET runtime provides tools and libraries to simplify interaction with native code, reducing the need for manual configuration and memory management.

The article will describe the following integration methods between C++ and C#:

Loading the .NET Runtime manually within C++ code and injecting a .NET assembly into it.
Using Ahead-of-Time (AOT) compilation to build native libraries.
Using a COM component for interaction.
Modifying IL Code after building the library.

Test program for `.dll` validation

Before diving into the approaches, a simple C++ program was developed to test the functionality of created .dll files. The program includes the call_library function for loading a library and verifying its functionality. This approach helps identify potential issues early, ensuring reliability and stability in the final product.

void call_library(const std::string& file_name)
{
    const std::wstring name(file_name.begin(), file_name.end());
    const auto library_handle = LoadLibrary(name.c_str());

    if (library_handle == nullptr)
    {
        std::cout << "Cannot open library by path '" << file_name << "'\n";
        return;
    }

    std::cout << "Success LoadLibrary(\"" << file_name << "\")\n";

    const auto proc_name = "calculate";
    const auto proc_address = (proc)GetProcAddress(library_handle, proc_name);

    if (proc_address == nullptr)
    {
        std::cout << "Cannot get proc '" << proc_name << """' in file '" << file_name << "'\n";
        return;
    }

    std::cout << "Success GetProcAddress(\"" << proc_name << "\")\n";

    std::cout << "Calculation result is " << proc_address(1, 1) << '\n';
}

Loading .NET Runtime for .NET Core 3.0+

This example is the most complex among those presented. Yet, what could be simpler than initializing the .NET Runtime and loading an assembly into it, allowing you to retrieve function pointers as needed?

This approach demands a deep understanding of both C# and C++. You must carefully configure all aspects of cross-platform interaction to ensure correct code execution. While manually initializing the .NET Runtime might seem daunting, it is one of the most powerful methods for integrating C# and C++.

This method requires meticulous attention to detail and a solid knowledge of how the .NET platform operates. At first glance, it may appear overwhelming, but once you grasp all its nuances, you will be able to seamlessly combine two powerful programming languages into a cohesive solution.

As an example, let's build a simple C# API that will be invoked from a C++ library. The key feature of this method is defining a delegate for the method signature.

The use of a delegate is optional and can be omitted entirely if desired. To achieve this, the exported method must be
annotated with the UnmanagedCallersOnly attribute. This attribute specifies that the method can be called directly
from unmanaged code, bypassing the need for a delegate.

When invoking the load_assembly_and_get_function_pointer function, instead of passing the delegate name, you simply
use the constant UNMANAGEDCALLERSONLY_METHOD. This approach streamlines the process by removing the overhead of
defining and managing a delegate while ensuring seamless interoperability between managed and unmanaged code.

For a practical example of this implementation, refer to the provided
example here.

public static class Api
{
    public delegate int CalculateDelegate(int a, int b);

    public static int Calculate(int a, int b) => a + b;
}

To run the resulting assembly, we need to write some C++ code that initializes the .NET Runtime, loads our assembly, and provides a pointer to the desired function.

The initialization of the .NET Runtime relies on hostfxr.dll, which provides the following functions:

hostfxr_initialize_for_runtime_config - Initializes the .NET Runtime using the runtime configuration file.
hostfxr_get_runtime_delegate - Used to retrieve the load_assembly_and_get_function_pointer_fn function.
load_assembly_and_get_function_pointer_fn - Used to obtain a pointer to a function from the .NET assembly.
hostfxr_close - A function to shut down the .NET Runtime.

typedef int (*proc)(int, int);

void run()
{
    // Step 1: Get hostfxr procedures
    const auto hostfxr_library = LoadLibraryW(L"hostfxr.dll");

    const auto init_proc = "hostfxr_initialize_for_runtime_config";
    const auto runtime_proc = "hostfxr_get_runtime_delegate";
    const auto close_proc = "hostfxr_close";

    const auto init_fptr = (hostfxr_initialize_for_runtime_config_fn)GetProcAddress(hostfxr_library, init_pr
    const auto get_delegate_fptr = (hostfxr_get_runtime_delegate_fn)GetProcAddress(hostfxr_library, runtime_
    const auto close_fptr = (hostfxr_close_fn)GetProcAddress(hostfxr_library, close_proc);

    if (!(init_fptr && get_delegate_fptr && close_fptr))
        throw std::runtime_error("Failed to load hostfxr");

    const fs::path runtime_config_path = params_.assembly + L".runtimeconfig.json";

    // Step 2: Initialize the .NET Core runtime
    hostfxr_handle context = nullptr;

    int rc = init_fptr(runtime_config_path.c_str(), nullptr, &context);
    if (rc != 0 || context == nullptr)
        throw std::runtime_error("Failed to initialize runtime");

    // Step 3: Get the load_assembly_and_get_function_pointer delegate
    load_assembly_and_get_function_pointer_fn load_assembly_and_get_function_pointer = nullptr;

    rc = get_delegate_fptr(context,
                           hdt_load_assembly_and_get_function_pointer,
                           (void**)&load_assembly_and_get_function_pointer);
    if (rc != 0 || load_assembly_and_get_function_pointer == nullptr)
    {
        close_fptr(context);
        throw std::runtime_error("Failed to get load_assembly_and_get_function_pointer delegate");
    }

    // Step 4: Load the managed assembly and get a function pointer to the C# method
    rc = load_assembly_and_get_function_pointer(
        (params_.assembly + L".dll").c_str(), // assembly file
        params_.type.c_str(), // full qualified type
        params_.method.c_str(), // method
        params_.delegate.c_str(), // delegate full qualified type
        nullptr,
        (void**)&proc_);

    if (rc != 0 || proc_ == nullptr)
    {
        close_fptr(context);
        throw std::runtime_error("Failed to get managed method pointer");
    }

    // Step 5: Call delegate

    auto result = proc_(1,1);

    close_fptr(context);
}

Limitations of this method:

This method relies on the new APIs provided by hostfxr.h and coreclr_delegates.h, which are not available in earlier versions such as .NET Framework. As a result, its usage is limited to modern technologies, which may not always align with the needs of legacy projects.
For this method to work, the specific version of the .NET Runtime under which your .dll was built must be installed. Without the appropriate runtime, the project cannot function correctly, adding additional requirements and effort for setting up the environment.

Useful links:

Loading .NET Runtime for .NET Framework/.NET Standard

This method is fundamentally similar to the previous one but with one significant difference: it uses an older API to launch the .NET host. Despite their similarities, this approach relies on a well-established set of APIs used before newer methods were introduced. It allows you to initialize the .NET Runtime, utilize the assembly, and access the
required functions.

This method may involve additional steps and demand greater attention to detail, particularly regarding cross-platform interactions and memory management. However, mastering this approach enables you to work with older infrastructure, which can be beneficial for specific scenarios and legacy projects.

To begin, let's write the API that we will use:

Here, there is no need to define a delegate, as was required in the method described above.

public static class Api
{
    public static int Calculate(int a, int b) => a + b;
}

Now, to run the resulting .dll, we need to write C++ code that will handle initializing the .NET Runtime and loading the assembly into it.

In this case, coreclr.dll is used instead of hostfxr.dll.

Key Differences:

Functionality Level: coreclr.dll operates at the application execution level and handles all aspects of managing executable code, whereas hostfxr.dll functions at the host level and is responsible for preparing the runtime environment.
Purpose: coreclr.dll directly executes .NET code, while hostfxr.dll provides the infrastructure for initializing and loading the runtime, acting as an entry point for hosts.

Functions Provided by coreclr.dll:

coreclr_initialize - Initializes and starts the .NET Runtime.
coreclr_create_delegate - Creates a delegate for a function from the assembly.
coreclr_shutdown - Shuts down the .NET Runtime.

typedef int (*proc)(int, int);

void run()
{
   const auto executable_path = fs::current_path();
   const auto assembly_path = executable_path / (params_.assembly + ".dll;");

   // Step 1: Load coreclr.dll
   const auto coreclr_file_name = "coreclr.dll";
   const auto paths = split(getenv("PATH"), ';'); // Getting env 'PATH'
   const auto runtime_path = find_path(coreclr_file_name, paths); // .NET Runtime path

   const auto core_clr = LoadLibraryExA(coreclr_file_name, nullptr, 0);

   if (core_clr == nullptr)
       throw std::runtime_error("Failed to load CoreCLR");

   // Step 2: Get CoreCLR hosting functions
   const auto initialize_core_clr = (coreclr_initialize_ptr)GetProcAddress(core_clr, "coreclr_initialize");
   const auto create_managed_delegate = (coreclr_create_delegate_ptr)GetProcAddress(
       core_clr, "coreclr_create_delegate");
   const auto shutdown_core_clr = (coreclr_shutdown_ptr)GetProcAddress(core_clr, "coreclr_shutdown");

   if (!(initialize_core_clr && create_managed_delegate && shutdown_core_clr))
       throw std::runtime_error("Cannot get coreclr procedures");

   // Step 3: Construct AppDomain properties used when starting the runtime
   // Construct the trusted platform assemblies (TPA) list
   std::string tpa_list(assembly_path.string());
   for (const auto& file : fs::directory_iterator(runtime_path))
   {
       auto file_name = file.path().string();
       if (std::regex_match(file_name, std::regex(".*.dll$")))
           tpa_list += file_name + ';';
   }

   // Define CoreCLR properties
   const char* property_keys[] = {
       "TRUSTED_PLATFORM_ASSEMBLIES"
   };
   const char* property_values[] = {
       tpa_list.c_str(),
   };

   // Step 4: Start the CoreCLR runtime
   void* host_handle;
   unsigned int domain_id;
   int hr = initialize_core_clr(
       executable_path.string().c_str(), // AppDomain base path
       "SampleHost", // AppDomain friendly name
       sizeof(property_keys) / sizeof(char*), // Property count
       property_keys, // Property names
       property_values, // Property values
       &host_handle, // Host handle
       &domain_id); // AppDomain ID

   if (hr < 0)
       throw std::runtime_error("coreclr_initialize failed - status: " + std::to_string(hr));

   // Step 5: Create delegate to managed code
   hr = create_managed_delegate(
       host_handle,
       domain_id,
       params_.assembly.c_str(),
       params_.type.c_str(),
       params_.method.c_str(),
       (void**)&proc_);

   if (hr != S_OK)
   {
       shutdown_core_clr(host_handle, domain_id);
       throw std::runtime_error("coreclr_create_delegate failed - status: " + std::to_string(hr));
   }

   // Step 6: Call delegate

   auto result = proc_(1,1);

   shutdown_core_clr(host_handle, domain_id);
}

Limitations:

This approach works with all versions of the .NET Runtime; however, it is primarily recommended for legacy runtimes, such as the .NET Framework.
Successful execution requires the corresponding .NET Runtime version that the .dll was built for to be installed on the system. If the required runtime version is missing, the library cannot be loaded or executed.

Useful links:

Using C++/CLI as a Wrapper

One of the most common and convenient methods for integrating C++ and C# is using a wrapper based on C++/CLI. This approach seamlessly bridges the two languages, leveraging the power and flexibility of each.

Firstly, a C++/CLI wrapper serves as a bridge between managed .NET code and unmanaged C++ code. This is especially useful when you need to use existing C++ code in C# projects or, conversely, integrate new .NET features into legacy C++
applications.

Additionally, C++/CLI provides excellent tools for working with pointers and memory management, enabling developers to create highly efficient and performant applications. This method also promotes better code readability and maintainability, as developers can use familiar tools and libraries.

In summary, utilizing a C++/CLI wrapper is not only a standard but also a powerful way to integrate C++ and C#, ensuring smooth and efficient interaction between these two programming languages.

To begin, let's describe the .NET library that will be called from C++.

public static class Api
{
    public static int Calculate(int a, int b) => a + b;
}

Next, we create a C++/CLI library (built with the /clr flag) where we define the header and cpp files.

// Api.h
#define EXTERN_DLL_EXPORT extern "C" __declspec(dllexport)

EXTERN_DLL_EXPORT int calculate(int a, int b);

// Api.cpp
#include "Api.h"

int calculate(int a, int b)
{
    return CppCli::Api::Api::Calculate(a, b);
}

In the end, we get three files:

dotnet.dll, containing the .NET assembly.
cppcli.dll, containing the C++/CLI assembly.
cppcli.runtimeconfig.json - configuration file for initializing the .NET Runtime.

To ensure that the calculate function is exported in our dll, we can use the dumpbin utility. This tool allows us to view the list of exported functions. For example, by using the command dumpbin /exports, we can easily check whether our calculate function is present in the dll.

This method provides a clear view of which functions are available for use and helps confirm the correctness of our library before integrating it into projects. In this way, we can not only verify the exported functions but also ensure that they are properly integrated into our application.

File Type: DLL

  Section contains the following exports for cppcli.dll

    00000000 characteristics
    FFFFFFFF time date stamp
        0.00 version
           1 ordinal base
           1 number of functions
           1 number of names

    ordinal hint RVA      name

          1    0 00004000 calculate = calculate

Limitations:

This method is directly compatible only with .NET Framework and .NET Core, meaning its application is limited to these versions of the .NET runtime. Consequently, it cannot be used with other types of .NET, which should be considered when choosing an appropriate approach. For working with .NET Standard, you would need to create a wrapper library.
Proper functioning of this method requires an installed .NET Runtime. Without the required version of the runtime, your project will not function correctly, adding specific requirements for the development environment and the installation of necessary components. Ensure that the .NET Runtime matches the version under which your library was built.

Useful links:

Full sample

Modifying IL Code (.export Instruction)

One of the most unusual and intriguing methods for integrating C++ and C# is modifying the Intermediate Language (IL) code after compiling a C# project. This is a highly creative approach that allows changes to be made directly at the intermediate language level used by .NET.

This method can unlock new possibilities for interaction between the two languages, giving developers the flexibility to manipulate the code even after the compilation process is complete. While it requires a deep understanding of C#, C++, and Intermediate Language, it also presents an exciting challenge that can significantly broaden your development
horizons.

First, let's define the C# library.

public static class Api
{
    public static int Calculate(int a, int b) => a + b;
}

After building the project, we will get a .dll file. Next, we need to run the command ildasm /out:output.il filename.dll. When we open the resulting .il file, we can see the IL Code. In our case, we are interested in the Calculate function, which is represented by the following code:

.method public hidebysig static int32  Calculate(int32 a,
                                               int32 b) cil managed
{
    // Code size       4 (0x4)
    .maxstack  8
    IL_0000:  ldarg.0
    IL_0001:  ldarg.1
    IL_0002:  add
    IL_0003:  ret
} // end of method TestApi::Calculate

At the beginning of this method, you need to add an instruction in the format .export [index] as name, so it becomes:

.method public hidebysig static int32  Calculate(int32 a,
                                               int32 b) cil managed
{
    .export [1] as calculate
    // Code size       4 (0x4)
    .maxstack  8
    IL_0000:  ldarg.0
    IL_0001:  ldarg.1
    IL_0002:  add
    IL_0003:  ret
} // end of method TestApi::Calculate

After modifying the IL Code, it needs to be reassembled using the command:
ilasm /dll /out:dotnet.dll /PE64 /x64 output.il.

Now, by applying the dumpbin /exports utility to the new library, you can obtain the following result:

File Type: DLL

  Section contains the following exports for dotnet.dll

    00000000 characteristics
    673106E9 time date stamp Sun Nov 10 20:18:01 2024
        0.00 version
           1 ordinal base
           1 number of functions
           1 number of names

    ordinal hint RVA      name

          1    0 0000276A calculate

The resulting new library can be used via LoadLibrary in C++.

Taking this idea further, you can combine .NET Framework and .export to create a wrapper library for a library built on .NET Standard. This approach opens up additional possibilities for cross-language integration. It allows you to take advantage of both worlds: the functionality and extensive capabilities provided by .NET Framework, and the compatibility
and cross-platform support of .NET Standard.

This method enables the creation of powerful and flexible solutions that can operate in various environments while ensuring a high level of compatibility and efficiency. It requires attention to detail and knowledge of the specific features of both frameworks, but when implemented correctly, it can significantly enhance the performance and
functionality of your application.

Limitations:

This method works only with .NET Framework. However, by using a wrapper library, it can also support .NET Standard libraries, significantly expanding its range of applications.
Proper functioning of this approach requires an installed .NET Runtime. This means that the corresponding .NET runtime environment must be present on the user's machine for the application to execute successfully.
This method relies on the use of the Global Assembly Cache (GAC), which allows versioning and dependency management for libraries at the system level.
Unfortunately, this method is limited to the Windows operating system. While this restricts its use in cross-platform solutions, it is ideally suited for applications developed and run in a Windows environment.

Useful links:

Full sample

Ahead-of-Time Compilation (AOT)

One of the most modern and advanced methods for integrating C# and C++ code is using the Ahead-of-time compilation(AOT). This method
involves compiling C# code directly into native machine code ahead of time, rather than relying on Just-In-Time (JIT) compilation during runtime.

AOT compilation offers numerous advantages, such as:

Increased performance: Since the code is already compiled into machine code, there is no need to spend time on compilation during runtime, making the application execute faster.
Reduced startup time: Applications using AOT can start up faster because there is no need to compile the code at launch.
Lower memory consumption: AOT compilation helps reduce memory usage as the compiled code is optimized and does not require resources for runtime compilation.

This approach unlocks new possibilities for creating highly efficient and performant applications, combining the power of C# and C++ in a single project. AOT compilation is particularly valuable in scenarios requiring maximum performance and stability, such as game development, scientific applications, and other computationally intensive tasks.

However, the AOT method has its limitations:

Executable size: AOT compilation can significantly increase the size of the final executable, as all the code is compiled ahead of time.
Library compatibility: Some libraries and features that rely on JIT may not be supported with AOT compilation, limiting the availability of certain tools and technologies.
Optimizations: AOT compilation may not always achieve all possible optimizations available with JIT, as JIT can make decisions based on runtime-specific data.

Within the AOT framework, the UnmanagedCallersOnly attribute can be utilized. UnmanagedCallersOnly is a .NET attribute that specifies a method can be called directly from native code without using interop mechanisms like P/Invoke. This allows the method to be invoked directly from C++ code, bypassing additional layers of interaction, which
can enhance performance.

Let's describe our C# library:

public static class Api
{
    [UnmanagedCallersOnly(EntryPoint = "Calculate")]
    public static int Calculate(int a, int b) => a + b;
}

It is also necessary to modify the .csproj file and add:

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>

After running the command dotnet publish -r win-x64, we obtain a .dll file. To ensure that the library correctly exports the required functions, you can use the dumpbin utility and execute the command dumpbin /exports.

File Type: DLL

  Section contains the following exports for dotnet.dll

    00000000 characteristics
    FFFFFFFF time date stamp
        0.00 version
           1 ordinal base
           2 number of functions
           2 number of names

    ordinal hint RVA      name

          1    0 000B5060 Calculate = Calculate
          2    1 001756B0 DotNetRuntimeDebugHeader = DotNetRuntimeDebugHeader

Limitations:

Features like Assembly.Load and Reflection cannot be used. This restriction means that the library cannot perform dynamic assembly loading or runtime code manipulation, which might be required for more complex and flexible scenarios.
It's important to note that .NET 8 supports only the x64 architecture, while .NET 9 expands this support to include both x64 and x86 architectures. This limitation may affect the compatibility of your application with different systems and platforms, requiring careful consideration during project planning and implementation.

Useful links:

Using COM Components

The last method worth considering is the use of COM (Component Object Model) technology. This option offers the least flexibility compared to the previous solutions, as it requires implementation efforts both on the library developer's side and on the consumer's side.

COM interfaces can be useful in scenarios where the consumer of your code can only work with COM components. For example, if you are integrating your library into legacy systems or applications built on COM, this approach might be the only option.

However, despite its applicability in certain cases, this method has its limitations and can be inconvenient to use if strict compatibility with COM technologies is not required. In my case, this method was not suitable, as the project's requirements extended beyond the capabilities provided by COM.

Thus, COM technology should only be considered when you have strict compatibility requirements or other justified reasons for its use. In other cases, it may be more appropriate to explore more modern and flexible options for integrating C# and C++.

To begin, you should define a .NET library that consists of a COM interface and its implementation.

[ComVisible(true)]
[InterfaceType(ComInterfaceType.InterfaceIsDual)]
public interface IComInterface
{
    int Calculate(int a, int b);
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public sealed class ComInterface : IComInterface
{
    public int Calculate(int a, int b) => a + b;
}

Additionally, to build the COM library, you will need to modify the .csproj file and include the following:

<PropertyGroup>
    <ComVisible>true</ComVisible>
</PropertyGroup>

The next step is to register the resulting .dll. To accomplish this, you can define a Target that will not only publish the library as a COM component but also register it in the Global Assembly Cache (GAC).

IMPORTANT: Administrator privileges are required for gacutil and regasm to work.

<Target Name="ComRegister" AfterTargets="Build">
    <Message Text="Register COM component" Importance="high"/>
    <Exec Command="C:\Windows\Microsoft.NET\Framework64\v4.0.30319\regasm $(TargetDir)$(AssemblyName).dll /codebase /tlb:$(AssemblyName).tlb"/>

    <Message Text="Publish TLB" Importance="high"/>
    <Copy SourceFiles="$(TargetDir)$(AssemblyName).tlb" DestinationFolder="$(ProjectDir)/bin/publish/"/>
    <Copy SourceFiles="$(TargetDir)$(AssemblyName).dll" DestinationFolder="$(ProjectDir)/bin/publish/"/>

    <Message Text="Add to GAC" Importance="high"/>
    <Exec Command="gacutil /i $(TargetDir)$(AssemblyName).dll"/>
</Target>

In this case, using the LoadLibrary function is not suitable, so it is necessary to develop an alternative client to load the library, which is now represented by a .tlb file.

#import "../Com/bin/publish/Com.tlb" raw_interfaces_only

#include <iostream>

int main()
{
    HRESULT hr = CoInitialize(nullptr); // Initialize COM
    if (FAILED(hr))
    {
        std::cerr << "Failed to initialize COM." << std::endl;
        return -1;
    }

    std::cout << "Successfully initialized COM." << std::endl;

    try
    {
        // Create an instance of the COM class
        Com::IComInterfacePtr comObject;
        hr = comObject.CreateInstance(__uuidof(Com::ComInterface));
        if (FAILED(hr))
        {
            std::cerr << "Failed to create COM object. Status - " << std::hex << hr << std::endl;
            CoUninitialize();
            return -1;
        }

        std::cout << "Successfully created COM object." << std::endl;

        // Call the method
        long result = 0;
        comObject->Calculate(1, 1, &result);

        std::cout << "Calculation result is " << result << '\n';
    }
    catch (const _com_error& e)
    {
        std::cerr << "COM error: " << e.ErrorMessage() << std::endl;
    }

    CoUninitialize(); // Clean up COM
    return 0;
}

Useful links:

Benchmarks

Benchmark	Time	CPU	Iterations
BenchmarkFixture_call_aot/call_aot	4.04 ns	3.77 ns	186666667
BenchmarkFixture_call_cppcli/call_cppcli	7.81 ns	7.85 ns	89600000
BenchmarkFixture_call_framework_export/call_framework_export	5.11 ns	5.02 ns	112000000
BenchmarkFixture_call_standard_framework_export/call_standard_framework_export	6.29 ns	6.14 ns	112000000
call_com	141065 ns	107422 ns	6400
BenchmarkFixture_call_old_runtime/call_old_runtime	1257 ns	1245 ns	640000
BenchmarkFixture_call_new_runtime/call_new_runtime	146 ns	140 ns	5600000

The benchmarks demonstrate the performance of various function call mechanisms, highlighting differences in execution time and efficiency across different scenarios. Here's a summary:

Fastest Calls:
- BenchmarkFixture_call_aot/call_aot: Achieved the best performance with a runtime of 4.04 ns, showcasing the efficiency of Ahead-of-Time (AOT) compilation.
- BenchmarkFixture_call_framework_export/call_framework_export: Delivered a runtime of 5.11 ns, slightly slower but still highly efficient.
Moderately Fast Calls:
- BenchmarkFixture_call_standard_framework_export/call_standard_framework_export: Executed in 6.29 ns, showing comparable performance to call_framework_export.
- BenchmarkFixture_call_cppcli/call_cppcli: With a runtime of 7.81 ns, the C++/CLI call is efficient but slightly slower than AOT and framework export methods.
Slower Calls:
- BenchmarkFixture_call_new_runtime/call_new_runtime: Performed in 146 ns, indicating that the newer runtime introduces additional overhead compared to AOT.
- BenchmarkFixture_call_old_runtime/call_old_runtime: Executed in 1257 ns, revealing significant overhead in older runtime environments.
Slowest Call:
- call_com: At 141065 ns, COM-based calls are the least efficient in this comparison, reflecting the additional overhead associated with the COM infrastructure.

Key Insights:

AOT and framework exports are the most efficient calling mechanisms, achieving nanosecond-level performance.
COM calls are significantly slower, likely due to their inherent complexity and inter-process communication overhead.
The new runtime demonstrates improved performance over the old runtime but still lags behind AOT in raw speed.

These benchmarks highlight the importance of choosing the right execution model based on performance requirements and
use cases.

Conclusion

If the obtained results are summarized in a table, the following pros and cons can be identified:

Name	Description	Target Runtime	Pros	Cons	OS
AOT	Using ahead of time compilation into native .dll	.NET 8, .NET 9	Modern, Simple implementation, Compatible with Unix/Windows	Imposes restrictions, Not supported by older Runtimes	Windows, Unix
COM	Using COM Interop	.NET Framework, .NET Core, .NET Standard	Standardized implementation, Documentation	Requires the client to support interaction via COM	Windows
C++/CLI	Using C++/CLI like Wrapper .dll	.NET Framework, .NET Core, .NET Standard	Easy to implement, Documentation	Requires C++, Only for Windows, Additional .dll layer	Windows
.export instruction	Using .export instruction	.NET Framework, .NET Standard	Fun way, Supported out of the box	Difficult to implement, Only for Windows, need GAC	Windows
New Runtime	Using pure .NET (New) Runtime	.NET Standard, .NET Core	No use of additional languages - only C++ and C#, Compatible with Unix/Windows	Complex implementation	Windows, Unix
Old Runtime	Using pure .NET (Old) Runtime	.NET Framework, .NET Core, .NET Standard	No use of additional languages - only C++ and C#	Complex implementation	Windows, Unix

In my case, while developing a plugin for Total Commander, I chose the AOT (Ahead-of-Time Compilation) method. This choice turned out to be optimal since my library had no external dependencies, which significantly simplified the integration process and improved performance.

This method allowed me to compile the code into native machine code ahead of time, which not only enhanced execution speed but also ensured faster application startup. By using AOT, I was able to significantly reduce overhead and optimize resource consumption. Thus, AOT became the perfect solution for my task.

If you're interested in a detailed implementation example, you can check out the results of my project here.

The choice of the right integration method always depends on the specific requirements and conditions of the project. It is important to evaluate all possible options and their limitations to find the most effective and reliable solution. I hope my advice will help you tackle your tasks.

Good luck with your projects!

DEV Community: Maksim Zimin

Bending .NET: How to Stack-Allocate Reference Types in C#

About

Theory

General Discussions

Links

Links

A few more fun tricks.

Inheritance

The entire array is on the stack

Verification & Benchmarking

Safe

Unsafe

Conclusion

Mocking gRPC Clients in C#: Fake It Till You Make It

About problem

Options for Mocking gRPC Clients

Let's prepare a sample client

UnaryCall

ClientSideStreaming

ServiceSideStreaming

DuplexStreaming

Conclusion

Description

Using

Main advantages

Useful links

Conclusion

C++ Calls C#: A Tale of Friendship Across Runtimes

A little backstory:

С++ and Csharp

Test program for .dll validation

Conclusion

Test program for `.dll` validation