Debug Plug-ins

2025-06-21

The process of writing, registering, and debugging a plug-in is:

Create a .NET Framework Class library project in Visual Studio
Add the Microsoft.CrmSdk.CoreAssemblies NuGet package to the project
Implement the IPlugin interface on classes that will be registered as steps.
Add your code to the Execute method required by the interface
1. Get references to services you need
2. Add your business logic
Sign & build the assembly
Test the assembly
1. Register the assembly in a test environment
2. Add your registered assembly and steps to an unmanaged solution
3. Test the behavior of the assembly
4. Verify expected trace logs are written
5. Debug the assembly as needed

Content in this article coverts the previous steps in bold and supports the following tutorials:

Test your assembly

The simplest way to test your assembly might be to manually perform the operation using the app. But you should also know that events that cause plug-ins to execute can be initiated in multiple ways, such as a table created from a workflow, or from the web services.

Execution context information might be different depending on how the action is performed. When writing your plug-in, make sure you practice defensive programming practices and don't assume that every value you expect is always there.

You might want to write a program that automates performing the operations that cause your plug-in to fire and include many possible variations.

If you want to use a test automation framework, you'll find that the community created some tools for automated testing. More information: Testing tools for server-side development

Use Tracing

As described in Tracing service, you can write messages to the PluginTraceLog Table within the code of your plug-in by using the ITracingService.Trace method.

Before you'll be able to use this service, you must enable tracing in your Microsoft Dataverse environment. The process is described in View trace logs.

Note

Trace logging takes up organization storage space especially when many traces and exceptions are generated. You should only turn trace logging on for debugging and troubleshooting, and turn it off after your investigation is completed.

While debugging, you can easily query the trace logs for a given plug-in class using the Web API in your browser. If your assembly is named BasicPlugin.FollowUpPlugin, you can use this query in your browser address field:

GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=startswith(typename,'BasicPlugin.FollowUpPlugin')

The JSON results are returned to your browser like so:

{
    "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
    "value": [{
        "messageblock": "FollowupPlugin: Creating the task activity.",
        "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
    }]
}

Tip

This works best if you install a browser extension that formats the returned JSON. Or you might want to use an API client like Postman or Insomnia, or you might want to use VS Code with PowerShell.

You might prefer to use the XrmToolbox Plugin Trace Viewer. This community tool isn't supported by Microsoft. If you have questions pertaining to this tool, contact the publisher.

Tracing messages can also be found in the log file that can be downloaded when a synchronous plug-in or custom workflow assembly throws an error that results in an error dialog that is displayed to the user. The user can select the Download Log File button to view the log containing details of the exception and the trace output.

For asynchronous registered plug-ins and workflow assemblies that return an exception, the tracing information is shown in the details area of the System Job form in the web application.

Note

If your custom code executes within a database transaction, and an exception occurs that causes a transaction rollback, all table data changes by your code are undone. However, the PluginTraceLog table records will remain after the rollback completes.

Use Plug-in profiler

Plug-in profiler is a solution that you can install on your environment that enables you to capture the execution context of a plug-in and then use that data to replay the event within Visual Studio while debugging.

You can find instructions to install and use Plug-in profiler in the Tutorial: Debug a plug-in. See Install plug-in profiler and Debug your plug-in

View Plug-in Profile data

After you install the Plug-in profiler and captured some profiles, you can view the event context and replay data that is used when you debug. Viewing this data can help you understand the execution context data that your plug-in can use.

You can view this data using the Plug-in Registration tool by selecting the View Plug-in Profile command. This opens the Plugin Profile dialog