I’m a big fan of unit testing your custom code to prevent errors from ever occuring in the system. However it is not unlikely that QA can still report an issue that is related to your custom code. You will have to ask QA for a replication log, the replication log should describe the specific steps they performed in order for you to replicate the behaviour.

Using the plug-in profiler we can easily step-through our custom code to determine exactly which line of code is causing the error.

What is the plug-in profiler

The plug-in profiler is a tool that profiles the execution of plug-ins and custom workflow activities for an enhanced debugging experience in Microsoft Visual Studio. The tool can be run from the Command Prompt window or from within the Plug-in Registration tool.

Using this tool you also have the ability to replay your plugin-in or custom workflow activity remotely (when disconnected from Dynamics). This is especially useful for ISV providers. They can ask the customer to profile the execution of failing code and you can easily replay this execution on your own system (offline).

Steps to profile the execution of failing code

As mentioned previously, you could use the command prompt (PluginProfiler.Debugger.exe) to profile the execution but I prefer to use the Plugin Registration Tool. Using the command prompt is out of scope of this blog post.

Installing the plug-in profiler

Open your Plugin Registration Tool and connect to a Dynamics organization. Next, install the Profiler solution in our organization (can be either on-premises or online). This can be done by a simple click on a button, “Install Profiler” found in the Plugin Registration Tool.

Install plug-in profiler

After the plug-in profiler is installed, you should find a new managed solution installed in your Dynamics system (check out Settings > Solutions to verify).

Next step depends on the type of custom-code you would like to debug. Is it a plug-in or a custom workflow activity? We will start to describe the steps to profile a custom workflow activity. Steps to profile a plugin, can be found right after.

Profile a Custom Workflow Activity

When you want to debug a custom workflow activity you have to find out which failing workflow calls your custom workflow activity. You can also create a new on-demand workflow that calls your custom workflow activity.

When you have found the workflow (or created a new one), we have to start profiling it. In the Plugin Registration Tool select the Plug-in Profiler and click Profile Workflow.

Profile Workflow

Next, select your workflow (in the drop down list) and check the specific step(s) of the workflow you would like to profile.

Configure the profile of a workflow activity

Select Exception as profile storage and include secure configuration and click OK. The profile configuration is now stored under plug-in profiler:

Workflow is profiled

The plugin registration tool has changed the workflow by appending “(Profiled)” to the name. You will have to make sure this workflow is a realtime workflow in order for the exception to popup. You can always convert your workflow to a realtime workflow.

Next, we have to trigger the execution of the workflow. A business process error should popup and you can click “Download Log File” to save the (compressed) profile.

Compressed profile message

Now we have gathered all the necessary information to start debugging our custom code. Next we have to replay the execution to step through our custom code (see replay execution).

When you would like to profile a plugin, the steps are a little different:

Profile a plugin

To profile a plugin, we have to select the specific plugin step that we would like to profile and click “Start Profiling”.

Start Profiling

Next, trigger the plugin and the following error should popup:

Compressed profile message

Download the log file and we are ready to replay the execution.

Replay the execution

Select debug in the plugin registration tool (or “replay plug-in execution” when offline).

Start debugging your custom workflow activity

Select the file containing your profile and your local (debug) assembly file. Before clicking on “Start Execution”, we have to attach Visual Studio to the Plugin Registration Tool.

Replay/debug plugin execution

In Visual Studio, select “Debug” and “Attach to Process…” (or CTRL + ALT + P). Select the PluginRegistration.exe process and click Attach.

Visual Studio: Attach to Process…


When attached to the plugin registration tool you can start to put breakpoints in your code (Visual Studio). After clicking “Start Execution” in the plugin registration tool, the Visual Studio debugger will popup and break at your specific breakpoint(s). This way you can step through your custom code and find the cause of your issue much faster.

Enjoy the power of the plugin profiler!


5 thoughts on “Debug your custom code (plug-ins & custom workflow activities) using the plug-in profiler”

  1. Hey, profiling a workflow has never worked for me since the inclusion of Plugin Profiler into the Dynamics world. It always throws one error or other. Am currently trying it on v9.0 org with the latest plugin registration tool and it throws this error when hitting that Ok button for profiling.

    Unhandled Exception: System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]: Unable to load plug-in assembly.

    1. Hi Piyush, I was able to replicate the issue in a vanilla Dynamics instance (v9.0.2.760) using the latest Plugin Registration Tool (v9.0.0.934). Unsure what could be the root cause, I have opened a support ticket to investigate. Will keep you posted if I get a response.

      1. Piyush, Microsoft confirmed me it is a known issue and it is being worked on… They couldn’t commit any date but it would be expected to take weeks. Will keep you posted anyway but for now there is no workaround unfortunately.

  2. Hi, I am trying to debug my custom workflow activity and somehow Visual Studio break point just doesn’t work. I am hoping Jonas can confirm this is still ongoing issue for Online clients? Thank you

Leave a Reply