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.

The overall process

flowchart TD
    A[Build Package &amp; Deploy<br/>plug-in + registered step] --> B{Operating system?}
    B -->|Windows| C[Debugging → Profile next run<br/>installs profiler, starts capture]
    B -->|macOS / Linux| D[Plugin Registration Tool<br/>Install + Start Profiling]
    C --> E[Trigger the plug-in in your app<br/>create/update the record, run the action]
    D --> E
    E --> F[Pick the captured run<br/>saved into profiles/]
    F --> G[Set breakpoints in<br/>Execute / ExecuteDataversePlugin]
    G --> H[Debugging → Replay &amp; debug<br/>generates Replay_Class_timestamp.cs]
    H --> I[Debug the generated test<br/>from Test Explorer / dotnet test]
    I --> J([Breakpoints hit with the exact<br/>captured server-side context — no live org])

Loading

Three stages — profile (capture a real execution), download (bring the capture local), replay & debug (turn it into a test you step through). On Windows all three are one-click in VS Code; elsewhere only the capture step uses the Plugin Registration Tool. Each is detailed below.

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.