Debug a plug-In

  • Article

 

Applies To: Dynamics CRM 2013

The following steps describe how to debug a plug-in executing on Microsoft Dynamics CRM 2013. To debug a plug-in that executes in the sandbox on Microsoft Dynamics CRM Online, you must using tracing as described later in this topic.

In This Topic

Debug a plug-in

Debug a sandboxed plug-in

Logging and tracing

Debug a plug-in

  1. Register and deploy the plug-in assembly.

    If there is another copy of the assembly at the same location and you cannot overwrite that copy because it is locked by Microsoft Dynamics CRM, you must restart the service process that was executing the plug-in. Refer to the table below for the correct service process. More information: Register and Deploy Plug-Ins

  2. Configure the debugger.

    Attach the debugger to the process on the Microsoft Dynamics CRM server that will run your plug-in. Refer to the following table to identify the process.

    Plug-in Registration Configuration

    Service Process

    online

    w3wp.exe

    offline

    Microsoft.Crm.Application.Hoster.exe

    asynchronous registered plug-ins (or custom workflow assemblies)

    CrmAsyncService.exe

    sandbox (isolation mode)

    Microsoft.Crm.Sandbox.WorkerProcess.exe

    If there are multiple processes running the same executable file, for example multiple w3wp.exe processes, attach the debugger to all instances of the running executable process. Next, set one or more breakpoints in your plug-in code.

  3. Test the plug-in.

    Run the Microsoft Dynamics CRM application, or other custom application that uses the SDK, and perform whatever action is required to cause the plug-in to execute. For example, if a plug-in is registered for an account creation event, create a new account.

  4. Debug your plug-in code.

    Make any needed changes to your code so that it performs as you want. If the code is changed, compile the code into an assembly and repeat steps 1 through 4 in this procedure as necessary. However, if you change the plug-in assembly’s major or minor version numbers, you must unregister the earlier version of the assembly and register the new version. More information: Register and Deploy Plug-Ins

  5. Register the plug-in in the database.

    After the edit/compile/deploy/test/debug cycle for your plug-in has been completed, unregister the (on-disk) plug-in assembly and then reregister the plug-in in the Microsoft Dynamics CRM database. More information: Register and Deploy Plug-Ins

Tip

It is possible to debug a database deployed plug-in. The compiled plug-in assembly's symbol file (.pdb) must be copied to the server's <crm-root>\Server\bin\assembly folder and Internet Information Services (IIS) must then be restarted. After debugging has been completed, you must remove the symbol file and reset IIS to prevent the process that was executing the plug-in from consuming additional memory.

For more information about debugging a plug-in using the Plug-in Profiler tool, see Analyze plug-in performance.

Debug a sandboxed plug-in

It is important to perform these steps before the first execution of a sandboxed plug-in. If the plug-in has already been executed, either change the code of the assembly, causing the hash of the assembly to change on the server, or restart the Microsoft Dynamics CRM Sandbox Processing Service on the sandbox server.

Configure the Server

The sandbox host process monitors the sandbox worker process which is executing the plug-in. The host process checks if the plug-in stops responding, if it is exceeding memory thresholds, and more. If the worker process doesn't respond for than 30 seconds, it will be shutdown. In order to debug a sandbox plug-in, you must disable this shutdown feature. To disable the shutdown feature, set the following registry key to 1 (DWORD):

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

Debug the Plug-in

Follow these steps to debug a sandboxed plug-in.

  1. Register the plug-in in the sandbox (isolation mode) and deploy it to the Microsoft Dynamics CRM server database.

  2. Copy the symbol file (.pdb) of the compiled plug-in assembly to the server\bin\assembly folder on the server running the sandbox worker process named Microsoft.Crm.Sandbox.WorkerProcess.exe. This is the server hosting the Sandbox Processing Service role.

  3. Follow the instructions in steps 2 through 4 presented at the beginning of this topic.

For more information about debugging a plug-in using the Plug-in Profiler tool, see Analyze plug-in performance.

Logging and tracing

An alternative method to debug a plug-in is to use tracing. Tracing assists developers in troubleshooting plug-ins by providing run-time plug-in information as an aid in diagnosing the cause of plug-in failure. Tracing is especially useful to debug Microsoft Dynamics CRM Online registered plug-ins as it is the only supported debugging method for that scenario.

The tracing discussed here is different from ASP.NET tracing. Tracing is implemented in the Microsoft Dynamics CRM SDK through the use of the tracing service ITracingService. Developers add Trace statements to their plug-in code, then build and deploy the plug-in. During execution and only when that plug-in passes an exception back to the platform at run-time, tracing information is displayed to the user. For a synchronous registered plug-in, the tracing information is displayed in a dialog box of the Microsoft Dynamics CRM web application. For an asynchronous registered plug-in, the tracing information is shown in the Details area of the System Job form in the web application. The amount and nature of this information is up to you as a developer to code into your plug-ins.

The main reason for implementing this type of tracing is to support the isolated (sandboxed) plug-in and custom workflow activities capability in Microsoft Dynamics CRM. Sandboxed custom code is not able to write information to the system event log or the file system. The tracing service was implemented to provide sandboxed plug-ins and custom workflow activities with a means to output run-time information when an exception is thrown. In addition, tracing is also supported in plug-ins that are not sandboxed.

An important design feature of tracing is that the tracing information is only made available when an exception is passed from the plug-in or custom workflow activity back to the platform. When the error dialog box is displayed in the web application, the user must click the Download Log File button to view the log containing exception and trace output. If an exception is not thrown or is caught by the plug-in/custom activity code, any tracing information generated by your custom code is lost.

An alternate approach is to create a custom entity to track any run-time plug-in information that you want to record. When your plug-in executes, have the plug-in store its exception information in a record of your custom entity. In this way, you are logging your run-time plug-in information to the Microsoft Dynamics CRM database. This method works for any plug-in regardless of how it is registered. However, if the plug-in executes within the database transaction and an exception occurs that causes a transaction rollback, any entity data changes by the plug-in will be undone.

For more information about how to use tracing in plug-in code, see Sample: Azure aware custom plug-in. For more information about platform (ASP.NET based) tracing, see Monitoring and troubleshooting Microsoft Dynamics CRM.

See Also

ITracingService
Plug-in development
Analyze plug-in performance
Register and Deploy Plug-Ins
Event execution pipeline
Write a plug-in
Plug-in isolation, trusts, and statistics