Getting Started

Getting Started

Install RuleScript

dotnet add package RuleScript.Core --version 1.10.0

Most host code starts with RuleScript.Core.Runtime:

using RuleScript.Core.Runtime;

Execute a Script

var engine = new RuleScriptEngine();
var context = new RuntimeContext();

context.Set("Name", "Mick");
context.Set("Distance", 519);

engine.Execute("""
    var message = "Hello " + Name;

    if Distance > 500 then:
        result = message + ": NG";
    else:
        result = message + ": OK";
    endif
    """, context);

Console.WriteLine(context.Get<string>("result"));

RuntimeContext is the boundary between RuleScript and the host. Use Set, Get, Get<T>, TryGet, Contains, GetOrDefault, Remove, and Clear to exchange values.

Execute a Project File

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules"
};

var context = engine.ExecuteFile("main");

Extensionless paths use .rules by default. Set ScriptFileExtension for another extension, or replace ImportResolver when scripts are stored outside the local file system.

Register a Host Function

engine.RegisterFunction("GetDistance", _ => 519);

var context = engine.Execute("""
    var distance = GetDistance();
    result = distance > 500;
    """);

Typed registrations describe parameters and return types before execution:

engine.RegisterFunction(
    "Add",
    [
        new RuleScriptParameterSymbol("left", RuleScriptValueType.Number),
        new RuleScriptParameterSymbol("right", RuleScriptValueType.Number)
    ],
    RuleScriptValueType.Number,
    args => Convert.ToDouble(args[0]) + Convert.ToDouble(args[1]));

Asynchronous Execution

engine.RegisterFunctionAsync("ReadAsync", async (args, cancellationToken) =>
{
    return await service.ReadAsync(args[0]?.ToString(), cancellationToken);
});

var context = await engine.ExecuteAsync("""
    var value = ReadAsync("sensor-a");
    result = value;
    """);

Async Host Functions require ExecuteAsync, ExecuteFileAsync, or a long-running runtime started with StartAsync.

Start a Host Trigger Runtime

Host Trigger is the v1.10.0 long-running runtime model. Scripts mark callable entry points with @HostTrigger, then include a dispatcher task that waits for host requests.

var engine = new RuleScriptEngine
{
    ExecutionTimeoutEnabled = false
};

var runtime = engine.CreateRuntime("""
    @HostTrigger("LotArrived")
    function OnLotArrived(lotId: string) -> void:
        Print("lot arrived: " + lotId);
        return;
    endfunction

    parallel:
        trigger task:
            dispatch;
        endtask
    endparallel
    """);

var running = runtime.StartAsync();

await runtime.TriggerAsync("LotArrived", ["LOT-001"]);
await runtime.StopAsync();
await running;

TriggerAsync enqueues a request. The script dispatcher calls the matching Host Trigger function and then continues waiting until the host calls StopAsync, cancellation is requested, or the runtime faults.

Next Steps

• Read Language Guide for complete syntax.
• Read Host Trigger for the v1.10.0 runtime model.
• Read Host Integration for embedding patterns.
• Read API Reference by Class for public APIs.