API Host AuroraEngine

AuroraEngine

Primary host entry point for compiling scripts, creating domains, registering CLR types, and compiling lightweight blocks.

Namespace: AuroraScript. Kind: class.

Back to .NET Host API Reference

Overview

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

The engine owns compiled code and configuration; a ScriptDomain owns execution state. Build once, then create one domain per isolated execution.

Quick Reference

A minimal end-to-end host flow.

var engine = new AuroraEngine(EngineOptions.Default);

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

using var domain = engine.CreateDomain();
var result = domain.Execute("MAIN", "main");

Constructors

AuroraEngine

AuroraEngine(EngineOptions options)

Creates an engine with immutable compiler, runtime, optimization, and output options.

Parameters

Name	Type	Required	Description
options	EngineOptions	Yes	Engine configuration. Cannot be null.

Returns

A new AuroraEngine instance.

Exceptions

A null configuration throws AuroraException.

var engine = new AuroraEngine(EngineOptions.Default);

Fields

Global

ScriptGlobal Global

Engine-level global prototype used by new domains.

Parameters

None.

Returns

Returns ScriptGlobal.

Behavior

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

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

ClrRegistry

ClrTypeRegistry ClrRegistry

Host-side registry for CLR types exposed to scripts.

Parameters

None.

Returns

Returns ClrTypeRegistry.

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

Methods

RegisterType

void RegisterType<T>(string alias = null, TypeAccess access = TypeAccess.All)
void RegisterType(Type type, string alias = null, TypeAccess access = TypeAccess.All)

Registers a CLR type under a script-visible alias.

Parameters

Name	Type	Required	Description
T	type parameter	Yes	CLR type to expose. Used by the generic overload.
type	Type	Yes	CLR type to expose. Used by the non-generic overload.
alias	string	No	Script-visible name for the type.
access	TypeAccess	No	Allowed constructor and static-member access. Defaults to TypeAccess.All.

Returns

None.

Behavior

Registration grants capability to scripts, so register reviewed types only and expose the smallest suitable TypeAccess.

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

BuildAsync

Task BuildAsync(params ScriptSource[] sources)
Task BuildAsync(CancellationToken cancellationToken = default)
Task BuildAsync(string entryPath, CancellationToken cancellationToken = default)
Task BuildAsync(IEnumerable<string> entryPaths, CancellationToken cancellationToken = default)
Task BuildAsync(CancellationToken cancellationToken, params ScriptSource[] sources)

Compiles modules and their import/include graph.

Parameters

Name	Type	Required	Description
sources	ScriptSource[]	No	Explicit sources to compile instead of resolver lookup.
entryPath	string	Yes	Single entry path resolved through Compiler.SourceResolver.
entryPaths	IEnumerable<string>	Yes	Multiple entry paths resolved through Compiler.SourceResolver.
cancellationToken	CancellationToken	No	Token that cancels compilation.

Returns

A Task that completes when compilation finishes.

Behavior

• BuildAsync(string) resolves the entry path through Compiler.SourceResolver and builds its dependency graph.
• BuildAsync() enumerates all sources from Compiler.SourceResolver.GetAllSourcesAsync.
• Before module analysis, the compiler scans resolver-visible project .as files and loads standalone @global() declaration files when they exist.
• @global() declarations are optional compile-time contracts for host globals and do not depend on import or include.

Exceptions

Compilation failures throw AuroraCompilationException with one diagnostic per problem.

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

CompileBlock

CompiledBlock CompileBlock(string source, string[] parameters)
CompiledBlock CompileBlock(string source, CompileBlockOptions options = null)

Compiles a function body for direct invocation.

Parameters

Name	Type	Required	Description
source	string	Yes	Statement body, not module source.
parameters	string[]	Yes	Positional parameter names exposed as local variables. Used by the first overload.
options	CompileBlockOptions	No	Block options including parameter names and diagnostic source name.

Returns

An invokable, disposable CompiledBlock.

Behavior

• CompileBlock accepts statement bodies only, not module syntax.
• CompileBlock does not support @module, @global(), import, include, export, or declare.

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

CreateDomain

ScriptDomain CreateDomain(Action<ScriptGlobal> globalConfiguration, ScriptObject userState = null)
ScriptDomain CreateDomain(ScriptGlobal domainGlobal = null, ScriptObject userState = null)

Creates an initialized execution domain for compiled modules.

Parameters

Name	Type	Required	Description
globalConfiguration	Action<ScriptGlobal>	Yes	Domain-global configuration callback. Used by the first overload.
domainGlobal	ScriptGlobal	No	Custom domain environment, typically from NewEnvironment().
userState	ScriptObject	No	Host state attached to the domain.

Returns

An initialized ScriptDomain.

Behavior

Build once and create separate domains for isolated executions over the same compiled code. Use the callback overload to expose per-domain host services or state.

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

CreateEmptyDomain

ScriptDomain CreateEmptyDomain(Action<ScriptGlobal> globalConfiguration, ScriptObject userState = null)

Creates a domain without running the compiled module initializer.

Parameters

Name	Type	Required	Description
globalConfiguration	Action<ScriptGlobal>	Yes	Domain-global configuration callback.
userState	ScriptObject	No	Host state attached to the domain.

Returns

A ScriptDomain that does not run compiled module initializers.

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

NewEnvironment

ScriptGlobal NewEnvironment()

Creates a global environment inheriting from the engine global.

Parameters

None.

Returns

A new ScriptGlobal inheriting the engine Global.

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