Table of Contents

Create a Package

The Bonsai language can be extended with custom packages, which are installed and shared using NuGet. Packages are typically written in the C# programming language, using the Visual Studio development environment. The Bonsai installer includes project templates that make it easier to create your own package project. Once you have developed and refined your custom extensions you can package the code for installing in the Bonsai editor, or sharing with the community.

Pre-requisites

  1. Visual Studio. You can install the Community edition for free.

  2. Bonsai VS Extensions. From the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it.

Creating a package project

  1. Start Visual Studio.

  2. Select the Create a new project option. In the Create a new project dialog, type bonsai in the search toolbox. The project template for creating a Bonsai package should now be displayed.

    Creating a new Bonsai package project

  3. Give the project a name and a location, and press the Create button. After the project is created, you should see that a file "Source1.cs" has been added to the solution explorer. This file contains an example implementation of a custom source.

    Bonsai source template

  4. Every Bonsai operator specifies an observable sequence using the IObservable<T> interface. The System.Reactive package provides a comprehensive library of methods used to generate and manipulate observable sequences in C#. The simplest way to implement a source is by using the methods in the Observable class.

    As an example, the expression below will generate a simple periodic sinewave by applying the projection operator Select to the incremental counter sequence generated by a Timer.

    [Description("")]
[Combinator(MethodName = nameof(Generate))]
[WorkflowElementCategory(ElementCategory.Source)]
public class Source1
{
    public IObservable<double> Generate()
    {
        return Observable
            .Timer(
                dueTime: TimeSpan.Zero,
                period: TimeSpan.FromSeconds(0.5))
            .Select(counter => Math.Sin(counter));
    }
}

  5. We can test our operator by starting the project with F5. This will automatically launch the Bonsai editor with our package preloaded in the Toolbox. Add the new Source1 node and run the workflow.

    Running the sine source

  6. If we need to parameterize our operator, we can add new public properties to the class. Custom editors can be used to provide interactive widgets for editing the property values. Several common widgets are provided in the DesignTypes class. For example, to make the period customizable with a slider over a specified range, we can modify our source operator:

    [Description("")]
[Combinator(MethodName = nameof(Generate))]
[WorkflowElementCategory(ElementCategory.Source)]
public class Source1
{
    [Range(0.1, 2)]
    [Editor(DesignTypes.SliderEditor, DesignTypes.UITypeEditor)]
    public double PeriodSeconds { get; set; } = 0.5;

    public IObservable<double> Generate()
    {
        return Observable
            .Timer(
                dueTime: TimeSpan.Zero,
                period: TimeSpan.FromSeconds(PeriodSeconds))
            .Select(counter => Math.Sin(counter));
    }
}

  7. It is also possible to debug our code while it is running by setting breakpoints, either by clicking on the left of the line we want to debug or by hitting F9 over the target code. After this, you can run the code step by step and inspect the runtime value of variables.

    Debugging the sine source

  8. Finally, we can add new operators by right-clicking the project name in the solution explorer and selecting Add > New Item. Templates for creating the most common operator types are available under the Bonsai category.

    Creating a new Bonsai transform

    For example, we can create a simple transform that tests whether each of the values emitted by the sinewave generator is positive:

    [Combinator]
[Description("")]
[WorkflowElementCategory(ElementCategory.Transform)]
public class Transform1
{
    public IObservable<bool> Process(IObservable<double> source)
    {
        return source.Select(input => input > 0);
    }
}
Tip

Use XML documentation comments to document your code. Check out the Documentation with docfx article for information on how to use docfx to automatically generate documentation pages for your package.

Publishing a package project

  1. Double-click the name of the project in the Visual Studio Solution Explorer to open up the package metadata.

    Inspecting the package metadata

  2. Fill in or edit all the relevant metadata fields. These are critical to correctly communicate the provenance of your project to other users. Please pay special attention to Title, Description, Authors, Copyright, PackageProjectUrl, PackageLicenseExpression, PackageIcon and PackageTags to make sure that they correctly describe your project. Make sure that Version is correctly assigned in every new release to avoid problems during package updates.

    Tip

    Use version suffixes for sharing prerelease versions for testing, e.g. 0.1.0-alpha. If a package version has a prerelease suffix, it will only be listed by the package manager if the checkbox "Include prerelease" is checked.

  3. Build the project in Release mode. If all metadata is correctly specified, the build process should generate a .nupkg file as part of the output. By default, it will be placed in the same bin\Release folder where the project assembly (.dll) is generated.

  4. To install the package in the editor, configure a new package source pointing to a folder containing your generated .nupkg file, or simply copy the .nupkg file to the Gallery folder of your local Bonsai installation. The package should then be listed in the package manager (make sure to select the package source where the package is located if you cannot find it in the list).

    Warning

    If you have your custom package installed in the same editor used to debug the source code, Bonsai will prefer the installed package over the compiled source code library. In this case, either uninstall the package, or use a local Bonsai installation.

    Note

    If you would like to share the package with the broader Bonsai community, consider publishing your package in the Bonsai Community feed. Click the Connect to Feed button for more details on how to push packages to the feed.

Edit this page