Today's post was written by William Dibbern, Principal Developer at Sonoma Partners.
Anyone who has built a web resource for Dynamics CRM can tell you how frustrating it is without the right toolset.
Since all HTML, JavaScript, CSS, and images are stored in the database, they must all be uploaded through Dynamics CRM. Without a tool, you're left locating the web resource in a solution and using a web form to upload your changes. Try to use the built-in editor and you could risk formatting issues. All over GitHub and in the SDK you can find tools for helping to keep your local files in sync with CRM's copy by uploading them through the API. While that will certainly alleviate a lot of the pain, what if we could go further?
Let's do just that and take a look at a tool called Imposter.
What is Imposter?
Imposter is an extension to the widely popular Fiddler which allows you to serve up files from your local file system in response to requests from your browser.
The way Imposter works is that it hooks into Fiddler's API to see when the browser requests a web resource from the Dynamics CRM, and it uses some simple logic to figure out which file on your local system it should send in place of whatever the server has.
This has two advantages:
You can make changes in the editor of your choice (I'm really partial to Visual Studio Code, but that's a story for another day.) and see those changes reflected immediately in your browser without having to upload the file to CRM and publish every time you make a change.
You can make changes to the file and test them out without affecting anyone else accessing the system. Working on a rewrite of some JavaScript but need other developers to be able to keep working with the legacy code and only have one development environment? No problem anymore!
If you're familiar with Fiddler, you may be familiar with its AutoResponder functionality and therefore may be wondering what the advantage of Imposter is over this built-in functionality. Here are a few key points:
You have to setup a rule per file if you want to swap out, manually. If you're clever, you can do this with a regex to swap out a whole directory however, Imposter lets you skip the regex and map a local directory to a URL fragment so you can serve up an entire directory of files with only one setting.
Imposter comes with an implementation of "hot reloading" which means whenever you save changes to your code, the page is automatically refreshed to display the latest.
When you start using Imposter you'll also notice it has a concept of "profiles." Each profile is a combination of a base URL to look for (so that Imposter knows when to try to swap out files and when not to), a local directory (where Imposter will look for files that match those that were requested), and some overrides (for when your file system and CRM don't line up perfectly). With these profiles, we can support working on multiple projects at the same time. This looks a lot cleaner than a bunch of rules in AutoResponder.
How do I use Imposter?
Once you've got Fiddler and Imposter for Fiddler installed, you'll see a new icon in your menubar. If you click it, you'll see several options. Let's start with adding a profile first.
Adding a Profile
Click Imposter.
Click Profiles.
Click Add New.
Notice a setting dialog opens.
For Profile Name, we enter a friendly name for our profile. This name can be anything and is simply an identifier for you.
For Base URL, you'll want to enter a fragment of the URL that you're going to be asking Fiddler to keep an eye on to swap files for.
Since we're working in CRM, we can just enter /WebResources/publisherprefix_/ (where "publisherprefix" is the prefix you've chosen in your solution, by default "new") and what Imposter will do is wait for any request that contains /WebResources/publisherprefix_/ in the URL, and it will attempt to parse a file name from that string.
So let’s say your browser requests a webpage at https://crm.organization.com/WebResources/publisherprefix_/CustomSearch/index.html?data=awesome, Imposter will see the /WebResources/publisherprefix_/ segment of that URL and will start looking for a file in the CustomSearch folder called index.html. If found, Imposter will serve that file up in place of what the server has.
In the Local Directory field, you'll enter the base path on your file system that Fiddler should try to use to look for matching files. Continuing the example in the previous step, if you entered C:\MyVisualStudioSoltion\WebProject\, Imposter would look for html in C:\MyVisualStudioSolution\WebProject\CustomSearch\.
If you have any files that wouldn't match the pattern given in the previous step, like if you've been uploading your web resources as html instead of "namespacing" them like new_/index.html, then Overrides are where you go.
Tip: If you're unfamiliar with simulating directories with CRM Web Resources, you can read a basic introduction on that here. You can put in any URL fragment you'd like to match on (ex. index.html) and then past in the complete path to that file on your file system.
Click Save.
Enabling Imposter
Now that we've got a profile created, we can start things up.
From the File menu in Fiddler, ensure Capture Traffic is checked. Having this turned off is like hitting the circuit breaker, no extensions will work as no traffic will be captured.
From the Imposter menu, navigate to Profiles, then select your profile name, then click Enable. Note you can turn on as many profiles as you'd like.
Notice in the Imposter menu now that Enabled is checked. You can quickly turn on or off Imposter from this menu without losing the state of which of your profiles are enabled/disabled.
Clear your browser's cache and navigate to a web resource in CRM. You should see your local file system's changes being served up in the browser, and in Fiddler you'll see a blue highlight on web resources that were requested, matched, and replaced by Imposter.
Tip: Fiddler’s highlighter can be glitchy, so if you want to know for sure whether a file was swapped, add the X-Imposter response header to the results grid in Fiddler.
Auto Reload
I bet you noticed the Auto Reload option in the Imposter menu, didn't you? Wondering what that is? When Auto Reload is enabled, Imposter will monitor the Local Directory in any enabled profile(s) and wait for changes. If it detects a change, any HTML web resource that was already swapped out by Imposter will automatically refresh itself to account for the newest updates. Awesome, right?
I would recommend using caution with this feature, though. If you swap out an HTML web resource hosted in an iframe, any event handlers attached to functions in that iframe could be broken when it refreshes, making the utility a little less useful. For that reason, I primarily use this feature for dialogs and fully custom pages.
Where is it?
All this talking and no links to download? Well here ya go: Imposter for Fiddler on GitHub. The tool is hosted on GitHub, so if you'd like to submit a feature request or any other changes, feel free! There is also a Wiki on the GitHub repository which has some great tips and tricks for using Imposter. Enjoy!