Native AOT

HostFxrSharp is designed from the ground up to survive Native AOT publishing (PublishAot). Every native access goes through source-generated P/Invokes and unmanaged function pointers, the single managed-to-native callback is a static [UnmanagedCallersOnly] trampoline, and no part of the library relies on runtime reflection or dynamic code generation. You can compile a launcher that locates hostfxr, starts the .NET runtime, and runs or loads managed code — and ship it as a fully ahead-of-time-compiled native executable.

This page explains why the wrapper is AOT-safe, how to consume it from an AOT-published app, and how to call managed methods across the boundary without any delegate marshalling.

Why HostFxrSharp is Native-AOT compatible

Native AOT forbids the runtime features that most interop layers lean on: no runtime-generated marshalling stubs for [DllImport], no Marshal.GetDelegateForFunctionPointer / Marshal.GetFunctionPointerForDelegate round-trips, and no reflection over types trimmed away at publish time. HostFxrSharp avoids all of them by construction.

Source-generated P/Invokes

Every call into nethost and hostfxr is declared with [LibraryImport]. The interop source generator emits the marshalling code at compile time, so there is no runtime IL generation and no trimming warning. Classic [DllImport] would require the runtime to build a marshalling stub on first call — exactly what Native AOT cannot do.

Unmanaged function pointers, no delegate marshalling

The runtime helpers returned by a host context are consumed as raw C# function pointers rather than managed delegates. For example, the assembly loader in HostFxrSharp.Loading wraps the native load_assembly_and_get_function_pointer helper directly:

// Internal shape of AssemblyFunctionPointerLoader — no managed delegate is ever created.
private readonly delegate* unmanaged[Stdcall]<byte*, byte*, byte*, byte*, void*, void**, int> _fn;

Because the pointer is invoked through delegate* unmanaged[...] syntax, there is no Marshal-based delegate wrapping in either direction. The function pointers you receive from Load are likewise plain nint values you invoke through unmanaged function-pointer casts (see below).

The single managed-to-native callback is a static trampoline

The one place code has to flow from native into managed is the diagnostic error writer installed by HostFxr.SetErrorWriter. Instead of handing hostfxr a marshalled delegate, the library installs the address of a static method annotated with [UnmanagedCallersOnly]:

// How HostFxrSharp registers the callback (simplified from the library source).
[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
private static unsafe void ErrorWriterTrampoline(byte* message)
{
    // Reads the native char_t* message and forwards it to the user's HostErrorWriter.
    // Exceptions are swallowed here: crossing native -> managed with an exception is undefined.
}

// Installed as a plain function-pointer address — no delegate, no GC handle:
// (delegate* unmanaged[Cdecl]<byte*, void>)&ErrorWriterTrampoline

A [UnmanagedCallersOnly] method has a fixed native address the compiler can take with &, so it needs no marshalled delegate and no keep-alive GCHandle. This is the canonical AOT-safe callback pattern, and it is the only managed-to-native callback in the whole library.

No reflection

HostFxrSharp resolves nothing by reflection. Type and method names for the assemblies you load are passed through to the hosted runtime as strings — they name members in the JIT-loaded guest, never in your AOT host — so the trimmer has nothing to preserve on the host side.

Consuming HostFxrSharp from an AOT-published app

Building an AOT launcher is three steps: enable AOT, publish per-RID, and write the launcher exactly as you would for a JIT build.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <PublishAot>true</PublishAot>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="HostFxrSharp" Version="1.0.0" />
  </ItemGroup>

</Project>

dotnet publish -c Release -r win-x64
dotnet publish -c Release -r linux-x64
dotnet publish -c Release -r osx-arm64

using HostFxrSharp;

// Locate + load hostfxr (via nethost), initialize the process runtime for a managed app,
// then start the runtime and run it. Returns the app's exit code.
using HostFxrSharp.Contexts.HostContext app =
    HostFxr.InitializeForCommandLine(["MyApp.dll", "--verbose"]);

int exitCode = app.RunApp();
return exitCode;

Calling managed methods without marshalling

When you load an assembly and ask for a function pointer to one of its static methods, HostFxrSharp lets you describe the target method's signature through MethodSignature (in HostFxrSharp.Loading). Three shapes are available:

MethodSignature.UnmanagedCallersOnly is the marshalling-free path. The hosted runtime returns a direct pointer to the target method instead of generating a delegate marshalling stub to wrap it, and you invoke it through a plain unmanaged function-pointer cast. This keeps the boundary blittable and stub-free on both sides.

FromDelegateType and the default component entry point, by contrast, cause the hosted runtime to synthesize a marshalling delegate. That is legal (the guest is JIT-based), but it means the parameters flow through the runtime's marshaller. Prefer MethodSignature.UnmanagedCallersOnly whenever you control the target method.

using System.Runtime.InteropServices;

namespace MyComponent;

public static class Exports
{
    [UnmanagedCallersOnly]
    public static int Add(int a, int b) => a + b;
}

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

// Initialize a framework-dependent component from its .runtimeconfig.json.
using HostContext host = HostFxr.InitializeForRuntimeConfig(
    @"C:\components\MyComponent\MyComponent.runtimeconfig.json");

// Acquire the loader from the host context (see "Loading assemblies").
AssemblyFunctionPointerLoader loader = host.GetFunctionPointerLoader();

// Resolve a native pointer to the [UnmanagedCallersOnly] method — no delegate marshalling.
nint ptr = loader.Load(
    assemblyPath: @"C:\components\MyComponent\MyComponent.dll",
    typeName: "MyComponent.Exports, MyComponent",
    methodName: "Add",
    signature: MethodSignature.UnmanagedCallersOnly);

unsafe
{
    var add = (delegate* unmanaged<int, int, int>)ptr;
    int result = add(2, 3); // 5
    Console.WriteLine(result);
}

The error writer: the one callback in practice

HostFxr.SetErrorWriter is the user-facing side of the [UnmanagedCallersOnly] trampoline. You pass an ordinary managed HostErrorWriter delegate; the library routes native diagnostic messages to it through the static trampoline, so it works unchanged under AOT:

using HostFxrSharp;

// Install a process-wide diagnostic writer; dispose the registration to remove it.
using IDisposable registration = HostFxr.SetErrorWriter(
    message => Console.Error.WriteLine($"[hostfxr] {message}"));

using var app = HostFxr.InitializeForCommandLine(["MyApp.dll"]);
int exitCode = app.RunApp();

The native error writer is process-global, so the most recent registration wins, and disposing the returned registration detaches your callback. See Error handling for how failures surface as structured exceptions.

Caveats

A few facts about the native hosting layer are unchanged by AOT — HostFxrSharp is a faithful, thin wrapper and does not paper over them.

Next steps