JsScriptTaskExecutor.Net 1.0.1

JsScriptTaskExecutor.Net

A .NET library powered by the Microsoft ClearScript V8 engine to safely execute JavaScript scripts, with strongly-typed inputs/outputs, timeout control, and dynamic library injection. It is particularly useful for executing script tasks in BPMN or workflow engines where dynamic logic is required.

Features

• Execute JavaScript using Microsoft ClearScript V8 engine
• Strongly-typed input/output variable handling (primitives, objects, lists)
• Inject reusable JavaScript libraries at runtime
• Timeout control to prevent long-running or stuck scripts
• Type-safe conversions between script and .NET types

Installation

Install via NuGet:

dotnet add package JsScriptTaskExecutor.Net

Or using the NuGet Package Manager:

PM> Install-Package JsScriptTaskExecutor.Net

🛠 Quick Start (Package Usage)

1. Register the service in your Program.cs:

using ScriptTaskExecutor.Engine;

var builder = WebApplication.CreateBuilder(args);

// Configure ScriptTaskExecutor with path to JS libraries
builder.Services.AddScriptTaskExecutor(librariesPath: "path/to/your/js/libraries");

var app = builder.Build();

This sets up the IScriptTaskExecutor service for injection into controllers or other services.

2. Basic Usage Example

using ScriptTaskExecutor.Engine.DataTypes;
using ScriptTaskExecutor.Engine.Executors;
using ScriptTaskExecutor.Engine.Models;

public class ScriptService
{
    private readonly IScriptTaskExecutor _executor;

    public ScriptService(IScriptTaskExecutor executor)
    {
        _executor = executor;
    }

    public async Task RunScript()
    {
        var context = new ScriptExecutionContext
        {
            Script = "result = input1 + input2;",
            Inputs = new Dictionary<string, (DataTypesEnum Type, object? DefaultValue)>
            {
                { "input1", (DataTypesEnum.Int32, 5) },
                { "input2", (DataTypesEnum.Int32, 10) }
            },
            Outputs = new Dictionary<string, DataTypesEnum>
            {
                { "result", DataTypesEnum.Int32 }
            },
            TimeoutMs = 5000
        };

        var outputs = await _executor.ExecuteScript(context);
        Console.WriteLine($"Result: {outputs["result"]}"); // Output: 15
    }
}

⚠️ Important — Declaring Output Variables in JavaScript

Any JavaScript variable you expect to retrieve as an output variable must be declared with var.

In JavaScript, let and const are block-scoped and are not attached to the global object, so they will not be accessible from the .NET side after script execution.

Why this is required

When the V8 engine executes your script, only variables declared with var at the top level are added as properties of the global object. Variables declared with let or const live in the script’s internal scope and are not visible outside the script.

✅ Example (works)

var result = inputValue * 2;

❌ Example (will not work)

let result = inputValue * 2;
const result = inputValue * 2;

💡 If you must use let or const

Explicitly assign the value to the global object:

let result = inputValue * 2;
globalThis.result = result; // Now accessible from C#