Tutorial: Debug a plug-in

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

• Tutorial: Write and register a plug-in
• Tutorial: Debug a plug-in (This tutorial)
• Tutorial: Update a plug-in

For detailed explanation of supporting concepts and technical details see:

• Use plug-ins to extend business processes
• Write a plug-in
• Register a plug-in
• Debug Plug-ins

Goal

Because the plug-in executes on a remote server, you cannot attach a debugger to the plug-in 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 on your local computer.

Prerequisites

• All the prerequisites for Tutorial: Write and register a plug-in apply. See Prerequisites. The exception is that Visual Studio 2019 or later is required to install and use Power Platform Tools.
• If you haven't completed the previous tutorial, you can use the general steps below with a different registered plug-in.

Install plug-in profiler

There are two tools available from which to run the Plug-in Profiler: the Plug-in Registration Tool and Power Platform Tools for Visual Studio. Instructions for the use of both tools are provided in this tutorial.

Plug-in Registration Tool

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.

   

Power Platform Tools

1. Follow the instructions in Install Power Platform Tools.

Following the steps provided above results in a new managed solution named Plug-in Profiler in your Microsoft Dataverse development environment.

Start profiling

Follow these steps to begin profiling a plug-in's execution.

Plug-in Registration Tool

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

   

2. When presented with the Profiler Settings dialog, accept the default settings and click OK to close the dialog.

   

Tip

For alternate information about running the profiler installed with the Plug-in Registration Tool see Run the plug-in profiler from a Command Prompt window.

Power Platform Tools

1. In Visual Studio select View > Power Platform Explorer to open the view if it is not already open.

2. Expand the Plug-in Assemblies node and then completely expand the BasicPlugin.FollowupPlugin assembly node.

3. Right click the step registration (the lowest level node) of the plug-in and choose Start Profiling.

4. When presented with the Profiler Settings dialog, accept the default settings and click OK to close the dialog.

   

Capture a profile

In your model-driven (or other) app, create a new account to execute the plug-in. This will capture an instance of the plug-in executing and persist it as a Plug-in Profile table row in Dataverse. You can see this row in Power Apps under Tables > Plug-in Profile by choosing Data.

Plug-in Registration Tool

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

   

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

3. 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.

   

Power Platform Tools

1. In Solution Explorer, right-click the plug-in class file in the plug-in library project and choose Debug.

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

3. 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.

   

Debug your plug-in

Follow these steps to debug your plug-in code.

Plug-in Registration Tool

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.

   

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

   

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

   

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

   

   Note

   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.

   

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

   

7. Step through your code to debug.

Power Platform Tools

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.

   

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

   

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

   

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

   

5. Step through your code to debug.

Stop profiling

Follow these steps to stop profiling the plug-in's execution.

Plug-in Registration Tool

1. Close the Replay Plug-in Execution dialog

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

   

Power Platform Tools

1. Close the Replay Plug-in Execution dialog

2. In the Power Platform Explorer view, right-click the step registration node (lowest level node) of the plug-in assembly and choose 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

Plug-in Registration Tool

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.

Power Platform Tools

The Plug-in Profiler is not available as a command line tool from Power Platform Tools for Visual Studio.