Package and share

Pack a .nbext file

nbext pack

This builds in Release and writes bin\Release\<id>-<version>.nbext.dotnet build -c Release does the same, so CI and other IDEs need nothing more. Inside, the file is a ZIP:

nimblio.media-controls-1.1.0.nbext   (a ZIP file)
├─ extension.json                    what you wrote, plus entry, categories and actions from the build
├─ bin/
│  ├─ MediaControls.dll              your code
│  ├─ MediaControls.deps.json
│  └─ …                              NuGet packages you use
└─ assets/
   └─ icon.png                       files you put in assets/

The Nimblio.Sdk assemblies aren’t included: Nimblio provides them. Other NuGet packages your project uses are, with their own dependencies.

Give it an icon

Put a square PNG of at least 96 × 96 pixels in an assets folder and point to it fromextension.json with "icon": "assets/icon.png". Nimblio shows it in the install dialog and in Downloads. Without one, people see a puzzle piece in your category’s colour.

Check it

nbext validate runs the checks Nimblio runs before it shows the install dialog:

> nbext validate bin\Release\nimblio.media-controls-1.1.0.nbext
nbext Media controls 1.1.0 (nimblio.media-controls) by Nimblio samples: 5 action(s), 6 file(s), 35 KB.
nbext Asks for: input, system
nbext Needs Nimblio >=0.1.0. Not signed (signing comes with the Marketplace).

To try it as people will, install the file on a PC where you don’t develop, or run nbext install <file>to open Nimblio’s install dialog for it.

What people see when they install it

• Your extension’s name, icon, publisher, version and description.
• It can: one line per permission in extension.json, such as “Connect to the internet” or “Control keyboard and mouse”. See the permission list.
• Adds N actions, with their names.
• A warning that the extension isn’t signed and runs with their Windows account’s access.

Fewer permissions and a clear description make people more willing to install. If you need network, say in the description which service you connect to.

Versions and updates

Use version numbers like 1.4.0, and raise them with every file you share. When someone opens a newer version, Nimblio shows an update dialog (“Updates from 1.3.0 to 1.4.0”). Older versions show a warning first, and the same version is offered as a reinstall.

To keep people’s workflows working through updates:

• Never change an extension id or an action id. Workflows store them.
• Don’t rename or remove a setting. Its key is the property name. If you must, keep reading the old one: workflows saved before the update still have it.
• Give new settings a default that keeps the old behaviour.
• Don’t remove an action. Steps that use it would fail with “This action’s extension is missing”. Keep it working and leave it out of your documentation instead.
• Changing names, descriptions, icons and summaries is always safe.

Set engines.nimblio in extension.json to the oldest Nimblio your extension works with, such as ">=0.2.0". Older versions of Nimblio refuse to install it and say which version it needs.

Share it

For now, share the .nbext file itself: on your website, in a GitHub release, or by email. People install it from Downloads → Import…, by double-clicking it, or by dragging it onto Nimblio.