Thursday, April 2, 2015

Debugging Dynamics CRM for Outlook

I had a recent adventure with a Kendo UI project that took me into the recesses of a place I have very skillfully avoided for 7 lucky years: debugging JavaScript in the CRM for Outlook client.  The problem jumped out at me at the worst possible moment: Go Live.  Apparently the testers hadn’t thought to use the Outlook client, even though a majority of users would.  I number myself among them.

This lead me to discover a quaint little bug in the CRM for Outlook client: when you use JQuery to attach to multiple mouse events (“mousedown”, “mouseup”, and “click”) in an HTML Web Resource, only the first one in the event sequence gets its handlers fired.  The rest of the sequence does not complete.

“Wait, what?”  That’s what I said, too.  I’m going to recount the tale here, in case anyone else runs into this bug, but I will return to the process of debugging JavaScript in Outlook.

So, it works like this: when you click on a mouse button, there are 3 distinct events sent through the browser’s runtime, in order:

  1. mousedown  “The button is pressed down.”
  2. mouseup  “The button has been released.”
  3. click  “The button was pressed and released.”

The way this bug manifests, is when more than one of those events is being watched—at least by jQuery, anyway.  (I haven’t taken the time to see if browser-native event handlers are not affected in this way.)  By attaching a handler to both the “mousedown” and “click” events, we expect that a click will trigger that handler twice. 

It does; in every other browser, but not within the Outlook client.  This is actually incredibly easy to test:

<script type="text/javascript" src=""></script>
<script type="text/javascript">
$("#clickable").on("mousedown", function() { alert("Mouse is down.");});
$("#clickable").on("mouseup", function() { alert("Mouse is up.");});
$("#clickable").on("click", function() { alert("Mouse was clicked.");});
<span id="clickable">Click on me to see the event pipeline.</span>

This means that developers may need to find creative solutions to enable or support richer HTML interfaces from within Outlook.  Thankfully, the client-side context has a helpful getClient() method.

With that behind us…

So, the process of debugging Dynamics CRM for Outlook hasn’t changed the whole time I’ve been avoiding it, and the process is actually very simple: you debug with Visual Studio.

First, allow Visual Studio to do the dirty work by deselecting “Disable script debugging (Other)” from the Outlook machine’s Internet Options.


Then, launch Outlook and Visual Studio.  Do not attach to Outlook’s main process.  Find the page you want to debug, and attach Visual Studio to the instance of Microsoft.Crm.Application.Outlook.WebFormsHost.exe matching the page you’re viewing.  Each new window gets its own host process, so look carefully.


After that, you should be able to summon the debugger with a simple “debugger;” statement.  What you’ll probably miss most, like I did, is a nice JavaScript console, and a DOM Explorer, like those found in the debugging tools of most browsers.

Then, when you make changes to your HTML or JavaScript, you’ll run into CRM for Outlook’s quirky, bi-layered cache.  The steps to clear the cache are as follows:

  1. Launch Internet Options from the Control Panel.  You cannot rely on the Internet Options launched from Internet Explorer’s menu—it doesn’t reach into the client’s cache, which I speculate is maintained in a phantom profile.
  2. Delete browsing history:
  3. Launch the Diagnostics utility, which was installed with the CRM for Outlook connector.  It can be found in the Start Menu.  Repair your installation if you cannot find it.
  4. Under “Advanced Troubleshooting”, click to “Delete Temporary Microsoft Dynamics CRM Client Files”.

For JavaScript changes, this is enough—simply hit F5 and the page will reload with your changes.  For HTML resources, you will first need to close all CRM windows displaying the page, and then use the process above.

That’s really all there is to it.  I decided to write it all up here, because this information wasn’t easy to come by, and involved some trial and error.  Hope it helps!