Debug Plug-ins

Article
02/24/2023

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 topic coverts the steps in bold above and supports the following tutorials:

Test your assembly

The simplest way to test your assembly may simply be to manually perform the operation using the app. But you should also be aware 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 may 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 will always be there.

You may want to write a program that will automate performing the operations that will cause your plug-in to fire and include a number of possible variations.

If you want to use a test automation framework, you will find that the community has created some tools for this. 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 will 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 will be 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 plug-in that will format the returned JSON. Or you may want to use an API client like Postman or Insomnia, or you may want to use VS Code with PowerShell.

You may prefer to use the XrmToolbox Plugin Trace Viewer. This community tool is not 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 will be 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 re-play 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 have installed 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 will open the Plugin Profile dialog