Today's guest blogger is BJ Dibbern, a Senior Developer at Sonoma Partners.
There are a bunch of scenarios where you might want to debug plug-ins in CRM 2011 where at first glance it may not seem feasible. Need to debug while others are debugging? Need to debug sandboxed plug-ins? Plug-ins for CRM Online? Plug-ins that are registered in a production environment? All of these scenarios have a valid solution, and one that is not that hard to achieve.
Enter the Plug-in Profiler. Long story short, it lets you debug plug-ins offline. While you may have heard of the Plug-in Profiler before, you may not have considered it for your situation. This may be because it’s not as readily advertised as the standard debugging process of un-sandboxed plug-ins in a local on-premise deployment. Hopefully this post will help you have a better understanding of why the Plug-in Profiler is a great tool, and how it may be able to help you in the future.
First things first, you need to ensure that you have the latest and greatest version of the Plug-in Registration Tool which is included in the Dynamics CRM 2011 SDK. You can grab the latest version of it here: http://www.microsoft.com/en-us/download/details.aspx?id=24004. If you have an older copy of the Plug-in Registration Tool, you may not be able to see the Plug-in Profiler as it was introduced in version 5.0.5 of the SDK. In the latest releases of the SDK, you should find the Plug-in Registration tool in the Bin folder of the SDK download.
I’m going to assume in this post that you are familiar with the Plug-in Registration Tool already and know how to connect to an environment. If not, please see this article for more information: Walkthrough: Register a Plug-in Using the Plug-in Registration Tool.
Now let’s follow through the few basic steps of debugging a plug-in with the Plug-in Profiler.
- Connect to your target environment.
- If you have not already, register a plug-in and step in the target CRM environment. Ensure that you keep a copy of the debug version of the plug-in assembly on the computer where you are running the tool – this is needed to use the Profiler.
- In the main toolbar of the Registration Tool, select Install Profiler. This will take a few minutes to complete as it installs a solution to your target environment. You can uninstall the solution at anytime without any worry.
Now we can enable profiling on a plug-in step. To do so, select a plug-in step (not a plug-in class) and click on the Profile button (highlighted below).
- In the dialog that presents, the defaults are fine for most use cases. Click OK.
- Back in CRM, perform an action that causes an exception to occur in the plug-in step you are profiling. You will be presented with a Business Process Error dialog box. Note the key difference here is that the exception is not immediately visible in the dialog. Instead the error detail actually contains the profile the tools uses to allow you to playback execution.
- Click the Download Log File button and save the details to your computer. This is the profile that the Profiler will use to allow you to playback execution.
- Open your Visual Studio solution and attach to debut the process named PluginRegistration.exe and set your desired break point in the code.
- Back in the Plug-in Registration Tool, click the Debug button, the below dialog will be presented.
- In the Step #1 box, browse to the file we downloaded in step 7.
- In the Step #2 box, browse to the location of the debug version of your plug-in assembly. The plug-in type (field labeled “Plug-in”) should default if you’ve selected the correct log. Note that if you get an error here stating it could not parse the organization service fault, that you probably don’t have profiling enabled correctly.
- Once you’re ready to debug, click the Start Plug-in Execution button on the dialog. This will allow you to step through your plug-in as you would normally when attached to the actual service.
Note that while it’s an awesome and powerful tool, the Profiler isn’t perfect. One thing to be aware of: errors with partial trust do not seem to be caught when attached to the profiler. You will need to debug those another way. You’ll notice that in playback of these types of issues, the profiler will throw an exception (generally on service calls) basically telling you that you’ve stepped through the execution past the point where the actual exception occurred.
Other than that one caveat however, the tool is excellent and I highly recommend checking it out.