Upgrade Adxstudio Portals v7.x to xRM Portals Community Edition

With Adxstudio Portals having an end of support date announced as August 2018, many existing Adxstudio customers are looking to see what their upgrade options are. One of the options to upgrade to the new Dynamics 365 portals from Microsoft is to utilize the Portals Source Code version or xRM Portals Community Edition as part of the upgrade path. Hidden within the PowerShell scripts for importing the Portal Source Code version is logic to actually upgrade your portal data and make it compatible with the new data formats in the release of the Portals Source Code. This allows you to maintain your existing implementation instead of having to completely re-implement it on the new version. Once you are at Portal Source Code (v8.3 portals) you can then move to online portals maintaining the implementation as well. To trigger this you need to be aware of 2 site settings that will need to be created for each web site. In this post we will look at going the first step of the upgrade process, from Adxstudio Portals v7 to Portal Source Code/xRM Portals Community Edition.

Firstly, run a backup of your instance and read over some caveats to be aware of.

  • This example will use the Basic/Start/Custom Portal template with a completely out of the box portal.
  • The upgrade process will not perfectly upgrade all your components. The upgrade process is focused around transforming data to work within the new data model. You will need to review your configurations to ensure they all function properly within the new version.
  • Custom branding will likely need to be redone
  • New portal data from the latest version will not be imported. So you will not get any new templates or configurations from the new version, but your existing data will be maintained. If you want new portal data and configurations you can install a fresh portal in a new instance and manually copy over data.
  • If multiple web sites are present all web sites must be upgraded at once and therefore all must have the 2 site settings
  • Code customizations need to be transported to the updated code base and tested for compatibility OR implemented using new out of box configuration based method. NOTE: all custom code must be removed or abstracted to a Dynamics Portal Companion App approach before upgrading to the online Dynamics 365 portals
  • If you are not using ASP.NET Identity in Adxstudio Portals this is a required change prior to removing the Adxstudio solutions as the schema for the old forms based authentication will be removed with them.

For this example I have a new Dynamics 365 instance, version 8.2.x with Adxstudio Portals v7.0.0025 installed using the Basic Portal starter template. Here are the solutions installed in the system currently:

To do the upgrade we are doing to use the package deployer packages that come with the solutions components (MicrosoftDynamics365PortalsSolutions.exe). You can download that item from the Microsoft Download Center.

Within these packages there is logic that looks at the following 2 site settings to determine if it will run the data transformation to resolve the data model changes, UpgradeWebsiteData and WebsiteLCIDforUpgrade to determine the language to apply to the site. Below is an example of the site setting values:

Name Value Example Value Description
UpgradeWebsiteData true Boolean value, default of false
WebsiteLCIDforUpgrade 1033 LCID Code for web site. Use one of 43 supported portal languages.

Once you have these site settings in, and remember if you have multiple sites you will want to have the settings in for all sites. You cannot upgrade one site and then upgrade another site later. The sites all share the same solutions which will be upgraded on the first site being done. We can then proceed with running the PowerShell script which will run one of the packages.

Open your PowerShell and navigate to the .\PackageDeployerPackages\ folder. Within that folder execute the import script, .\Import.ps1.

This will prompt you to select your connection type, on premises or online. Enter your full organization URL, ie. https://orgname.crm.dynamics.com, then enter your language LCID code. Then you will be prompted to select your package. You will want to select the starter portal you already have installed. Remember this package list and names differs a bit from the Adxstudio Installer website gallery list. Below is a map Adxstudio to Dynamics 365 portals.

Adxstudio Portals Website Gallery Templates Microsoft Dynamics 365 portals Templates
Basic Portal Starter/Custom Portal
Community Portal Community Portal
Company Portal Not Supported
Conference Portal Not Supported
Customer Portal Customer Self-Service Portal
Government Portal Not Supported
Partner Portal Partner Portal
Retail Portal Not Supported
Not Supported Employee Self-Service Portal

It is important to note that features in the portals have also changed. Community Portal with xRM Portals Community Edition and Dynamics 365 portals online no longer contains event management functionality. There will be other gaps such as this in other portals. Please ensure you validate using a portals comparison like available on adoxio.com or installing the latest portals in a clean instance.

Once you have selected your package the package deployer will start its process of importing solutions and then running the data transformation against the websites that return the site settings above.

When it is completed running you will be left with a combination of the Adxstudio solutions and the new Dynamics 365 portal ones from the Portals Source Code release. Here is an example of the combined solutions for the Basic/Starter/Custom Portal template.

You can now test the portal using the xRM Portals Community Edition code base against your instance and start to validate some of the custom configurations you put in place.

Once you have completed a quick validation the next step is to remove all the Adxstudio solutions based on their dependency tree usually last in is first out, so work your way down the list and delete each of them. Because the Dynamics 365 portals solutions are there the entities will remain in the system so none of your data should be removed either. Always best practice to be taking your backups at logical points of this process as well. With Dynamics 365 online this is a super easy process.

Note that if you have published web notification steps then you will need to unregister the SDK message steps where the event handler is “Adxstudio.Xrm.Plugins.Webnotifications”, otherwise you may run into issues removing some solutions.

Once you have removed all the Adxstudio solutions you should be left with just the Dynamics 365 ones. You can retest your functionality and move on to addressing any configuration and branding issues.

This process will have upgraded you to the Portal Source Code version solutions and you can utilize xRM Portals Community Edition has the code base for your portal and now deploy that to your web servers or to an Azure App Service. If you had any custom code that you need to continue to maintain then you should have moved it into this code base and made any necessary changes to continue its existing function.

Upgrading to Portal Source Code/xRM Portals Community Edition could be where you stop for now. When you are ready to go fully online you can continue with an upgrade to the online version of Dynamics 365 portals. In an upcoming post we will look at how you can do that upgrade from Portal Source Code version or xRM Portals Community Edition to the latest Microsoft Dynamics 365 portals online service.

If you have questions related to the upgrade please post a comments and I will try to include answers in future blog posts about the topic.

WEBINAR: Wondering what to do with your Adxstudio Portal?

Things are changing in the world of portals for Dynamics 365 or Dynamics CRM. The platform is advancing forward at a rapid pace with new portal options from Microsoft being released and older legacy versions needing to be evaluated for their longevity.

I am often asked to help organizations understand and select the option that is right for them as existing Adxstudio customers looking to be properly supported in the future, or new customers considering what Microsoft portal options are available to them. To help make this content available for everyone I will be giving a webinar with Adoxio Business Solutions on Tuesday, June 27th at 10:00am PST / 11:00am MST / 1:00pm EST.

I invite anyone interested in portals for Dynamics 365 to join. If you already have burning questions you would like answered I would be more than happy to try and answer them during the webinar. Please see the full invitation from Adoxio below and a link to register as well as submit your question prior to the webinar.

Register Now Submit a Question

Join Adoxio on Tuesday, June 27th at 11:00am MST / 1:00pm EST for a webinar that will outline considerations for the future of your Adxstudio Portal. There are a lot of changes in the near future for portals from Microsoft for Dynamics 365. The portal source code will be released, bringing with it another choice for implementations. What does the future potentially hold for the legacy Adxstudio portals? What choices do you have for on-premises deployments?

Get answers to these and more with Colin Vermander, Technical Director for Service Delivery at Adoxio. You will leave understanding what your options are as a current or future portal customer, and get key insights into what Adoxio is recommending.

By attending this webinar, you will learn:

  • Overview of Microsoft’s announcement & their plans to release the code
  • How this will affect you?
  • Solutions and your options moving forward

CRM SDK 6.1.2 Released – Fixes Adxstudio and Dynamics 365 Compatibility

Microsoft has released an update to the CRM 2013 SDK with a new version, 6.1.2. This version includes changes to support the new authentication protocols introduced in v8.1.1 of the SDK. Since the Adxstudio Portal v7 relied on the CRM 2013 SDK, without this new version of the SDK it was unable to connect to Dynamics 365 instances due to the deprecation of the Azure Access Control Service (ACS) endpoint from all v8.2 instances. Now with this new CRM SDK you can include it in Adxstudio Portals v7.x projects so they will be able to connect successfully to Dynamics 365!

The new CRM SDK v6.1.2 has been posted to Nuget – https://www.nuget.org/packages/Microsoft.CrmSdk.CoreAssemblies/6.1.2. This new DLL will likely be included in the next Adxstudio Portals v7 release but until then you can manually add it to your projects via either of the following methods:

BIN folder drop
Use this method if you have not customized the code and only deployed the out of box MasterPortal

  1. Download the updated CRM SDK v6.1.2 Nuget package from nuget.org
  2. Use WinRAR or 7Zip or other compression utility to open the Microsoft.CrmSdk.CoreAssemblies.6.1.2.nupkg file. Right click the file in Windows Explorer, select Open With… and select your desired ZIP compatible compression program. Alternatively, change the file extension to .zip.
  3. Extract the Microsoft.Xrm.Sdk.dll and Microsoft.Crm.Sdk.Proxy.dll from lib\net45 folder to a local folder location.
  4. Copy the Microsoft.Xrm.Sdk.dll and Microsoft.Crm.Sdk.Proxy.dll files to the MasterPortal\bin\ folder where your portal code is deployed, overwrite both the existing files when prompted.
    Note: When replaced this will cause the portal application to automatically be restarted.

Visual Studio – NuGet Package Manager
Use this method if you are customizing the MasterPortal project and need to recompile the MasterPortal with custom code or update your reference to a new DLL location.

  1. Open your MasterPortal Visual Studio Project. In the solution explorer pane, expand the MasterPortal, right click References and select Manage NuGet Packages…
  2. From the NuGet Manage Packages window, select Browse from the top instead of the default of installed and enter in the search “crmsdk”.
  3. From the results select “Microsoft,CrmSdk.CoreAssemblies” the package will be by crmsdk.
  4. In the right pane of the NuGet window use the version selector to select 6.1.2, and click Install.
  5. You will be prompted for a dependency to Microsoft.Identity, confirm the dialog and accept the terms to install the packages.
  6. Once completed you can rebuild the MasterPortal project and re-deploy your customized portal for Dynamics 365 compatibility.

One thing to be aware of with using NuGet Package Manager is that it can have the side effect of doubling up some of your dependent assemblies in the web.config. A base MasterPortal this was not an issue but something you may want to review your web.config after to ensure it doesn’t have any extra items that you do not need. Also if you use NuGet to add other packages to your project be cautious when updating to not include the Microsoft.CrmSdk.CoreAssemblies in any update.

Alternatively from NuGet you can use the BIN drop method as well with your Visual Studio project. Instead of dropping the updated assemblies in the BIN folder, instead drop them in your reference assembly folder, perhaps called Framework or DllImports. This would replace your existing DLLs in that reference folder.

The new CRM SDK 6.1.2 should also work with any previous versions of CRM, allowing you to pre-update your Adxstudio Portal projects prior to upgrading your CRM to Dynamics 365.

Why this was update necessary:

With the deprecation of Azure Access Control Service (ACS), we have to modify our SDK authentication code by removing all references to ACS. Effective from versions Microsoft Dynamics CRM Online 2016 Update 1 (v8.1.1) and Microsoft Dynamics 365 (v8.2), we removed Live ID support and ACS dependencies on the server-side.

We also removed Microsoft.Xrm.Client from the CRM 2016 (8.x) SDK client because it was not compliant with the OAuth changes, and replaced it with Microsoft.Xrm.Tooling.Connector. You can use the current Microsoft Dynamics 365 Software Development Kit (SDK) to access Microsoft Dynamics CRM back to version 6.x for both auth and messaging.


For some additional context you can read my previous post – Dynamics 365 and Adxstudio Portals Compatibility

Adxstudio Portals v7.0.0023 Released

A new version of Adxstudio Portals has just been released on the Adxstudio Community site. You can head over to download the latest version, 7.0.0023 here.

This version has a number of much needed fixes to bugs that were introduced in v7.0.0022. One in particular that was keeping a lot of implementations away from 7.0.0022 was the anonymous web forms bug. From the release notes posted they look to have addressed this and a number of other fixes.

Another major addition in this release is the web notifications can now be configured directly in CRM for what entities will cause a notification to the portal. The default in previous releases was all entities unless you manipulated this through the plugin registration tool. There is now a Web Notifications Entities that the web notification plugin will use to determine whether to send the message or not. This should be a huge boost to portal performance but now be-aware to add your new custom entities to this list if you want that data also invalidated on the portal. You can read more about this configuration here.

This release unfortunately does not fix the compatibility of Adxstudio v7 and Dynamics 365 but this new release is still very welcome with all the improvements and new cache invalidation functionality.

Update 12/1/2016: Andrew Chan from Adoxio –
Please be aware that a “settings.xml” file is packaged with the sample project under the App_Data folder. Please remove this file when you spin up a new project. Without doing so, this file will cause the Portals to try and connect to an already configured CRM organization that isn’t available, and it will ignore a CRM specified in the connection string in web.config.

Note: This post also appears on Adoxio Business Solutions Team Blog.

Dynamics 365 and Adxstudio Portals Compatibility

Update 2/1/2017:
Microsoft has release CRM SDK 6.1.2 which fixes compatibility between Adxstudio Portals v7 and Dynamics 365! Read more here.

With all the changes in Dynamics 365 there are updates in the SDK and service that now make Adxstudio Portal v7.x incompatible. Outlined below are some of the issues you may run into, with some temporary workarounds if you want use Dynamics 365, and the potential pitfalls of these current solutions.  As a result of the current status of support with Dynamics 365, it would be recommended that if you have an Adxstudio Portals v7.x implementation using CRM Online that you currently do not upgrade past CRM 2016 Update 1.

Update 12/27/2016:
It looks like a fix is going to be coming soon! Posted over at the Dynamics 365 Team Blog about SDK backwards compatibility a new CRM 2013 SDK version that supports the new authentication will be released as SDK v6.1.2. With this updated SDK version you would be able to swap the reference DLLs in Adxstudio Portals v7 without the negative impact to functionality that switching to v8.2 SDK has. No date was provided for this update, but we may also see v7.0.0024 released with this fix in the new year.

Dynamics 365 SDK Backwards Compatibility

One of the changes that is causing some issues is that the ACS endpoint is no longer being provisioned on online instances.  This started with some CRM 2016 Update 1 instances but now seems to be rolling out more broadly.  You might receive the following error when attempting to have your portal connect to the CRM.

ACS10002: An error occurred while processing the SOAP body. ACS50000: There was an error issuing a token. ACS50001: Relying party with identifier ‘https://instancename.crm.dynamics.com/’

Some instances of this could be resolved by changing the instance URL which would potentially cause the ACS endpoint to be rebuilt, but not always.  You could also log a ticket with Microsoft Support for them to restore the ACS endpoint to your instance.

Adxstudio Portals v7.x ships as a solution compatible with CRM 2013, 2015, and 2016.  As such it ships with the CRM 2013 SDK DLLs (v6.0 SDK).  With the release of Dynamics 365 and SDK v8.2 the CRM 2013 SDK DLLs are no longer compatible, and you actually need to upgrade to the v8.1 SDK DLLs to connect with a Dynamics 365 instance.  If you do try to connect Adxstudio Portals with its default CRM SDK 6.0 DLLs then you would likely see the following error message:

The Organization Service URL is invalid. Metadata contains a reference that cannot be resolved: 'https://instancename.crm.dynamics.com/XRMServices/2011/Organization.svc?wsdl=wsdl0'. There is an error in XML document (1, 1298). The maximum nametable character count quota (16384) has been exceeded while reading XML data. The nametable is a data structure used to store strings encountered during XML processing - long XML documents with non-repeating element names, attribute names and attribute values may trigger this quota. This quota may be increased by changing the MaxNameTableCharCount property on the XmlDictionaryReaderQuotas object used when creating the XML reader. Line 1, position 1298.

This can be solved by replacing both the Microsoft.Xrm.Sdk.dll and the Microsoft.Crm.Sdk.Proxy.dll with the versions from the v8.1 SDK, changing the MasterPortal project to .NET Framework 4.5.2 and adding the following dependent assembly references.

  <assemblyIdentity name="Microsoft.Xrm.Sdk" publicKeyToken="31bf3856ad364e35" culture="neutral"/>
  <bindingRedirect oldVersion="" newVersion=""/>
  <assemblyIdentity name="Microsoft.Crm.Sdk.Proxy" publicKeyToken="31bf3856ad364e35" culture="neutral"/>
  <bindingRedirect oldVersion="" newVersion=""/>

However while this will solve your connection issue it will come with unknown issues to other Adxstudio components like Entity List and the portals front-side editor. The change in SDK version does have impact on the portal functions due to the differences between SDK 6.0 (CRM 2013) and SDK 8.1 (CRM 2016 Update 1) and the dependencies the portal components have.

At this time it would probably be recommended if you have a Adxstudio Portals v7.x implementation using CRM Online that you do not upgrade past CRM 2016 Update 1. If you run into the ACS endpoint error explained above then open a support ticket with Microsoft Support and request that the ACS endpoint be restored. If you have already been upgraded, or want to use Dynamics 365 and still need Adxstudio Portals v7, then your best option is to do the DLL upgrade and try to work around the current issues with the reference change.

Note if you start a trial or demo with the intent on showing Adxstudio Portals you can change to a previous version with the following guide.

Microsoft has been notified and aware of the issue.  We are working with them to see what resolution options are available.  As more information on a potential update to resolve these issue becomes available from Microsoft I will update this post. Below is currently a running list of known issues using SDK 8.1 with Adxstudio Portals v7.0.0022, this is in no way a complete comprehensive list.

  • Entity List – grid configuration Edit action – will not appear on entity list rendering for Target Types ‘Web Page’ and ‘Url’, if using Target Type ‘Entity Form’ will result in error:
    Cannot create and populate list type Microsoft.Xrm.Sdk.KeyAttributeCollection. Path 'EditActionLink.EntityForm.KeyAttributes', line 1, position 2877.
  • Entity List – grid configuration Details action – will cause error if using Target Type ‘Entity Form’ as indicated above
  • Front-side editor – ‘Object reference not set to an instance of an object’ when Creating a new web page, or editing a page, or editing a snippet, or modifying a web link set.

If you discover other issues please let me know through comments, Twitter, email or however else and I will update this listing.

Note: This post also appears on Adoxio Business Solutions Team Blog.