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 then turns that capture into a unit test you debug in VS Code — set breakpoints, F5, step through — instead of attaching Visual Studio to the Plugin Registration Tool.

The flow has two halves: capture (done in the Plugin Registration Tool) and replay + debug (done here).

1. Capture a profile (Plugin Registration Tool)

Capturing has to be done in the Plugin Registration Tool (PRT). Its Install Profiler registers the profiler assembly into the plug-in pipeline in a way that can't be reproduced over the Web API, so this step is manual — but you only do it once per environment.

1. In PRT, connect to your environment and click Install Profiler (once per environment).
2. Select your registered step → Start Profiling → choose Persist to Entity → OK.
3. Trigger the plug-in — do the action that fires it (create/update the record, run the action, etc.).
4. The capture is saved as a Plug-in Profile row in Dataverse. (You can also Stop Profiling in PRT when you're done.)

2. Download or drop in the profile (VS Code)

In your plugin project's Debugging panel section (or the Command Palette):

• Download profiles — fetches the captured Plug-in Profile rows into a profiles/ folder in your project, or
• If you saved a profile file from PRT (its View Plug-in Profile → download), just drop it into profiles/ — or use Replay's file picker to point at it anywhere.

3. Replay and debug (VS Code)

1. Set breakpoints in your plug-in's Execute / ExecuteDataversePlugin.
2. Run Replay Plugin Profile as Unit Test (Debugging panel → Replay & debug, or the palette). It generates a Replay_<Class>_<timestamp>.cs in your test project that deserializes the captured context and invokes your plug-in in-process, and wires up the profiler's replay assemblies for you.
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).

Why not one-click capture?

Earlier builds tried to start profiling for you over the Web API. It turns out the profiler only becomes pipeline-executable when installed through PRT's Install Profiler, so an automated capture couldn't reliably produce profiles. Rather than ship something flaky, capture stays in PRT (where it's rock-solid) and Dataverse PowerTools focuses on the part that's genuinely better than PRT: debugging the captured profile right in VS Code.