Upgrading to xRM Portals Community Edition: Lessons Learned

General Process

Business Solutions MVP Colin Vermander wrote a great post on the steps to move from Adxstudio v7 to xRM Portals Community Edition. We used these steps as the basis for the upgrade.

At a high level, the process to upgrade includes:

1. Updating your Portals source code to the most recent version.
2. Using the PowerShell script to import the new Microsoft solutions, and to migrate your data to the new multi-lingual data model.

#2 should be pretty straight-forward; #1 could be easy, or very complicated, depending on how much you’ve customized the Portals code. I’m not going to rehash Colin’s post, but I will mention a few areas where we ran into challenges and provide you with our solutions.

Running the PowerShell Script

Once we had our environment configured properly, the PowerShell script ran just as described by Colin. Unfortunately, there were a few dependency issues we had to get sorted out first. Specifically, we needed to add the following libraries (available in the CRM SDK\Tools\PackageDeployer folder) to our Global Assembly Cache (GAC):

• Microsoft.Xrm.Tooling.PackageDeployment.CrmPackageExtentionBase.dll
• Microsoft.Xrm.Tooling.PackageDeployment.CrmPackageCore.dll
• Microsoft.Uii.Common.dll
• Microsoft.Xrm.Tooling.Dmt.DataMigCommon.dll
• Microsoft.Xrm.Tooling.Dmt.ImportProcessor.dll
• Microsoft.Xrm.Tooling.Dmt.MetadataHandler.dll
• Microsoft.Uii.CrmEntityManager.dll

Running a command like “gacutil -i Microsoft.Uii.CrmEntityManager.dll” in the Visual Studio Developer Command Prompt for each of the above libraries did the trick.

The only other note I’d make is that we needed to use the unique name when connecting in the script, instead of the regular URL.

Our Process for Updating the MasterPortal Project

Whenever we started a new project using Adxstudio Portals, we’d always make our first check-in into TFS the out-of-the-box MasterPortal project, with only the connection string updated. That way we could keep track of any and all changes to the project. Having that point of reference made our life easier when it came up upgrading to xRM Portals Community Edition.

We decided it was much easier to move our changes into the new MasterPortal project, as opposed to trying to merge into our existing project. So by looking at all of the changes that had been checked-in, we had a very good idea what we needed to do. For this particular project, we needed to move over some custom page templates, JavaScript, CSS, a custom header and footer, as well as a custom web service. A majority of the work easily involved copying files directly into the new project.

Third-party Assemblies with Common Dependencies

Once we had moved all of our code in, one of the first challenges we ran into was adding a few additional references that were required for integration with external services (including Moneris and Twilio). These libraries depended on some of the same assemblies as the MasterPortal project but, in some cases, different versions (either newer or older). This resulted in both run-time and compile-time errors. For example, we ran into issues with both System.IdentityModel.Tokens.Jwt, as well as Newtonsoft.Json. Since we didn’t really want to mess with the MasterPortal project, we used either of the assembly binding redirects, or chose an older version of the third-party libraries that used compatible versions of the dependent assemblies.

“Operation not supported” Errors

Since we had downloaded the source code for xRM Portals Community Edition from GitHub, we ran into some blocked assemblies in the DllImports folder:

• DocumentFormat.OpenXml.dll
• Microsoft.SharePoint.Client.dll
• Microsoft.SharePoint.Client.Runtime.dll
• Microsoft.WindowsAzure.ServiceRuntime.dll

To resolve these issues, simply right-click on the assembly in Windows Explorer and choose Properties. Then click the Unblock button near the bottom of the tab.

Local Login – Now Disabled by Default

If your project uses local authentication, and you haven’t explicitly configured the Authentication/Registration/LocalLoginEnabled Site Setting, you’ll want to do that. It seems like the default is now false in the new version, so if you want local authentication, create that Site Setting with a value of true.

Forcing SSL on Azure

If you are publishing your project to Azure Websites, by default the code will force SSL. While we would certainly recommend that you use SSL whenever possible, you can turn off this behavior with the following appSetting in your web.config file:

<add key="PortalRequireSsl" value="false" />

Uninstalling the Old Solutions

While Colin did briefly mention this in his post, once we got to the point where we wanted to uninstall the old Adxstudio solutions, I had forgotten about it.

We were able to successfully uninstall most of the solutions, but ran into an issue when trying to uninstall Adxstudio Portals Base. When trying to delete the solution via the CRM UI, it just spun forever. We then tried with the XrmToolBox Managed Solution Deletion Tool, and we received a cryptic error message: The size necessary to buffer the XML content exceeded the buffer quota.

We submitted a support ticket with Microsoft, and when they mentioned a possible plugin dependency, I remembered Colin’s note. The plugin used to notify the portal of changes to CRM data was causing dependency issues. The easy fix was to unregister that particular plugin (Adxstudio.Xrm.Plugins.WebNotificationPlugin). Once that plugin was gone, we were able to delete the rest of the solutions.

Cache Invalidation

The old method of cache invalidation – which relied on plugins – doesn’t work in the new version. I plan on looking into what the options are here, but at least for now, don’t forget about the Clear Cache button at http://portalurl/_services/about. Remember, you need to be logged on as an Portal administrator to see the button.

UPDATE: check out my blog post on cache invalidation for xRM Portals Community Edition project.