Host Native Exports

宿主原生导出

用源生成器把 C# Core 方法暴露为脚本全局对象，并在类型已证明时由编译器直调。

适用于 4.0.0。

首页 · 宿主集成 · .NET 宿主 API 参考

Important

这与脚本 native func 以及 BuiltInModules（fs / http）不是同一概念。

• 宿主原生导出：C# 上的 [AuroraBuiltinGlobal] / [AuroraExport]，生成 Datum 适配器与编译器目录。
• native func：脚本模块函数的显式 ABI。
• 原生模块：宿主启用的 fs、http 等包。

本页目录

• 何时使用
• 声明全局对象
• Core 签名
• 直调与适配器
• 诊断
• 引擎内置
• 后续步骤

何时使用

当宿主全局应当是带类型化 Core 方法的 ScriptObject，而不是 BondingFunction 或普通 CLR 委托时使用本路径。

运行时可见性仍来自 ScriptGlobal.Define。生成器只负责适配器、构造函数和程序集目录特性。

声明全局对象

在声明 [AuroraBuiltinGlobal] 的项目中把 AuroraScript.Hosting.Generators 作为 analyzer 引用。类型必须是命名空间内的 public sealed partial 顶层类，并派生自 ScriptObject。

using AuroraScript.Hosting;
using AuroraScript.Runtime;
using AuroraScript.Runtime.Types;

[AuroraBuiltinGlobal("Stats")]
public sealed partial class StatsSupport : ScriptObject
{
    [AuroraExport("mean", MatchFailure.ReturnNaN)]
    public static double MeanCore(double a, double b) => (a + b) / 2D;

    [AuroraExport("echo", MatchFailure.Throw)]
    public static ScriptDatum EchoCore(ScriptDatum value) => value;
}

在 domain 或引擎全局上注册实例：

global.Define("Stats", new StatsSupport(), writeable: false, enumerable: false);

若自行编写实例构造函数，必须调用 RegisterAuroraExports()；否则生成器会发出构造函数。不要手写 [AuroraGeneratedExport] / [AuroraGeneratedConstant]。

Core 签名

支持的参数与返回类型：

• double、int、bool、string
• ScriptDatum
• 任意 ScriptObject 子类（ScriptArray、packed array、Path、Proxy、Regex、Date、HashMap、Error、ClosureFunction、包装器）

可选隐式前缀，且只能按此顺序：

1. ScriptContext ctx — 不是脚本实参。
2. ScriptObject thisObject — 接收者；参数名必须为 thisObject。

允许尾部 C# 默认值。params double[] 与 params ScriptDatum[] 仅用于 Datum 适配器。

public static readonly double 字段可标 [AuroraExport("PI")]，成为脚本常量。未遮蔽读取发射 ldsfld，而不是装箱的 ldc.r8。

[AuroraParam(MatchLevel.Exact)] 或 Strict 收紧适配器强制转换。MatchFailure 控制不匹配行为：Default 对数值返回推断为 NaN，否则为 null；Throw 抛出 AuroraRuntimeException。

对象返回值通过 ScriptDatum.WriteObject / FromObject 保留原来的 ValueKind，因此 Array、Date、Error 不会塌成普通 object。

不支持：async、Span/ref/out/in、泛型方法、嵌套类型、record、空导出名、params 与 [AuroraParam] 同时使用、把 ctx/thisObject 放在脚本参数之后。

直调与适配器

参数类型已证明时，编译器直接调用 Core 方法。条件：

• 未遮蔽的全局接收者（Math.abs(x)，而不是 var m = Math; m.abs(x)）。
• 无 params 的 public Core 方法。
• 实参类型可证明兼容，含尾部可选默认值。
• 目录元数据存在。引擎程序集始终扫描。额外宿主程序集必须列入 EngineOptions.HostExportAssemblies：

var options = EngineOptions.Default with
{
    HostExportAssemblies = new[] { typeof(StatsSupport).Assembly }
};

params 导出、spread 实参、被遮蔽的全局以及未证明的实参类型走生成的 Datum 适配器。

诊断

代码	级别	含义
AURORAEXP001	Error	无效的 builtin global 声明
AURORAEXP002	Error	不支持的导出成员或签名
AURORAEXP003	Error	重复的脚本成员名
AURORAEXP004	Warning	显式实例构造函数必须调用 RegisterAuroraExports()

引擎内置

引擎已用本路径定义 Math、TDoc 和实验性 Stats。JSON、console、HotPatch 以及原型方法仍为 Bonding 实现。

Math.max / Math.min 使用 params double[]，因此始终走适配器；Math.abs 与 Math.PI 在未遮蔽且类型已证明时可直调或 ldsfld。

后续步骤

• 宿主集成 — 引擎、resolver、domain 与 CLR 互操作。
• AuroraBuiltinGlobalAttribute · AuroraExportAttribute
• Native 函数 — 脚本侧 native func。
• MCP 资源：aurora://docs/host-integration、aurora://schema/host-api。