Introduction

HostFxrSharp is a safe, idiomatic, Native-AOT-compatible managed wrapper over the native .NET hosting components — nethost and hostfxr. It lets you locate the hosting library, start the .NET runtime, and run or load managed code entirely from clean C#, on Windows, Linux, and macOS.

The native hosting APIs are a low-level C surface: manual buffer protocols, char_t strings whose encoding depends on the platform, opaque handles with strict lifetimes, and integer status codes. HostFxrSharp hides all of that behind a small, strongly-typed API — you call methods, receive strings and objects, and failures arrive as structured exceptions.

Why HostFxrSharp

• Native-AOT friendly. Every native access goes through source-generated P/Invokes and unmanaged function pointers. The only managed-to-native callback — the diagnostic error writer — uses a static [UnmanagedCallersOnly] trampoline, so the entire surface is Native-AOT compatible.
• Cross-platform. One API for Windows, Linux, and macOS. Native strings are marshalled per platform, so you never deal with char_t encoding yourself. See Cross-platform.
• Safe and idiomatic. Native status codes map to structured exceptions, and native handles are wrapped in SafeHandle-based lifetimes so a runtime is never leaked.

Features

• Locate and load hostfxr through nethost, or from an explicit path with no nethost present — see Locating hostfxr.
• Initialize host contexts for a command line (app.dll …) or a .runtimeconfig.json component.
• Run managed applications by starting the .NET runtime and returning the app's exit code.
• Load assemblies and resolve native function pointers to managed static methods.
• Read and write runtime properties before the runtime starts.
• Install a process-wide diagnostic error writer to capture host messages.

Installation

Add the package to your project:

dotnet add package HostFxrSharp

HostFxrSharp targets .NET 10 and supports both JIT and Native-AOT publishing.

Quick example

Initialize the process runtime for a managed application and run it:

using HostFxrSharp;

// Locate + load hostfxr, then initialize the process runtime for a managed app.
using var app = HostFxr.InitializeForCommandLine(["MyApp.dll", "--verbose"]);

// Start the .NET runtime and run the application; returns its exit code.
int exitCode = app.RunApp();

The collection expression is a string[] of the app's command-line arguments, exactly as hostfxr expects: the managed entry assembly first (app.dll), followed by its arguments. SDK commands such as dotnet run are not supported.

Two ways to initialize

HostFxr exposes two entry points, mirroring the native hosting API. Both return a HostContext.

Both accept an optional HostContextOptions (HostPath, DotNetRoot, and nested Resolution options) from the HostFxrSharp.Contexts namespace.

Load a component into the runtime

Instead of running a whole application, you can start the runtime from a component's .runtimeconfig.json and resolve a native function pointer to one of its managed static methods.

using HostFxrSharp;
using HostFxrSharp.Contexts;
using HostFxrSharp.Loading;

using HostContext component = HostFxr.InitializeForRuntimeConfig("MyComponent.runtimeconfig.json");

AssemblyFunctionPointerLoader loader = component.GetAssemblyFunctionPointerLoader();

nint entryPoint = loader.Load(
    assemblyPath: "MyComponent.dll",
    typeName:     "MyComponent.Entry, MyComponent",
    methodName:   "Run");

Native behavior you should know

HostFxrSharp is a thin, faithful wrapper — it does not paper over the fundamental rules of the native hosting components. Keep these in mind.

Next steps