Engineered Code is proud to announce the availability of ecLearn - the Learning Management System built on top of Microsoft Dataverse


Upgrading to xRM Portals Community Edition: Lessons Learned

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.

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.

8 responses to “Upgrading to xRM Portals Community Edition: Lessons Learned”

  1. […] a January blog post on upgrading to the xRM Portals Community Edition, I promised to look into automatic cache […]

  2. Ravi says:

    Hi, we tried cache invalidation. But our deployment is load balanced and the cache invalidation is happening in only one of the server. So the users connecting to the other server still facing the cache issue.

    We tried to configure based on the below URL. Once we update the web.config, we are getting “Adxstudio.Xrm.Services.RemoteEndpointOrganizationServiceCache is not valid” error.

    How can we handle cache invalidation for load balancing? Thanks .

    • Nicholas Hayduk says:

      Hi Ravi,

      The RemoteEndpointOrganizationServiceCache was removed in v8 of the portals, which is why you’re getting that error. What type of load balancing are you using? Is it multiple instances in Azure Web Apps, or some other technology? v8 now uses Adxstudio.Xrm.Services.PortalBusOrganizationServiceCache, which I believe invalidates the cache within Azure Web Apps, but if you’re doing something else, you may need to do a custom implementation to synchronize between the different servers.


  3. Senthil says:

    It is regarding Knowledge Base entity. Recently, we upgraded the portal from ADX v7 to XRM community edition. It seems portal doesn’t render any Knowledge Base articles now, when I browse /knowledge-base/.

    It actually renders a search field, but on search, it doesn’t render anything. We have few articles in CRM.

    Should I do any customization, in order to make it work?

    • Nicholas Hayduk says:


      v8 uses the new knowledgearticle entity (as opposed to the older kbarticle or knowledgebaserecord records, which v7 used). My best guess is that you don’t have any data in the knowledgearticle entity, which is why nothing is coming up. We’d recommend transitioning to the new entity if at all possible – reimplementing using the older entities would most likely not be trivial.


  4. Mike K. says:

    I’m using the xRM Portals Community Edition in a load-balanced environment (own servers, not Azure) and we’re having some cache refresh issues. I’ve read your other blog post on it ( which has been helpful, but I’m wondering if I need to do anything extra for a load balanced environment?

    As you say above, RemoteEndpointOrganizationServiceCache was removed in v8, so the steps in *may* no longer apply. Am I looking at a custom approach? It’s odd, as another customer has the same set-up, with no issues.

    Thank you for the blog posts 🙂

  5. Mike Kingscott says:

    Thanks for the link, I shall have a look – was also thinking of looking at the Adxstudio.Xrm.Services.PortalBusOrganizationServiceCache to see if I could munge/copy/duplicate the functionality.

    Thank you again.

Leave a Reply

Your email address will not be published. Required fields are marked *


Engineered Code is a web application development firm and Microsoft Partner specializing in web portals backed by Dynamics 365 & Power Platform. Led by a professional engineer, our team of technology experts are based in Regina, Saskatchewan, Canada.