Having gone through the entire process of upgrading a customer from Adxstudio v7 to xRM Portals Community Edition, I’d like to share what I’ve learned so that it might make your upgrade process a smoother experience.
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:
#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.
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):
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.
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.
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.
Since we had downloaded the source code for xRM Portals Community Edition from GitHub, we ran into some blocked assemblies in the DllImports folder:
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.
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.
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" />
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.
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.