Tutorial: Debug a plug-in


Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

This tutorial is the second in a series that will show you how to work with plug-ins.

For detailed explanation of supporting concepts and technical details see:


Because the plug-in executes on a remote server, you cannot attach a debugger to the process. The plug-in profiler captures a profile of an executing plug-in and allows you to re-play the execution of the plug-in using Visual Studio locally.


Install plug-in profiler

  1. If the Plug-in registration tool isn't already installed and open, follow the steps in Tutorial: Write and register a plug-in to open it. Complete the Connect using the Plug-in Registration tool section.

  2. In the Plugin Registration tool, click Install Profiler.

    Install Profiler

  3. This will install a new managed solution named Plug-in Profiler in your Microsoft Dataverse environment. This will take a minute or two to complete.

Start profiling

  1. In the Plugin Registration tool, select the (Step) BasicPlugin.FollowupPlugin: Create of account step you registered earlier, and click Start Profiling.

    Start profiling

  2. In the Profiler Settings dialog accept the default settings and click OK to close the dialog.


Form more information about running the profiler see Run the plug-in profiler from a Command Prompt window.

Capture a profile

  1. In your model-driven app, create a new account to trigger the plug-in. This will capture an instance of the plug-in executing and persist it as a profile record in the system.

  2. In the Plug-in Registration tool, click Debug.

    Click Debug

  3. In the Replay Plug-in Execution dialog, on the Setup tab, click the Select profile command icon to open the Select Profile from CRM dialog.

  4. In the Select Profile from CRM dialog, select the profile where Type Name equals BasicPlugin.FollowupPlugin and represents the profile captured when you last triggered the plug-in.

    Select Profile from CRM dialog

Debug your plug-in

  1. In the Replay Plug-in Execution dialog, on the Setup tab, in the Specify Assembly section, click the ellipses (…) button and choose the location of your BasicPlugin.dll.

    Replay plug-in execution

  2. In your Visual studio project, set a break point in your plug-in class.

    Set a break point

  3. In your Visual Studio project, select Debug > Attach to Process….

    Attach to process command

  4. Select the PluginRegistration.exe process and click Attach.

    Attach to process dialog


    You should see that the Plug-in Registration tool is now running in debug mode.

  5. In the Replay Plug-in Execution dialog, click Start Execution.

    Start Execution

  6. In your Visual Studio project, you should see that the code is paused at the breakpoint you set earlier.

    Breakpoint hit

  7. You can now step through your code to debug.


To repeat, in your Visual Studio project select Debug > Reattach to process and in the Replay Plug-in Execution dialog click Start Execution again.

Stop profiling

  1. Close the Replay Plug-in Execution dialog

  2. In the Plug-in Registration tool, click Stop Profiling.

    Stop profiling

Next steps

To learn more about common things you will do with plug-ins, continue to Tutorial: Update a plug-in

If you will not continue to the next tutorial you should unregister the BasicPlugin assembly you created in this step. See Unregister assembly, plug-in, and step for instructions.

Run the plug-in profiler from a Command Prompt window

While it is often preferable to run the profiler interactively from the Plug-in Registration tool, the profiler can be executed from a Command Prompt window independent of the tool. This is useful to obtain the plug-in profile log from a customer's Dynamics 365 apps server to debug a failed plug-in. A developer can then use that log to replay the plug-in's execution in the Plug-in Registration tool and debug the plug-in usingVisual Studio.

Procedure: Run the plug-in profiler from a command prompt

  1. Open a Command Prompt window and set the working directory to the folder where you downloaded the Plug-in Registration tool PluginRegistration.exe.
  2. Type this command to see the available run-time parameters: PluginProfiler.Debugger.exe /?.
  3. Review the supported parameter list and re-run the PluginProfiler.Debugger.exe program with the appropriate parameters.


Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).