Host Integration

宿主集成

Host Integration

适用版本：4.0.0。

Applies to 4.0.0.

首页 · .NET Host API 参考

本页说明稳定的宿主集成流程：配置 AuroraEngine、选择源码 Resolver、创建隔离的 ScriptDomain、注入状态与全局成员、注册 CLR 类型，并安全管理生命周期。

This page covers the stable host-integration flow: configure AuroraEngine, choose a source resolver, create isolated ScriptDomain instances, inject state and globals, register CLR types, and manage lifecycle safely.

配置引擎与源码 Resolver

从 EngineOptions.Default 派生配置。内置 ScriptSources 工厂覆盖文件、内存和组合来源。

Derive configuration from EngineOptions.Default. Built-in ScriptSources factories cover file-system, memory, and composite sources.

var memory = ScriptSources.Memory("mem://app/")
    .Add("main.as", """
        @module(MAIN);
        export func run() { return 42; }
        """);

var options = EngineOptions.Default.WithCompiler(compiler =>
{
    compiler.SourceResolver = memory;
    compiler.Mode = CompilationMode.Dynamic;
});

var engine = new AuroraEngine(options);
await engine.BuildAsync("main.as");

BuildAsync() 编译 Resolver 可见的全部来源；BuildAsync("main.as") 从入口和其 import / include 依赖构建。自定义 Resolver 必须保留导入者上下文，保证相对路径按导入文件解析。

BuildAsync() compiles every resolver-visible source; BuildAsync("main.as") builds from the entry point and its import / include dependencies. A custom resolver must preserve importer context so relative paths resolve from the importing file.

创建 Domain、状态和全局成员

每个 ScriptDomain 隔离全局对象和模块实例。将用户状态定义为 ScriptObject，脚本通过 $state 读取它。

Each ScriptDomain isolates its global object and module instances. Define user state as a ScriptObject; scripts read it through $state.

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

public sealed class UserState : ScriptObject
{
    public UserState()
    {
        Define("Name", StringValue.Of("Aurora"));
        Define("Count", NumberValue.Of(3));
    }
}

using var domain = engine.CreateDomain(userState: new UserState());

@module(MAIN);

export func stateName() {
    return $state.Name;
}

使用 CreateDomain 的配置回调注入宿主全局函数和值。需要编辑器诊断时，用单独的 @global(); 文件声明这些名称；声明不生成运行时代码。

Use CreateDomain's configuration callback to inject host functions and values. When editor diagnostics are desired, declare the names in a separate @global(); file; declarations do not generate runtime code.

using var domain = engine.CreateDomain(global =>
{
    global.Define("HOST_ADD", (Func<int, int, int>)((left, right) => left + right));
    global.Define("HOST_NAME", "Aurora");
});

@global();

declare func HOST_ADD(left, right);
declare const HOST_NAME;

CLR 互操作

只注册明确允许给脚本使用的 CLR 类型，并用别名缩小脚本契约。不要向不可信脚本暴露可访问文件、网络或进程的类型。

Register only CLR types explicitly intended for scripts, and use aliases to keep the script contract narrow. Do not expose file-, network-, or process-capable types to untrusted scripts.

engine.RegisterType<HostCalculator>("Calculator", TypeAccess.All);

@module(MAIN);

export func add() {
    var calculator = new Calculator(5);
    return calculator.Add(37);
}

生命周期与并发

不再使用 Domain 时调用 Dispose()；长期运行的宿主应避免把一个可变 Domain 当作不受同步保护的共享状态。热更新、全局状态和宿主对象的线程安全由宿主契约决定。

Call Dispose() when a domain is no longer needed. A long-running host should not treat one mutable domain as unsynchronized shared state. Thread safety of hot patching, globals, and host objects is part of the host contract.

using (var domain = engine.CreateDomain())
{
    var result = domain.Execute("MAIN", "run");
    Console.WriteLine(result);
}

相关页面：AuroraEngine、ScriptDomain、ScriptSources、CLR 互操作、安全边界。

Related pages: AuroraEngine, ScriptDomain, ScriptSources, CLR interop, and security boundaries.