Reference

extension.json

You write the top part by hand. The build adds entry, protocol, categories andactions from your attributes and writes the result next to your dll. Comments and trailing commas are allowed.

{
  "id": "acme.spotify-tools",
  "name": "Spotify Tools",
  "version": "1.2.0",
  "publisher": "Acme",
  "description": "Control Spotify playback and playlists from your workflows.",
  "icon": "assets/icon.png",
  "homepage": "https://example.com/spotify-tools",
  "engines": { "nimblio": ">=0.1.0" },
  "permissions": [ "network" ],
  "icons": {
    "playlist": "M3.75 5.25h9M3.75 9.25h9M3.75 13.25h5.5M14.5 11v5.25M14.5 16.25a1.75 1.75 0 1 1-1.75-1.75"
  }
}

What the build adds

You rarely need to read this part, but it’s what Nimblio, nbext validate and the MCP server see. Fieldtype is the lower-case kind; show comes from[ShowWhen] and validate from Required, Regex, Min andMax.

"entry": "bin/SpotifyTools.dll",
"protocol": 1,
"categories": [ { "id": "spotify", "name": "Spotify", "icon": "music", "color": "#1DB954" } ],
"actions": [
  {
    "id": "set_volume",
    "name": "Set Spotify volume",
    "category": "spotify",
    "icon": "volume",
    "summary": "Set Spotify's volume to {level}%",
    "fields": [
      { "key": "level", "label": "Volume", "type": "slider", "default": "40", "min": 0, "max": 100, "unit": "%" },
      { "key": "device", "label": "Device", "type": "text", "optional": true,
        "show": { "field": "level", "notEquals": "0" },
        "validate": { "regex": "^[A-Za-z0-9 ]+$", "message": "Use letters, digits and spaces." } }
    ]
  }
]

Permissions

People see these lines in the install dialog. Nimblio enforces the ones it provides; for the others, declaring them is a promise to the person, so declare everything your code does.

Call context.Require(Permissions.Network) (or any other) at the start of an action to fail with a clear message when the declaration is missing, instead of doing something the person didn’t agree to.

Icons

Icon on actions and categories takes any icon name from Nimblio’s own set, such as play,music, volume, message, globe, folder,keyboard, bell or puzzle. To draw your own, add it to icons inextension.json as SVG path data on a 20 × 20 grid. Nimblio strokes it at 1.5 pixels with round ends, in your category’s colour, like its own icons. Then use its name in Icon.

nbext commands

Commands that work on a project use the current folder, or --project <folder or .csproj>.

Build properties

The Nimblio.Sdk package adds these steps to your project’s build. You can set the properties in the .csproj:

NimblioPackOnBuild

true in Release by default: every Release build also writes the .nbext.

NimblioPackageDir

Where the .nbext goes. Default: bin\<Configuration>.

NimblioManifest

Your hand-written extension.json. Default: next to the project file.

Everything in an assets folder next to the project goes into the package.

Error codes

Run history and the error panel show these codes, which help when people report a problem to you.

Limits

• A package can be up to 50 MB unpacked and contain up to 2,000 files. Paths that leave the package are refused.
• Action ids: lower-case letters, digits, - or _, up to 48 characters. Setting keys: a letter, then letters, digits or _, up to 40.
• TimeoutSeconds: 1 to 43,200 (12 hours).
• The extension runs on .NET 8 as a 64-bit Windows process. Target net8.0 or net8.0-windows.
• The host starts on first use, and stops after 5 idle minutes. Keep ActivateAsync short: it has 30 seconds.

Where Nimblio keeps things

Environment variables

NIMBLIO_EXE

Where nbext install finds Nimblio when it isn’t in C:\Program Files\Nimblio and Developer mode is off.

NIMBLIO_DEV_PIPE

Another name for the developer pipe, set for both Nimblio and the tools. Useful when testing against a second copy of Nimblio.

NIMBLIO_SDK_FEED

A NuGet folder or feed that nbext new adds to the new project’s nuget.config, for SDK builds that aren’t on NuGet.