AI Core: App Runtime Contexts

AI-first map of runtime contexts used by scripts, modules, and application services.

App Runtime Contexts Discovery Map

Reference map for separating EyeAuras host code, SDK-only code, top-level scripts, ordinary C# helper classes, object-style executors, and Razor components.

User Intents

  • Understand where dependency access is available.
  • Move code from a script file into a helper class.
  • Decide whether a service must be passed explicitly.
  • Distinguish app/plugin module code from script project code.

Concept Model

  • Top-level script code runs with host-provided capabilities.
  • Ordinary C# files next to a script compile as normal classes and do not automatically inherit script host members.
  • Object-style action/trigger executors receive context through their base classes.
  • Razor components use Blazor [Inject] and component lifecycle rules.
  • App/plugin code uses the application DI/module system.
  • SDK-only code can reference contracts but cannot assume a live host.

Pass a host capability to a helper

Pass the current script's IFluentLog explicitly. Put the call in Script.csx; the class can live in an ordinary .cs file in that project:

csharp
var worker = new Worker(Log);
worker.Run();

public sealed class Worker
{
    private readonly PoeShared.Logging.IFluentLog log;
    public Worker(PoeShared.Logging.IFluentLog log) => this.log = log;
    public void Run() => log.Info("Worker started");
}

The script log receives Worker started. The class does not look up a global Log; another caller can supply a different logger. Pass variable/tree APIs and cancellation tokens in the same way.

Choose service acquisition by runtime

ContextAcquisitionBoundary
Top-level scriptSandbox member or GetService<T>()Registered containers and loaded extensions only
Ordinary C# classConstructor or method argumentNo implicit sandbox members
Razor component[Inject] / @injectBlazor host services; DataContext is passed separately
Application moduleApplication DI and Prism registrationThe host initializes modules
Standalone SDK appExplicit host/DI setupAssembly references provide types, not running services

AuraScriptSandbox resolves through its Unity container and registered related contexts. This does not make every application service available to every script. Check ownership for the actual registration; do not replace explicit cleanup with an assumption that all resolved objects are automatically disposed.

API Details

  • AuraScriptSandbox / IAuraScriptSandbox - top-level script capability surface.
  • ScriptContainerExtension - script-owned DI registration hook.
  • CsharpScriptActionExecutor - object-style action entry point.
  • CsharpScriptTriggerExecutor - object-style trigger entry point.
  • Prism.Modularity.IModule - app/plugin module contract.
  • [Inject] - Blazor component dependency injection attribute.
  • [Dependency] - Unity property injection attribute used in some runtime classes.

Prefer

  • Pass dependencies into helper classes through constructors or parameters.
  • Keep package-specific APIs documented in nuget/.
  • Use app modules for app/plugin registrations.

Avoid

  • Avoid assuming Log, AuraTree, Variables, or cancellationToken are available in ordinary helper classes.
  • Avoid using script-only dependency access patterns from Razor components.

Search Synonyms

  • top-level script
  • helper class
  • ordinary C# class
  • script globals
  • app module
  • plugin module
  • Blazor component injection
  • object-style action
  • object-style trigger

Choose a context for an operation

Use JS/DOM through an injected Razor service after the DOM exists. For serialization, top-level C# Actions resolve IConfigSerializer with GetService, while helpers accept it explicitly. The file provider distinguishes a borrowed service from a stream owned by its caller.

CsharpScriptActionExecutor and CsharpScriptTriggerExecutor receive dependencies through their base classes and container. This does not make Variables or Log global identifiers in ordinary classes.