Shimakaze.HostFxr 0.0.10

Shimakaze.NetHost

Shimakaze.NetHost 是一组用于 .NET Hosting API 的托管封装库，让你能够用 C# 安全地调用 nethost 与 hostfxr 原生接口，从而在原生代码、插件系统、脚本宿主或 NativeAOT 应用中启动并控制 .NET 运行时。

目录

• 项目概述
• 包结构
• 功能特性
• 目标框架
• 快速开始
• API 概览
• NativeAOT 支持
• 构建与打包
• 参考项目
• 许可证

项目概述

.NET Hosting API 允许原生代码定位、加载并启动 .NET 运行时，常用于：

• 把 .NET 运行时嵌入 C/C++ 原生宿主程序；
• 编写可加载托管程序集的插件宿主；
• 在 NativeAOT 应用中通过 hostfxr 调用托管代码。

.NET 官方文档 给出了 C/C++ 示例，而 Shimakaze.NetHost 将这些原生接口包装成易用的 C# API，并内置了 NativeAOT 静态链接所需的目标文件，省去手工配置 P/Invoke 与 MSBuild 的繁琐步骤。

包结构

功能特性

• 跨平台：自动识别 Windows / Linux / macOS，处理 Unicode（Windows）与 UTF-8（Unix）字符串编码。
• 极广的目标框架支持：从 .NET 10 一直向下兼容到 .NET 2.0 / .NET Standard 1.1。
• NativeAOT 兼容：.NET 8.0+ 目标标记为 IsAotCompatible。
• 自动原生资产解析：NetHost.targets 自动查找 libnethost 静态库与动态库，并在发布 NativeAOT 时静态链接。
• 安全封装：使用 IDisposable、不安全指针仅在内部使用，对外暴露托管字符串与数组。
• 零运行时依赖：封装库本身不依赖任何额外 NuGet 包。

目标框架

由 Directory.Build.props 统一指定：

• .NET 10 / .NET 9 / .NET 8 / .NET 7 / .NET 6 / .NET 5
• .NET Core 3.1 / 3.0 / 2.2 / 2.1 / 2.0 / 1.1 / 1.0
• .NET Framework 4.8.1 到 4.0，以及 3.5 / 2.0
• .NET Standard 2.1 / 2.0 / 1.6 / 1.5 / 1.4 / 1.3 / 1.2 / 1.1

快速开始

1. 安装 NuGet 包

dotnet add package Shimakaze.NetHost
dotnet add package Shimakaze.HostFxr

2. 定位 hostfxr 并加载

using Shimakaze;

// 获取 hostfxr 库路径（nethost 提供）
string hostfxrPath = NetHost.GetHostFxrPath();

// 加载 hostfxr
using var hostfxr = new HostFXR(hostfxrPath);

3. 初始化运行时并加载程序集

// 通过 runtimeconfig.json 初始化运行时
var parameters = new InitializeParameters
{
    HostPath = "MyApp.exe",
    DotnetRoot = @"C:\Program Files\dotnet"
};

hostfxr.InitializeForRuntimeConfig(
    "MyApp.runtimeconfig.json",
    parameters,
    out HostFXRHandle context);

// 加载程序集并获取入口委托
context.LoadAssemblyAndGetFunctionPointer(
    "MyAssembly.dll",
    "MyNamespace.MyClass",
    "MyMethod",
    null,
    out nint delegatePtr);

// 关闭上下文
context.Close();

4. 运行 .NET 应用程序

hostfxr.InitializeForDotnetCommandLine(
    new[] { "dotnet", "MyApp.dll" },
    parameters,
    out HostFXRHandle context);

int exitCode = context.RunApp();
context.Close();

API 概览

NetHost

HostFXR

HostFXRHandle

DelegateType

对应 hostfxr_delegate_type，包括：

• LoadAssemblyAndGetFunctionPointer
• GetFunctionPointer
• LoadAssembly
• LoadAssemblyBytes
• ComActivation
• WinrtActivation
• ComRegister / ComUnregister
• LoadInMemoryAssembly

NativeAOT 支持

Shimakaze.NetHost 随 NuGet 包附带 NetHost.targets，它会自动：

1. 解析当前 Runtime Identifier（RuntimeIdentifier / DefaultAppHostRuntimeIdentifier / NETCoreSdkRuntimeIdentifier）。
2. 从 SDK targeting pack 或 NuGet 全局包目录定位 Microsoft.NETCore.App.Host.<RID>。
3. 将 libnethost.a / libnethost.lib 作为 NativeLibrary 传入 NativeAOT 链接器。
4. 声明 DirectPInvoke 为 nethost，确保 P/Invoke 可被静态解析。
5. 在 Linux / macOS 上附加 -lstdc++ 链接参数。
6. 把动态库 nethost.dll / libnethost.so / libnethost.dylib 复制到输出目录，以便非 AOT 运行时使用。

使用 Shimakaze.NetHost 时，无需手动下载或配置 nethost 原生库。

构建与打包

本项目使用 .NET SDK 10 + GitVersion.MsBuild 6.x 进行版本管理，Central Package Management 已启用。

# 还原
dotnet restore --graph --artifacts-path artifacts

# 构建 Release
dotnet build --graph --artifacts-path artifacts --configuration Release --no-restore

# 打包（包含符号包）
dotnet pack --graph --artifacts-path artifacts --configuration Release --no-restore --no-build --include-symbols

CI/CD 配置位于 .github/workflows/build.yaml：

• 在 master 分支的 push / pull_request 时触发构建；
• 在 v* 标签时发布 GitHub Release 并推送 NuGet 包。

参考项目

• AustinWise/DotNetHostingAndNativeAot。

相关文档

• Write a custom .NET host to control the .NET runtime from your native code
• Native code interop with Native AOT

许可证

本项目采用 MIT License 授权。

Copyright © 2025 frg2089 frg2089@outlook.com