Host Integration

Host Integration

Configure the engine, resolve source, isolate domains, expose globals, and register CLR types safely.

Applies to 4.0.0.

Home · .NET Host API Reference

On this page

• Configuring the Engine and Source Resolver
• Creating Domains, State, and Globals
• CLR Interop
• Lifetime and Concurrency
• Next steps

Configuring the Engine and Source Resolver

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() 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.

Creating Domains, State, and Globals

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;
}

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 Interop

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);
}

Lifetime and Concurrency

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);
}

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

Next steps

• .NET Host API Reference for complete host types and members.
• Troubleshooting and Security for isolation and failure diagnosis.