Debugging Plugins

Debugging Plugins

Dataverse plug-ins run on the server, so you can't attach a debugger directly. The Plugin Profiler captures a plug-in's exact execution context; Dataverse PowerTools turns that capture into a unit test you debug in VS Code — set breakpoints, F5, step through — with the real server-side context, no live org needed.

On Windows, the whole loop is one-click inside VS Code. On macOS/Linux, capturing is done once in the Plugin Registration Tool (the capture tool is .NET Framework); everything after — download, replay, debug — works everywhere.

The plugin card's Debugging section (and the Command Palette) drives all of it.

1. Profile the next run (Windows — in VS Code)

Deploy your plug-in and register a step first (Build Package & Deploy). Then, in the plugin card's Debugging section, click Profile next run:

1. If the Plugin Profiler solution isn't installed yet, Dataverse PowerTools installs it for you (one-time, ~30s).
2. Pick the step to profile (skipped if there's only one).
3. When prompted, trigger the plug-in — do the action that fires it (create/update the record, run the action) in your app — then click Continue.
4. The captured executions are listed; pick the run you want (a plug-in that fired many times shows them all, newest first). It's downloaded into profiles/ and profiling is stopped automatically.

Under the hood this uses the profiler's own Install Profiler / Start Profiling over the extension's connection — no Plugin Registration Tool window, no separate sign-in, under both service-principal and interactive auth.

macOS / Linux

Capturing needs the .NET Framework profiler, so do it once in the Plugin Registration Tool (Install Profiler → Start Profiling → trigger the plug-in). Then use Download a run (below) here — that part is cross-platform.

2. Download a captured run (any OS)

Debugging → Download a run lists the captured Plug-in Profile rows in your environment (type · message · table · sync/async · time) and saves the ones you pick into profiles/. Use this to grab a run captured earlier, or on a non-Windows machine.

You can also just drop a profile file exported from PRT (View Plug-in Profile → download) into profiles/.

3. Replay and debug (any OS)

1. Set breakpoints in your plug-in's Execute / ExecuteDataversePlugin.
2. Debugging → Replay & debug. It generates a Replay_<Class>_<timestamp>.cs in your test project that deserializes the captured context and invokes your plug-in in-process with the profiler's replay services (the plugin type is read from the profile automatically). If no profile is in profiles/, it offers a file picker.
3. Debug that test from the Test Explorer (or dotnet test). Your breakpoints hit with the exact server-side context that was captured — no live org needed.

Requirements: a plugin test project (run Setup Plugin Unit Testing if you don't have one) and Windows for the test host (the profiler replay assemblies target .NET Framework — the same constraint PRT has).

How it works

Capturing requires the profiler to be pipeline-executable, which only happens through the profiler's EnablePlugin API (what PRT's Start Profiling calls) — raw Web-API step edits don't make it fire. Dataverse PowerTools ships a tiny Windows-only helper that calls that API with your existing access token, so Profile next run needs no PRT GUI. The captured profile is stored as a mbs_pluginprofile row and replayed in-process by the same profiler library PRT uses.