Like all managed code, .NET applications are executed by a host. The host is responsible for starting the runtime (including components like the JIT and garbage collector) and invoking managed entry points.

Hosting the .NET runtime is an advanced scenario and, in most cases, .NET developers don't need to worry about hosting because .NET build processes provide a default host to run .NET applications. In some specialized circumstances, though, it can be useful to explicitly host the .NET runtime, either as a means of invoking managed code in a native process or to gain more control over how the runtime works.

This article gives an overview of the steps necessary to start the .NET runtime from native code and execute managed code in it.

Prerequisites

Because hosts are native applications, this tutorial covers constructing a C++ application to host .NET. You need a C++ development environment (such as that provided byVisual Studio).

You also need to build a .NET component to test the host with, so you should install thelatests .NET SDK. It includes the necessary headers and libraries to link with.

Hosting APIs

Hosting the .NET runtime is done with thenethost andhostfxr libraries' APIs. These entry points handle the complexity of finding and setting up the runtime for initialization and allow both launching a managed application and calling into a static managed method.

Create a host usingnethost.h andhostfxr.h

Asample host demonstrating the steps outlined in the tutorial below is available in the dotnet/samples GitHub repository. Comments in the sample clearly associate the numbered steps from this tutorial with where they're performed in the sample. For download instructions, seeSamples and Tutorials.

Keep in mind that the sample host is meant to be used for learning purposes, so it is light on error checking and designed to emphasize readability over efficiency.

The following steps detail how to use thenethost andhostfxr libraries to start the .NET runtime in a native application and call into a managed static method. Thesample uses thenethost headers and library and thecoreclr_delegates.h andhostfxr.h headers installed with the .NET SDK.

Step 1 - Loadhostfxr and get exported hosting functions

Thenethost library provides theget_hostfxr_path function for locating thehostfxr library. Thehostfxr library exposes functions for hosting the .NET runtime. The full list of functions can be found inhostfxr.h and thenative hosting design document. The sample and this tutorial use the following:

• hostfxr_initialize_for_runtime_config: Initializes a host context and prepares for initialization of the .NET runtime using the specified runtime configuration.
• hostfxr_get_runtime_delegate: Gets a delegate for runtime functionality.
• hostfxr_close: Closes a host context.

Thehostfxr library is found usingget_hostfxr_path API fromnethost library. It is then loaded and its exports are retrieved.

// Using the nethost library, discover the location of hostfxr and get exportsbool load_hostfxr(){    // Pre-allocate a large buffer for the path to hostfxr    char_t buffer[MAX_PATH];    size_t buffer_size = sizeof(buffer) / sizeof(char_t);    int rc = get_hostfxr_path(buffer, &buffer_size, nullptr);    if (rc != 0)        return false;    // Load hostfxr and get desired exports    void *lib = load_library(buffer);    init_fptr = (hostfxr_initialize_for_runtime_config_fn)get_export(lib, "hostfxr_initialize_for_runtime_config");    get_delegate_fptr = (hostfxr_get_runtime_delegate_fn)get_export(lib, "hostfxr_get_runtime_delegate");    close_fptr = (hostfxr_close_fn)get_export(lib, "hostfxr_close");    return (init_fptr && get_delegate_fptr && close_fptr);}

The sample uses the following includes:

#include <nethost.h>#include <coreclr_delegates.h>#include <hostfxr.h>

These files can be found at the following locations:

• https://github.com/dotnet/runtime/blob/main/src/native/corehost/nethost/nethost.h
• https://github.com/dotnet/runtime/blob/main/src/native/corehost/coreclr_delegates.h
• https://github.com/dotnet/runtime/blob/main/src/native/corehost/hostfxr.h

Step 2 - Initialize and start the .NET runtime

Thehostfxr_initialize_for_runtime_config andhostfxr_get_runtime_delegate functions initialize and start the .NET runtime using the runtime configuration for the managed component that will be loaded. Thehostfxr_get_runtime_delegate function is used to get a runtime delegate that allows loading a managed assembly and getting a function pointer to a static method in that assembly.

// Load and initialize .NET Core and get desired function pointer for scenarioload_assembly_and_get_function_pointer_fn get_dotnet_load_assembly(const char_t *config_path){    // Load .NET Core    void *load_assembly_and_get_function_pointer = nullptr;    hostfxr_handle cxt = nullptr;    int rc = init_fptr(config_path, nullptr, &cxt);    if (rc != 0 || cxt == nullptr)    {        std::cerr << "Init failed: " << std::hex << std::showbase << rc << std::endl;        close_fptr(cxt);        return nullptr;    }    // Get the load assembly function pointer    rc = get_delegate_fptr(        cxt,        hdt_load_assembly_and_get_function_pointer,        &load_assembly_and_get_function_pointer);    if (rc != 0 || load_assembly_and_get_function_pointer == nullptr)        std::cerr << "Get delegate failed: " << std::hex << std::showbase << rc << std::endl;    close_fptr(cxt);    return (load_assembly_and_get_function_pointer_fn)load_assembly_and_get_function_pointer;}

Step 3 - Load managed assembly and get function pointer to a managed method

The runtime delegate is called to load the managed assembly and get a function pointer to a managed method. The delegate requires the assembly path, type name, and method name as inputs and returns a function pointer that can be used to invoke the managed method.

// Function pointer to managed delegatecomponent_entry_point_fn hello = nullptr;int rc = load_assembly_and_get_function_pointer(    dotnetlib_path.c_str(),    dotnet_type,    dotnet_type_method,    nullptr /*delegate_type_name*/,    nullptr,    (void**)&hello);

By passingnullptr as the delegate type name when calling the runtime delegate, the sample uses a default signature for the managed method:

public delegate int ComponentEntryPoint(IntPtr args, int sizeBytes);

A different signature can be used by specifying the delegate type name when calling the runtime delegate.

Step 4 - Run managed code!

The native host can now call the managed method and pass it the desired parameters.

lib_args args{    STR("from host!"),    i};hello(&args, sizeof(args));

Limitations

Only one runtime can be loaded inside a single process. If thehostfxr_initialize_for_runtime_config API is called when a runtime is already loaded, it will check if the existing runtime is compatible with the specified initialization parameters. If compatible, the existing runtime will be used and if not compatible, the API will return a failure.