Live reload and debugging

Turn on Developer mode

In Nimblio, open Settings → Extensions and turn on Developer mode. Nimblio then listens for the nbext tool and the VS Code extension on a named pipe that only your Windows account can open. Turn it off when you’re done: Nimblio stops listening and unloads extensions loaded from build folders.

Live reload with nbext dev

Run this in your extension’s folder (or pass --project):

nbext dev

1. It builds your project in Debug.
2. It loads the build folder into Nimblio, without copying it. Your actions appear in the library, and the extension shows in Downloads with a Dev badge. A dev copy takes the place of an installed copy of the same extension while it’s loaded.
3. It watches your files. When you save a .cs, .csproj, .json, image or MSBuild file, it rebuilds and reloads. Nimblio stops the extension’s host, reads the newextension.json and updates the library and any open workflow. The next run starts the new build.
4. It unloads the extension when you press Ctrl+C, or when Nimblio quits or Developer mode is turned off.

If a build fails, the errors print in the terminal and Nimblio keeps the last good build. Use--no-watch to load once without watching.

Nimblio loads a copy of your build, not the files in bin, so the build can always overwrite them, even while a workflow runs.

Debug in VS Code

You need the C# extension from Microsoft and the Nimblio extension tools.

Projects made with nbext new already have this launch configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug in Nimblio",
      "type": "nimblio",
      "request": "launch",
      "project": "${workspaceFolder}"
    }
  ]
}

1. Set a breakpoint in your action’s RunAsync.
2. Press F5 on Debug in Nimblio. VS Code runs nbext dev --debugin a terminal.
3. Run a workflow that uses your action. Nimblio starts the extension’s host, which waits for a debugger; VS Code attaches to it, and your breakpoint hits.
4. Edit and save. The extension reloads, and VS Code attaches again the next time the host starts.

nbext Loaded Spotify Tools 0.1.0 (3 action(s)) into Nimblio from C:\dev\SpotifyTools\bin\Debug\net8.0-windows
nbext Watching for changes. Press Ctrl+C to stop.
nbext Extension host started (process 18244), waiting for a debugger to attach…

The status bar shows the dev session. The command palette has more, all under Nimblio:

• New extension…
• Start dev session (reload on save), without the debugger.
• Start dev session and attach debugger
• Stop dev session
• Build .nbext package
• Install .nbext in Nimblio, also on .nbext files in the Explorer.

The extension also checks extension.json as you type, with completions for every property and permission.

Debug in Visual Studio or Rider

The build steps come from the Nimblio.Sdk package, so any IDE builds and packs extensions. To debug, runnbext dev --debug in a terminal, run a workflow that uses your action, then attach to theNimblio.ExtensionHost.exe process whose id the terminal prints (Debug → Attach to Process). The host waits up to 3 minutes for a debugger.

Logs

• context.Log(…) and anything your extension writes to the console go to%LOCALAPPDATA%\Nimblio\logs\extensions\<id>.log, and to the nbext dev terminal while you develop.
• In Nimblio, Downloads → … → Open log opens the file.
• Unhandled exceptions are written to the log with their stack trace. People see a short “The extension ran into a problem” error with your exception’s message.
• Run history shows each step’s log line and what you passed to context.Report.

If something doesn’t work

“Nimblio isn’t listening”

Open Nimblio and turn on Settings → Extensions → Developer mode. Nimblio and the tool must run as the same Windows user.

My action doesn’t appear

Check that the class is public, derives from NimblioAction<T> and has [NimblioAction]. Build errors starting with NBX come from the Nimblio build step and say what’s wrong.

A setting doesn’t appear

Only public properties with [Field] become settings.

“The extension stopped unexpectedly”

The host process crashed, often from a stack overflow or a native library. The log has the details. The next run starts it again.

Breakpoints stay hollow

Make sure VS Code attached to Nimblio.ExtensionHost.exe, not Nimblio.exe, and that you’re running a Debug build through nbext dev.