Locating hostfxr

Before HostFxrSharp can start a runtime, it must find and load the native hostfxr library on the current machine. This is the "locate hosting components" step, and it is the foundation every other operation builds on. This page covers the two things you can do here:

• Locate hostfxr — ask the native nethost component for its full path, without loading it.
• Load hostfxr — bring the library into the process so host contexts can be initialized.

The two entry points for locating live on NetHost, and the two entry points for loading live on HostFxr. Both types are in the HostFxrSharp namespace.

The locate-then-load model

The native hosting flow has two distinct stages, and HostFxrSharp keeps them separate:

You can stop after the locate stage (for example, to log or validate the path), or go straight to loading. Loading always implies a successful locate — except with HostFxr.LoadFrom, which skips nethost entirely and takes a path you already have.

For the bigger picture of how nethost, hostfxr, and host contexts fit together, see How hosting works.

Locating with NetHost

NetHost wraps the native get_hostfxr_path function. The native API uses a size-then-fill buffer protocol (it tells you how big a buffer to allocate, then fills it); HostFxrSharp handles that entire dance internally — a stack buffer first, then pooled growth if the path is unusually long — and hands you back an ordinary string.

NetHost.GetHostFxrPath

Returns the absolute path to hostfxr, or throws if it cannot be found.

using HostFxrSharp;

string hostFxrPath = NetHost.GetHostFxrPath();
Console.WriteLine($"hostfxr is located at: {hostFxrPath}");

Signature and failure modes:

Both exceptions live in HostFxrSharp.Exceptions and derive from HostingException. See Error handling for the full hierarchy.

NetHost.TryGetHostFxrPath

The non-throwing counterpart. It returns false (instead of throwing) when hostfxr cannot be located, which is convenient for probing whether a usable .NET install is present:

using HostFxrSharp;

if (NetHost.TryGetHostFxrPath(out string? hostFxrPath))
{
    Console.WriteLine($"Found hostfxr: {hostFxrPath}");
}
else
{
    Console.WriteLine("No compatible .NET install was found on this machine.");
}

The out parameter is annotated [NotNullWhen(true)], so the compiler knows hostFxrPath is non-null inside the true branch.

Resolution options

Both NetHost methods (and, transitively, HostFxr.EnsureLoaded) accept an optional HostFxrResolutionOptions. It lives in the HostFxrSharp.Resolution namespace and has two init-only properties:

DotNetRoot takes precedence

If both properties are set, DotNetRoot wins and AssemblyPath is ignored — this mirrors the native nethost semantics exactly. Keep this in mind: setting AssemblyPath alongside DotNetRoot has no effect.

using HostFxrSharp;
using HostFxrSharp.Resolution;

var options = new HostFxrResolutionOptions
{
    DotNetRoot   = @"C:\Program Files\dotnet",
    AssemblyPath = @"C:\apps\MyApp\MyApp.dll", // ignored — DotNetRoot takes precedence
};

// Resolves against C:\Program Files\dotnet, as if launching `dotnet MyApp.dll`.
string hostFxrPath = NetHost.GetHostFxrPath(options);

To locate hostfxr relative to a specific application binary instead, set only AssemblyPath:

using HostFxrSharp;
using HostFxrSharp.Resolution;

var options = new HostFxrResolutionOptions
{
    AssemblyPath = @"C:\apps\MyApp\MyApp.dll",
};

// Searches next to MyApp.dll first (a self-contained/app-local copy),
// then falls back to a globally registered .NET install.
string hostFxrPath = NetHost.GetHostFxrPath(options);

Resolution order

Given the options, nethost resolves hostfxr in this order:

1. DotNetRoot is set → locate hostfxr under that .NET installation root (as if running dotnet app.dll). AssemblyPath is ignored.
2. Only AssemblyPath is set → locate hostfxr as if AssemblyPath were an apphost: app-local next to the assembly first, then falling back to a machine-wide install.
3. Neither is set (the default, options is null) → locate hostfxr via the DOTNET_ROOT environment variable, or a globally registered install location.

Passing null options — or no options at all — selects case 3, which is the ordinary "use whatever .NET is installed on this machine" behavior most applications want.

Platform-specific library names

The file that nethost resolves has a platform-specific name, and so does nethost itself. You do not normally type these names — NetHost returns the fully qualified path for you — but they matter when you build a path by hand for HostFxr.LoadFrom:

Loading hostfxr

Locating a path is not enough to do anything useful — the library has to be loaded into the process. HostFxr provides two ways to do that, and both are idempotent and process-wide: because a process can host only one runtime, a process loads exactly one hostfxr, and only the first successful load call takes effect. Later calls return immediately without reloading.

You can read the currently loaded path at any time:

using HostFxrSharp;

// null until hostfxr has been loaded; the absolute path afterwards.
string? loaded = HostFxr.LoadedHostFxrPath;

HostFxr.EnsureLoaded

Locates hostfxr via nethost and loads it — the locate-and-load path. This is what the Initialize* methods call for you, so calling it directly is only necessary when you want to load hostfxr up front or pass resolution options.

using HostFxrSharp;

HostFxr.EnsureLoaded();
Console.WriteLine($"Loaded hostfxr from: {HostFxr.LoadedHostFxrPath}");

To steer discovery, pass HostFxrResolutionOptions. Because only the first call actually loads, only the first call's options take effect — supply them the first time hostfxr is loaded:

using HostFxrSharp;
using HostFxrSharp.Resolution;

HostFxr.EnsureLoaded(new HostFxrResolutionOptions
{
    DotNetRoot = @"C:\Program Files\dotnet",
});

HostFxr.LoadFrom

Loads hostfxr from an explicit path, bypassing nethost discovery entirely. Use this when you already know where hostfxr lives — an app-local, self-contained copy shipped next to your application, or a library you found in the machine .NET install. Because it never touches nethost, no nethost library needs to be present on the machine.

using HostFxrSharp;

// A self-contained deployment ships hostfxr alongside the app.
string hostFxrPath = Path.Combine(AppContext.BaseDirectory, "hostfxr.dll");

HostFxr.LoadFrom(hostFxrPath);
Console.WriteLine($"Loaded hostfxr from: {HostFxr.LoadedHostFxrPath}");

A cross-platform variant picks the correct native file name for the current OS:

using System.Runtime.InteropServices;
using HostFxrSharp;

static string HostFxrFileName()
{
    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        return "hostfxr.dll";
    if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        return "libhostfxr.dylib";
    return "libhostfxr.so"; // Linux and other Unix
}

string hostFxrPath = Path.Combine(AppContext.BaseDirectory, HostFxrFileName());
HostFxr.LoadFrom(hostFxrPath);

EnsureLoaded vs. LoadFrom

Error handling

All failures surface as structured exceptions from HostFxrSharp.Exceptions, all deriving from HostingException. Catch the specific type you care about:

using HostFxrSharp;
using HostFxrSharp.Exceptions;

try
{
    HostFxr.EnsureLoaded();
}
catch (HostFxrNotFoundException ex)
{
    // nethost could not locate hostfxr — likely no compatible .NET install.
    Console.Error.WriteLine($".NET runtime not found: {ex.Message}");
}
catch (HostFxrResolutionException ex)
{
    // Located but could not be loaded, or resolution failed for another reason.
    Console.Error.WriteLine($"Failed to load hostfxr: {ex.Message}");
}

If you prefer to branch on presence without exceptions, use NetHost.TryGetHostFxrPath first, then load. See Error handling for the complete exception model.

Native behavior to keep in mind

HostFxrSharp is a thin, faithful wrapper — it does not hide the fundamental rules of the native hosting components:

Putting it together

A complete example that probes for hostfxr, loads it, then hands off to a host context:

using HostFxrSharp;

if (!NetHost.TryGetHostFxrPath(out string? path))
{
    Console.Error.WriteLine("No compatible .NET runtime found. Install .NET and retry.");
    return;
}

Console.WriteLine($"Discovered hostfxr at: {path}");

using HostFxrSharp;
using HostFxrSharp.Exceptions;
using HostFxrSharp.Resolution;

try
{
    HostFxr.EnsureLoaded(new HostFxrResolutionOptions
    {
        // Omit for the default machine install, or pin an explicit root:
        // DotNetRoot = @"C:\Program Files\dotnet",
    });
}
catch (HostingException ex)
{
    Console.Error.WriteLine($"Could not load hostfxr: {ex.Message}");
    return;
}

Console.WriteLine($"Loaded hostfxr: {HostFxr.LoadedHostFxrPath}");

using HostFxrSharp;

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

Next steps