6.1. ClearScript

ClearScript

Stateflows.Extensions.ClearScript lets State Machine hooks, Activity actions, and reusable Actions execute scripts through Microsoft ClearScript. It provides convenience registration methods and configurable scripted behavior implementations; it does not select or install a JavaScript engine for the host.

Configure the engine

Install Stateflows.Extensions.ClearScript and a ClearScript engine implementation supported by your application. Supply a factory that returns an IScriptEngine:

using Microsoft.ClearScript;
using Microsoft.ClearScript.V8;
using Stateflows;

services.AddStateflows(stateflows => stateflows
    .AddClearScript(_ =>
        Task.FromResult<IScriptEngine>(new V8ScriptEngine())));

This example uses Microsoft.ClearScript.V8; install that package and deploy its platform-specific native dependencies. A different engine can be supplied through the same factory. The extension creates an engine for each script execution and disposes it after execution. If no factory has been registered, script execution throws a StateflowsException.

Use scripts in definitions

For example, a State Machine state can run a script on entry:

using Stateflows;
using Stateflows.StateMachines;

public sealed class Order : IStateMachine
{
    public static void Build(IStateMachineBuilder machine) => machine
        .AddInitialState("Waiting", state => state
            .AddOnEntry_ClearScript("Console.WriteLine('Entered Waiting');")
            .AddTransition<Confirm>("Confirmed"))
        .AddFinalState("Confirmed");
}

The extension also provides _ClearScript methods for state exit and composite initialization/finalization, transition and deferral guards/effects, and Activity actions. For reusable Actions, AddAction_ClearScript registers a named script as the Action implementation. See the extension source for the supported builder overloads.

The base script contexts expose behaviorContext and executionContext; State Machine hooks also expose stateContext, and Action implementations expose actionContext. Console is added as a host type. Treat scripts as trusted application code: the script can access the host objects deliberately exposed to it, so do not execute untrusted script text.