API reference

using HostFxrSharp;
using HostFxrSharp.Resolution;

// Locate hostfxr through the native nethost component.
string hostFxrPath = NetHost.GetHostFxrPath();
Console.WriteLine(hostFxrPath);

// Or steer discovery at a specific .NET installation, without throwing.
var options = new HostFxrResolutionOptions { DotNetRoot = @"C:\Program Files\dotnet" };

if (NetHost.TryGetHostFxrPath(out string? path, options))
    Console.WriteLine($"hostfxr: {path}");

// Receives diagnostic messages emitted by the hosting components.
public delegate void HostErrorWriter(string message);

using HostFxrSharp;

// Optional: control discovery explicitly. Initialize* would otherwise load hostfxr on demand.
HostFxr.EnsureLoaded();
Console.WriteLine(HostFxr.LoadedHostFxrPath);

// Capture host diagnostics for the lifetime of the registration.
using IDisposable diagnostics = HostFxr.SetErrorWriter(message => Console.Error.WriteLine(message));

// Run a managed application and return its exit code.
using var app = HostFxr.InitializeForCommandLine(["MyApp.dll", "--verbose"]);
int exitCode = app.RunApp();

using HostFxrSharp;
using HostFxrSharp.Contexts;

// A .runtimeconfig.json component. May attach as a secondary context if a runtime is already running.
using var context = HostFxr.InitializeForRuntimeConfig("MyComponent.runtimeconfig.json");

if (context.Kind is HostContextKind.Secondary && context.RuntimePropertiesDiffer)
{
    foreach (RuntimePropertyConflict conflict in context.GetConflictingRuntimeProperties())
        Console.WriteLine($"{conflict.Name}: requested '{conflict.RequestedValue}', active '{conflict.ActiveValue}'");
}

// Obtaining any loader starts the runtime; after this, properties are read-only.
var loader = context.GetAssemblyFunctionPointerLoader();

using HostFxrSharp;

using var context = HostFxr.InitializeForRuntimeConfig("MyComponent.runtimeconfig.json");
var properties = context.Properties;

// Read.
if (properties.TryGetValue("System.GC.Server", out string? gcMode))
    Console.WriteLine($"Server GC: {gcMode}");

// Write — only before the runtime starts, and only on the first context.
if (properties.CanModify)
    properties.Set("System.GC.Server", "true");

foreach (KeyValuePair<string, string> kv in properties.GetAll())
    Console.WriteLine($"{kv.Key} = {kv.Value}");

using HostFxrSharp;
using HostFxrSharp.Contexts;
using HostFxrSharp.Resolution;

var options = new HostContextOptions
{
    DotNetRoot = @"C:\Program Files\dotnet",
    Resolution = new HostFxrResolutionOptions { DotNetRoot = @"C:\Program Files\dotnet" }
};

using var context = HostFxr.InitializeForRuntimeConfig("MyComponent.runtimeconfig.json", options);

using HostFxrSharp;
using HostFxrSharp.Loading;

using var context = HostFxr.InitializeForRuntimeConfig("MyComponent.runtimeconfig.json");
var loader = context.GetAssemblyFunctionPointerLoader();

// Resolve a [UnmanagedCallersOnly] static int Add(int, int).
nint fn = loader.Load(
    assemblyPath: "MyComponent.dll",
    typeName: "MyComponent.Exports, MyComponent",
    methodName: "Add",
    signature: MethodSignature.UnmanagedCallersOnly);

unsafe
{
    var add = (delegate* unmanaged<int, int, int>)fn;
    int sum = add(2, 3); // 5
}

using HostFxrSharp.Loading;

var resolver = context.GetFunctionPointerResolver();

nint fn = resolver.Resolve(
    typeName: "MyComponent.Exports, MyComponent",
    methodName: "Add",
    signature: MethodSignature.UnmanagedCallersOnly);

using HostFxrSharp.Loading;

var loader = context.GetAssemblyLoader();
loader.Load("Plugin.dll");

using HostFxrSharp.Loading;

var loader = context.GetAssemblyBytesLoader();
byte[] assemblyBytes = File.ReadAllBytes("Plugin.dll");
loader.Load(assemblyBytes);

using HostFxrSharp.Loading;

MethodSignature entryPoint = MethodSignature.Default;              // int (nint arg, int argSizeInBytes)
MethodSignature unmanaged  = MethodSignature.UnmanagedCallersOnly; // [UnmanagedCallersOnly] target
MethodSignature typed      = MethodSignature.FromDelegateType("MyComponent.ComputeDelegate, MyComponent");

using HostFxrSharp;

HostStatusCode code = context.InitializationStatus;

if (code.IsSuccess() && code.IsSecondaryContext())
    Console.WriteLine("Attached to an already-running runtime.");

Exception
└─ HostingException (abstract)          — StatusCode { get; }
   ├─ HostFxrNotFoundException          — hostfxr could not be located
   ├─ HostFxrResolutionException        — nethost failed to resolve hostfxr (other reason)
   └─ HostingApiException               — a general native hosting failure
      ├─ HostInvalidStateException      — invalid host state
      ├─ IncompatibleHostPolicyException — new hostfxr API vs. older hostpolicy
      ├─ RuntimeAlreadyLoadedException  — a runtime is already loaded in this process
      ├─ RuntimePropertyNotFoundException — a requested runtime property is missing
      └─ UnsupportedHostingScenarioException — the scenario is unsupported for the context

using HostFxrSharp;
using HostFxrSharp.Exceptions;

try
{
    using var app = HostFxr.InitializeForCommandLine(["MyApp.dll"]);
    return app.RunApp();
}
catch (RuntimeAlreadyLoadedException ex)
{
    // Only one runtime can be loaded per process.
    Console.Error.WriteLine($"{ex.Message} (status: {ex.StatusCode})");
    return 1;
}
catch (HostingException ex)
{
    // Base type for every failure this library raises.
    Console.Error.WriteLine(ex.Message);
    return 1;
}