API Host AuroraEngine

AuroraEngine

编译、创建 Domain 和注册 CLR 类型的主入口

Primary entry point for compilation, domains, and CLR registration

.NET Host API 目录

.NET Host API Directory

概述

Overview

AuroraEngine 是一次编译配置的中心。构造后先注册所需 CLR 类型和宿主全局原型，再调用 BuildAsync；随后可以从同一 Engine 创建多个相互隔离的 Domain。

AuroraEngine is the center of one compilation configuration. After construction, register required CLR types and host-global prototypes, then call BuildAsync; multiple isolated domains can subsequently be created from the same engine.

AuroraEngine(EngineOptions options)

Parameters:

• options
  不可为 null 的引擎配置。

  Non-null engine configuration.

Returns

新引擎。

New engine.

异常

空配置会抛出 AuroraException。

A null configuration throws AuroraException.

var engine = new AuroraEngine(EngineOptions.Default);

Global

用途

新 Domain 的全局原型。

Global prototype for new domains.

边界

在创建 Domain 前定义共享值；每个 Domain 仍有自身的全局对象。

Define shared values before creating domains; each domain still receives its own global object.

engine.Global.Define("APP_NAME", "Aurora");

ClrRegistry

用途

管理向脚本公开的 CLR 类型。

Manages CLR types visible to scripts.

engine.ClrRegistry.RegisterType(typeof(DateTime), "HostDate", TypeAccess.Constructor);

RegisterType<T>([alias], [access]) / RegisterType(type, [alias], [access])

Parameters:

• T 或 type
  要公开的 CLR 类型。

  CLR type to expose.

• alias
  可选脚本名。

  Optional script name.

• access
Constructor、Static 或 All。

  Constructor, Static, or All.

Returns

无。

None.

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

BuildAsync(...)

Parameters:

• 可传入 ScriptSource[]、入口路径、入口路径集合或取消令牌。

  Accepts ScriptSource[], an entry path, entry paths, or a cancellation token.

Returns

表示编译完成的 Task。

Task completing when compilation finishes.

边界

BuildAsync() 枚举当前 Resolver 的全部来源；BuildAsync(string) 从入口构建依赖图。

BuildAsync() enumerates all sources from the current resolver; BuildAsync(string) builds the dependency graph from an entry.

await engine.BuildAsync("main.as");

CompileBlock(source, parameters) / CompileBlock(source, options)

Parameters:

• source
  语句体，不是模块源码。

  Statement body, not module source.

• parameters 或 options
  位置参数名或块选项。

  Positional parameter names or block options.

Returns

可调用且可释放的 CompiledBlock。

Invokable and disposable CompiledBlock.

using var block = engine.CompileBlock("return left + right;", ["left", "right"]);
var result = block.Invoke(ScriptDatum.FromNumber(20), ScriptDatum.FromNumber(22));

CreateDomain(globalConfiguration, [userState]) / CreateDomain([domainGlobal], [userState])

Parameters:

• globalConfiguration
  可选 Domain 全局配置回调。

  Optional domain-global configuration callback.

• domainGlobal
  可选自定义环境。

  Optional custom environment.

• userState
  可选 ScriptObject 状态。

  Optional ScriptObject state.

Returns

已初始化的 ScriptDomain。

Initialized ScriptDomain.

using var domain = engine.CreateDomain(global => global.Define("HOST_VALUE", 42));

CreateEmptyDomain(globalConfiguration, [userState])

Parameters:

• 与 CreateDomain 相同。

  Same conceptual inputs as CreateDomain.

Returns

不执行已编译模块初始化器的 Domain。

Domain that does not run compiled module initializers.

using var domain = engine.CreateEmptyDomain(global => global.Define("MODE", "design"));

NewEnvironment()

Parameters:

• 无。

  None.

Returns

继承 Engine Global 的新 ScriptGlobal。

New ScriptGlobal inheriting Engine Global.

var environment = engine.NewEnvironment();
environment.Define("TENANT", "north");
using var domain = engine.CreateDomain(environment);