Build your first extension

What you need

• Windows 10 or 11, with a version of Nimblio that has Settings → Extensions.
• The .NET 8 SDK or later.
• Any editor. For breakpoints and one-key debugging, use VS Code with the C# extension and the Nimblio extension tools (see Live reload and debugging).

1. Install the nbext tool

nbext creates, builds, loads and packs extensions. It’s a .NET tool:

dotnet tool install --global Nimblio.Cli

2. Create a project

Pick a name made of letters and digits, and say who you are:

nbext new SpotifyTools --publisher "Acme"

This creates a SpotifyTools folder with:

• SpotifyTools.csproj, a class library that references the Nimblio.Sdk package.
• extension.json, which says who you are and what the extension may do. You edit it by hand.
• Actions.cs, with one action to start from.
• VS Code settings: a Debug in Nimblio launch configuration and build tasks.

The extension id is acme.spotify-tools: your publisher name and the project name, in lower case. Pick it with --id if you want another one. Never change it once people use your extension, because their workflows refer to it.

{
  // Who you are and what the extension may do. The build adds the actions from your [NimblioAction] classes.
  "id": "acme.spotify-tools",
  "name": "Spotify Tools",
  "version": "0.1.0",
  "publisher": "Acme",
  "description": "Describe what your actions do.",
  "engines": { "nimblio": ">=0.1.0" },
  // network, processes, files, input, clipboard, notifications, system. Ask only for what you use.
  "permissions": [ "notifications" ]
}

3. Look at the action

An action is two classes: an input class whose properties are the step’s settings, and the action itself.

using Nimblio.Sdk;

[assembly: NimblioCategory("spotify-tools", "Spotify Tools", Icon = "puzzle", Color = "#9196FF")]

namespace SpotifyTools;

public sealed class HelloInput
{
    [Field("Name", Tokens = true, Placeholder = "World", Required = "Enter a name.")]
    public string Name { get; set; } = "World";

    [Field("Show a notification")]
    public bool Notify { get; set; } = true;
}

[NimblioAction("hello", Name = "Say hello", Category = "spotify-tools", Icon = "message",
    Description = "Greets someone. Replace this with your first real action.",
    Output = "Greeting", Summary = "Say hello to {name}")]
public sealed class Hello : NimblioAction<HelloInput>
{
    public override async Task<ActionResult> RunAsync(HelloInput input, IActionContext context, CancellationToken cancellationToken)
    {
        var text = $"Hello, {input.Name}!";
        if (input.Notify) await context.NotifyAsync("Spotify Tools", text);
        return ActionResult.WithOutput($"Said hello to {input.Name}", text);
    }
}

• [NimblioAction] gives the action its id, name, icon, description and the summary shown on the step card.
• [Field] turns a property into a setting. Its type picks the control: string is a text box,bool a switch. Tokens = true lets people insert values from earlier steps.
• RunAsync does the work and returns what happened, here with a value later steps can use.

When you build, the SDK reads these attributes and writes the full extension.json next to your dll. It never runs your action code to do so.

4. Load it into Nimblio

In Nimblio, open Settings → Extensions and turn on Developer mode. This lets tools on your PC, signed in as you, load extensions from a build folder. Then, in the project folder:

cd SpotifyTools
nbext dev

nbext Building SpotifyTools.csproj…
nbext Loaded Spotify Tools 0.1.0 (1 action(s)) into Nimblio from C:\dev\SpotifyTools\bin\Debug\net8.0-windows
nbext Watching for changes. Press Ctrl+C to stop.

Open Nimblio and search the action library for Say hello. Add it to a workflow and press Run: you get a notification, and the step’s log line in Run history. The extension also shows in Downloads with aDev badge.

5. Change it and save

Rename the action, add a field, or change the summary, then save. nbext dev rebuilds and reloads the extension, and the action library updates within a few seconds. You don’t restart Nimblio. If the build fails, Nimblio keeps the last good build.

Press Ctrl+C to stop. The dev copy is unloaded from Nimblio.

6. Pack it

nbext pack

This builds in Release and writes bin\Release\acme.spotify-tools-0.1.0.nbext. Install it on any PC fromDownloads → Import…, or send it to someone. Package and sharecovers versions and updates.