If you’ve done any work with Dynamics 365 Portals, you’ve probably run into the dreaded “We’re sorry but something went wrong” white screen of death. In this post I’ll share the tricks I’ve used to get more details about the error without contacting Microsoft support.

White Screen of Death

I’ll soon be releasing a series of blog posts on how Dynamics 365 Portals works with Virtual Entities (spoiler alert – pretty well!). More than once during my research I ran into the White Screen of Death, or a variation where an Entity List wouldn’t load, or certain features of an Entity Form wouldn’t act the way I’d expect. Essentially, any time the portal runs into a server-side error, this screen is displayed. The error screen provides no details on what the problem actually is, so in the past you were left with taking shots in the dark, or contacting Microsoft support to get more details. Neither of these options is desirable.

I thought to myself, “There must be a better way!”. And of course, the good news is I wouldn’t be writing this blog post if there wasn’t. The better news is that with the latest release of Dynamics 365 Portals (v8.4), we have even more options.

Option 1: Use the New v8.4 Features to Disable The Custom Error Screen or Save Application Logs to Azure Blog Storage

In the last couple weeks, Microsoft has started rolling out v8.4 of Portals, which includes two new features that help with the White Screen of Death:

1. You can disable custom error pages, so you can see more details about the error, including stack trace and exception message.
2. You can configure the portal to send application errors to an Azure Blob storage account.

Both of these are super helpful, and often will give you an indication as to what is going on. However, these new features are only available in v8.4 so, in the meantime if you haven’t upgraded, this won’t help. Also, sometimes error logs aren’t always enough; sometimes you need to be able to step through the code in the debugger in order to figure out what’s going on. That leads me to Option 2.

Option 2: xRM Portals Community Edition to the Rescue!

Last year, in order to appease on-premise customers (since the new version is online-only), Microsoft released the full source code for the Dynamics 365 Portals web application. Adoxio (the company spun out of Adxstudio, who originally built Portals) took this code, uploaded it to GitHub, and called it xRM Portals Community Edition.

For now, we can take this code, point it at our CRM, and run the web application locally to see what’s going on.

Three Easy Steps to Get Debugging

It’s actually pretty quick and easy to get started:

1. Download the latest version of xRM Portals Community Edition from GitHub.
2. Add your connection string for your Dynamics 365 instance to the web.config. For example, something like:

   <add name="Xrm" connectionString="ServiceUri=https://instancename.crm.dynamics.com; Username=user@instancename.onmicrosoft.com; Password=password;" />
   

3. Add a Website Binding record in Dynamics 365. If you’re using IIS Express (built into Visual Studio), create a Website Binding record where Name = MasterPortal, Website = [your website record], Site Name = MasterPortal, and Virtual Path = /.

If you build and run the project, it should connect to your existing Portal data, and you should have the ability to step through the code.

Why Did You Say “For Now”?

Microsoft has been adamant that the code release they provided was a one-time only thing. Therefore, there is an expiry date on this technique, we just don’t know what that date is. At some point, the version in the cloud will be different enough that the code won’t even work. It’s hard to say how soon that will be, but my guess is that we are months away from that. My testing was with the new v8.4 released just a couple weeks ago (the xRM Portals Community Edition is based on v8.3), and I didn’t run into any major show stoppers.

Hopefully with these techniques the white screen of death won’t be so terrifying.