API Host ScriptDomain

ScriptDomain

Isolated script execution environment

Back to .NET Host API Reference

Overview

ScriptDomain is bound to a compiled AuroraEngine, but owns an independent Global, module registry, and optional UserState. It implements IDisposable and must be disposed when no longer needed.

Properties

Global

ScriptGlobal Global

Returns

Current domain global, owning engine, and optional state.

// Given a configured AuroraEngine named engine:
using var domain = engine.CreateDomain();
Console.WriteLine(ReferenceEquals(domain.Engine, engine));
domain.Global.Define("REQUEST_ID", "r-42");

Engine

AuroraEngine Engine

Parameters

None.

Returns

Returns AuroraEngine.

UserState

ScriptObject UserState

Parameters

None.

Returns

Returns ScriptObject.

Methods

Execute

Executes an exported module method.

ScriptDatum Execute(string moduleName, string methodName)

ScriptDatum Execute(string moduleName, string methodName, params ScriptObject[] arguments)

ScriptDatum Execute(string moduleName, string methodName, params ScriptDatum[] arguments)

ScriptDatum Execute(string moduleName, string methodName, ScriptObject userState, params ScriptObject[] arguments)

ScriptDatum Execute(string moduleName, string methodName, ScriptObject userState, params ScriptDatum[] arguments)

Parameters

Name	Type	Required	Description
moduleName	string	Yes	@module name.
methodName	string	Yes	Exported function name.
arguments	ScriptObject[] / ScriptDatum[]	Varies	Arguments passed to the exported method; the accepted element type depends on the selected overload.
userState	ScriptObject	Varies	Per-call host state used by overloads that explicitly accept it; overloads without it use the domain context.

Returns

ScriptDatum result.

// Given a configured AuroraEngine named engine:
using var domain = engine.CreateDomain();
var executionResult = domain.Execute(
    "MAIN",
    "main",
    ScriptDatum.FromNumber(20));

GetMethod

Gets a compiled closure for advanced host-side invocation.

ClosureFunction GetMethod(string moduleName, string methodName)

Parameters

Name	Type	Required	Description
moduleName	string	Yes	Module name.
methodName	string	Yes	Exported function name.

Returns

ClosureFunction for advanced invocation.

// Given an initialized ScriptDomain named domain:
var method = domain.GetMethod("MAIN", "main");
var invocationResult = method.InvokeClrDetached(ScriptDatum.FromNumber(20));

prefer Execute normally; use GetMethod only when controlling ScriptContext or repeatedly invoking a closure is needed.

GetModule

ScriptObject GetModule(string moduleName)

Parameters

Name	Type	Required	Description
moduleName	string	Yes	Module name.

Returns

Module object.

// Given an initialized ScriptDomain named domain:
var module = domain.GetModule("MAIN");

DynamicPatch

Applies a hot patch to the domain.

void DynamicPatch(ScriptSource source, HotPatchType patchType)

void DynamicPatch(string modulePath, string script, HotPatchType patchType)

Parameters

Name	Type	Required	Description
source	ScriptSource	Varies	Patch source supplied to the ScriptSource overload.
patchType	HotPatchType	Yes	HotPatchType flags.
modulePath	string	Varies	Absolute file path or virtual full path used by the string overload.
script	string	Varies	Patch source text.

Returns

None.

// Given an initialized ScriptDomain named domain:
domain.DynamicPatch(
    "scripts/main.as",
    "@module(MAIN); export func run() { return 42; }",
    HotPatchType.Replace);

Behavior and exceptions

Note

The string overload requires an absolute file path or virtual full path under the current SourceResolver root. Composite resolvers choose the longest matching root.

DynamicPatchAsync

Asynchronously applies a hot patch to the domain.

Task DynamicPatchAsync(ScriptSource source, HotPatchType patchType, CancellationToken cancellationToken = default)

Task DynamicPatchAsync(string modulePath, string script, HotPatchType patchType, CancellationToken cancellationToken = default)

Parameters

Name	Type	Required	Description
source	ScriptSource	Varies	Patch source supplied to the ScriptSource overload.
patchType	HotPatchType	Yes	Patch operation and dependency behavior.
cancellationToken	CancellationToken	No	Token used to cancel the asynchronous patch operation.
modulePath	string	Varies	Absolute file path or virtual full path used by the string overload.
script	string	Varies	Replacement or incremental script source used by the string overload.

Returns

Task for patch completion.

// Given an initialized ScriptDomain named domain:
await domain.DynamicPatchAsync(
    "scripts/main.as",
    "export func added() { return 1; }",
    HotPatchType.Incremental);

ReplacePatch

Replaces the target module with in-memory patch source.

void ReplacePatch(string modulePath, string script, bool ignoreDepends = false)

Parameters

Name	Type	Required	Description
modulePath	string	Yes	Target path.
script	string	Yes	Replacement or incremental source.
ignoreDepends	bool	No	Whether to skip dependency updates.

Returns

None.

// Given an initialized ScriptDomain named domain:
domain.ReplacePatch("scripts/main.as", "@module(MAIN); export func run() { return 42; }");
domain.IncrementalPatch("scripts/main.as", "export func added() { return 1; }");

Behavior and exceptions

Note

modulePath must be an absolute file path or virtual full path under the current SourceResolver root.

ReplacePatchAsync

Task ReplacePatchAsync(string modulePath, string script, bool ignoreDepends = false, CancellationToken cancellationToken = default)

Parameters

Name	Type	Required	Description
modulePath	string	Yes	Absolute file path or virtual full path of the target module.
script	string	Yes	Replacement or incremental script source.
ignoreDepends	bool	No	true to skip dependent-module updates; otherwise false.
cancellationToken	CancellationToken	No	Token used to cancel the asynchronous patch operation.

Returns

Task.

// Given an initialized ScriptDomain named domain:
await domain.ReplacePatchAsync("scripts/main.as", "@module(MAIN); export func run() { return 42; }");
await domain.IncrementalPatchAsync("scripts/main.as", "export func added() { return 1; }");

Dispose

void Dispose()

Parameters

None.

Returns

None.

Releases domain-associated resources; do not use the domain afterward.

// Given a configured AuroraEngine named engine:
using var domain = engine.CreateDomain();
var executionResult = domain.Execute("MAIN", "run");

IncrementalPatch

Adds or updates members in the target module.

void IncrementalPatch(string modulePath, string script, bool ignoreDepends = false)

Parameters

Name	Type	Required	Description
modulePath	string	Yes	Absolute file path or virtual full path of the target module.
script	string	Yes	Replacement or incremental script source.
ignoreDepends	bool	No	true to skip dependent-module updates; otherwise false.

Returns

None.

Behavior and exceptions

Note

modulePath must be an absolute file path or virtual full path under the current SourceResolver root.

IncrementalPatchAsync

Task IncrementalPatchAsync(string modulePath, string script, bool ignoreDepends = false, CancellationToken cancellationToken = default)

Parameters

Name	Type	Required	Description
modulePath	string	Yes	Absolute file path or virtual full path of the target module.
script	string	Yes	Replacement or incremental script source.
ignoreDepends	bool	No	true to skip dependent-module updates; otherwise false.
cancellationToken	CancellationToken	No	Token used to cancel the asynchronous patch operation.

Returns

Returns Task.

Behavior and exceptions

Note

modulePath must be an absolute file path or virtual full path under the current SourceResolver root.