SoftwareDriven.Blockly.Code 1.8.0

SoftwareDriven.Blockly.Code

A Blockly based code engine for .NET.

Blockly is a JavaScript library for building visual programming editors. This library takes the Blockly XML produced by such an editor and executes it server-side in C# — Blockly's own JavaScript code generators are not used. The XML is parsed into a tree of Statement objects that a custom interpreter runs.

The package contains no UI. To embed the editor itself into a Blazor application, use SoftwareDriven.Blockly.Blazor.

Installation

dotnet add package SoftwareDriven.Blockly.Code

Target framework: net10.0.

Quick start

using SoftwareDriven.Blockly.Code;
using SoftwareDriven.Blockly.Code.Parser;
using SoftwareDriven.Blockly.Code.Statements;

// 1. Parse the Blockly XML into an executable program.
var reader = new BlocklyXmlReader();
var control = reader.ReadFile("Program.xml", new BlockControlConfig()
{
    OutputTopics = BlockOutputTopic.TextPrint | BlockOutputTopic.Errors,
    DefaultOutput = BlockDefaultOutput.Console,
});

if (control == null)
    return; // The file could not be read.

// 2. Run it.
var result = control.Run(new RunContext() { Caller = "MyApp" });

// 3. Evaluate the result and read back the variables.
if (result.Type == ExecutionResultType.Error)
    Console.WriteLine(result.Message);

var answer = control.GetVariableByName("answer");
Console.WriteLine(answer?.Value);

ReadStream(Stream, BlockControlConfig?) is the equivalent overload for XML coming from a database or from the Blazor editor's Export():

using var stream = new MemoryStream(Encoding.UTF8.GetBytes(workspaceXml));
var control = reader.ReadStream(stream, config);

Writing the program back to XML — e.g. to feed it into the editor again:

var writer = new BlocklyXmlWriter();
writer.WriteFile("Program.xml", control);

using var output = new MemoryStream();
writer.WriteStream(output, control);
var xml = Encoding.UTF8.GetString(output.ToArray());

Configuration

BlockControlConfig is passed to the reader and is available afterwards as control.Config.

Keep the MaxStackDepth / MaxLoopCycles guards — they prevent a faulty user program from taking down the host process.

Values and variables

Values are stringly typed. A TypedValue holds a string? Value plus a string? Type naming a KnownType (Boolean, String, Number, Array, Colour, DateTime, TimeSpan, Dictionary, Object) or a registered custom type. BlockVariable adds a name to that pair.

Numbers and dates are always parsed and formatted with CultureInfo.InvariantCulture.

// Provide input before the run ...
control.CreateOrSetVariable("input", "42", KnownType.Number);

control.Run(new RunContext());

// ... and read the output afterwards.
foreach (var variable in control.Variables)
    Console.WriteLine($"{variable.Name} = {variable.Value} ({variable.Type})");

Further members of interest on BlockControl: Main (the top level function), Functions, GetFunctionByName(), GetVariableById(), SetVariableByName() and Copy() to run the same program several times in parallel.

Custom object types

The object members used by the GetMember / SetMember / MemberAccess blocks are resolved through an IBlockTypeRegistry. Types can be declared explicitly, taken from a .NET type by reflection, or deserialized from JSON.

var registry = new BlockTypeRegistry();

// The built-in types (Boolean, String, Number, ...).
registry.AddKnownTypes();

// A hand written type.
registry.GetOrAddType("Customer", "Customer")
        .AddMember("Name", nameof(KnownType.String))
        .AddMember("Orders", nameof(KnownType.Array));

// A type derived from a .NET class by reflection.
registry.GetOrAddReflectedType<Order>();

config.TypeRegistry = registry;

A registry can also be loaded from JSON and layered with others:

var fromJson = JsonSerializer.Deserialize<BlockTypeRegistry>(json);

var composite = new CompositeTypeRegistry();
composite.Registries.Add(registry);
composite.Registries.Add(fromJson!);

Values of registered types are JSON documents. The registry offers helpers to work with them without leaving the string world:

var value = registry.CreateValueOfRegisteredType("Customer")?.ToString();

registry.SetNestedValue("Customer", "Name", value, "\"Doe\"", out value);
registry.AppendNestedValue("Customer", "Orders", value!, "{ \"Id\": 1 }", out value);
registry.GetElementsOfNestedArray("Customer", "Orders", value, "Order", out var orders);

Custom blocks

All standard Blockly blocks are handled by the engine itself. An IBlockRepository only has to deal with custom block types; returning null from CreateStatementFromBlock defers to the built-in handling.

public class MyRepository : IBlockRepository
{
    public string? BlocksJson => myBlockDefinitionsJson; // Blockly block JSON for the editor.

    public Toolbox Toolbox { get; } = new();

    public Statement? CreateStatementFromBlock(BlockControl control, XmlNode node,
        string id, string type, BlocklyXmlReader reader)
    {
        if (type != "my_block")
            return null; // Not ours - let the engine handle it.

        return new MyStatement()
        {
            ID = id,
            Input = reader.TryCreateValueStatementFromBlock(control, node.ChildNodes.Cast<XmlNode>(), "INPUT"),
        };
    }

    public string? CreateBlockFromStatement(BlockControl control, XmlDocument doc,
        XmlElement node, Statement statement, BlocklyXmlWriter writer)
    {
        if (statement is not MyStatement my)
            return null;

        writer.CreateValue(control, doc, node, my.Input, "INPUT");
        return "my_block";
    }
}

The matching statement derives from Statement, or from ValueStatement if it yields a value. Execute is called repeatedly: return ExecutionResult.Next(child) to have a child evaluated first and ExecutionResult.Done() when finished. On the following call continueFromChildId names the child that has just completed.

public class MyStatement : ValueStatement
{
    public ValueStatement? Input { get; set; }

    public override IEnumerable<Statement> Children
    {
        get { if (Input != null) yield return Input; }
    }

    public override ExecutionResult Execute(BlockControl control, RunContext context, string continueFromChildId)
    {
        if (string.IsNullOrWhiteSpace(continueFromChildId) && (Input != null))
            return ExecutionResult.Next(Input); // Evaluate the input first.

        Result = new TypedValue()
        {
            Value = Input?.Result?.Value?.ToUpper(),
            Type = nameof(KnownType.String),
        };

        return ExecutionResult.Done();
    }

    public override Statement Copy() => new MyStatement() { ID = ID, Input = Input?.CopyV() };
}

Use CompositeRepository to combine several repositories and DefaultRepository to serve blocks.json / toolbox.json from a directory while deferring all execution to the built-in blocks:

var repository = new CompositeRepository();

var defaultRepository = new DefaultRepository();
defaultRepository.Init("Content"); // Reads Content/blocks.json and Content/toolbox.json.

repository.Repositories.Add(defaultRepository);
repository.Repositories.Add(new MyRepository());

config.BlockRepository = repository;

Toolbox

The Editor namespace models the Blockly toolbox as C# objects, so the same definition can be handed to the editor and kept under source control. ToolboxFactory provides the built-in categories as extension methods.

using SoftwareDriven.Blockly.Code.Editor;

var toolbox = new Toolbox();
toolbox.AddLogicCategory()
       .AddLoopsCategory()
       .AddMathCategory()
       .AddTextCategory()
       .AddSeparator()
       .AddVariablesCategory()
       .AddFunctionsCategory()
       .AddCategory("My blocks", category =>
       {
           category.Colour = "#00FFFF";
           category.Contents = [new Block("my_block")];
       });

toolbox.HideCategory(ToolboxFactory.ApiCategoryName);
toolbox.DisableBlock("text_print");

Suspending and resuming a run

Suspend/resume is a first-class feature: a statement may return ExecutionResult.Wait() when it depends on something external. The engine then keeps its exact position in the program (StatementIdStack, LastChildId, LastItemState), so the BlockControl can be persisted and the run continued later from exactly that block.

var result = control.Run(new RunContext());

if (result.Type == ExecutionResultType.Wait)
{
    // Persist the control (including StatementIdStack / LastChildId / LastItemState),
    // wait for the external event, then continue where the program stopped.
    control.Run(new RunContext());
}

A statement that waits should implement the pair SerializeStateAtWait() / DeserializeStateAtContinue() so that its own loop counters and intermediate values survive the interruption.