xRM Portals Community Edition Now Available!

With the news on last Friday of the Microsoft Open Source Portals for Dynamics 365 becoming available, Adoxio has now launched their fork of that code as xRM Portals Community Edition. There is a lot to explore with this release of the open source portals and the xRM Portals Community Edition, what does it include, who is it best suited for, what are the long term goals, what are the gaps and how you can get your hands on it.

Let’s start with what the open source release includes and what is in xRM Portals Community Edition.

Open Source Portals, available on the Microsoft Download Center:

  • Microsoft Dynamics 365 Portals Solutions
  • Microsoft Dynamics 365 Portals Source
  • Self-hosted Installation Guide for Portals

xRM Portals Community Edition takes the components of the open source portals that are licensed under MIT, which is only the portals source, and made it available as a project on GitHub for the community, be it partners or individual developers to contribute, extend and fix issues in an easy and open fashion. Adoxio has decided to help facilitate this as the original portal experts for Dynamics 365/CRM, with the major goal of the project being to help provide a way for existing customers of legacy versions of Adxstudio a way to upgrade and move to online portals from Microsoft.

Note that the solutions still need to be downloaded directly from Microsoft on the download center as they are not licensed under MIT and are only provided as managed solutions. This does have an impact in limiting certain aspects of the project in terms of the communities ability to make fixes beyond the portals source code. With the history and experience of being a developer implementing portals I can tell you this isn’t a blocker that is going to prevent changes that maybe necessary, it will just involve some creative problem solving and possible re-engineering of certain components. Again this might not always be necessary to re-engineer components until a layering approach is not a support scenario for the necessary modifications or fixes required.

It is important to realize that with this release of open source portals there are some major caveats and gaps that certain use cases of the portals may cause issues for upgrades.

  • Problem: This is a one time only release by Microsoft
    Solution: xRM Portals Community Edition is maintained by partners like Adoxio as well other community members allowing for bug fixes and a maintained version of the open source release.
  • Problem: Not supported directly by Microsoft.
    Solution: xRM Portals Community Edition is supported by partners like Adoxio and updates will be provided for free by the community. Adoxio offers a number of different support options as well as the project is open to other Dynamics partners to contribute and provide their own support options.
  • Problem: Does not include all Adxstudio Portals solutions/portals like Event Management, Retail and 311/Government Service Requests
    Potential Solution: Partners will be offering comparable solutions that are compatible with the online version of portals or even compatible with open source portals for on premise.

The gap in the CRM solutions cannot be understated. If you are an Adxstudio Portals customer currently using Event Management, Retail Portal components like shopping cart or payment, as well as any component of the 311/Government Portal service request functionality then you will need to consider your future upgrade path. These solutions or starter portals are not available as part of Dynamics 365 portals or the open source portals release so there is currently no supported path forward for these scenarios without looking at additional partner based solutions.

With xRM Portals Community Edition everyone now has the capability to build this functionality right into their own custom version of the portal as well or whatever other customizations they deem necessary for their requirements. Even old Adxstudio functionality that isn’t actively turned on in the online product still remains in the code base and likely could be activated once properly validated and updated as necessary. You will notice that the commerce, and areas like Service311 remain in the code base and do compile but are missing their dependent schema due to not all legacy solutions being maintained.

Any change or investigation into functionality that is not already activated though should be met with caution as it is an investment and something that will need to be self maintained by the customer and/or partner as a result. xRM Portals Community Edition will be kept in a supportable fashion so extensions that cause significant modifications will be done external from the core project as to not disrupt the supportability of using the code base as an upgrade path. This does not prevent an extension library type approach that so many of Adxstudio Portals partners have taken over the years and hugely familiar to them.

Who is it for?

Now aware of the caveats and gaps we can more closely understand who this release and xRM Portals Community Edition is targeted at. First and foremost it is for those legacy Adxstudio customers that need an upgrade path to online portals from Microsoft. Up until now the only approach has been to re-implement all of the functionality manually. If you used a legacy Adxstudio portals starter portal that is still included in the Microsoft Dynamics 365 portal (Community, Partner, Customer, Basic/Starter) then the scripts and solutions included in the release will allow you to start testing that upgrade process. Further documentation on this upgrade process should be forthcoming in the next few weeks as well.

The other most popular use case of xRM Portals Community Edition is the use for those customers staying with on premises Dynamics instances. xRM Portals Community Edition contains the capability to support both Server-to-Server authentication (suggested for online instances) and the old connection string with a service account based authentication (used for on premises instances). Also because you have access to the source code, you can deploy it anywhere. This allows on premises customers to build and host their own portal while connecting to their on premises servers.

Finally those looking to pull out certain functionality or are interested in continuing to build a custom developed portal for specific business use can utilize a fork of xRM Portals Community Edition as a starting point for their development. It is a great way to kick start your project and just requires you to follow the MIT license requirements. This is also a way for previous Adxstudio Portals ISVs to continue maintaining their components as closely as possible to how they operate today with legacy Adxstudio Portals and their customers to get new enhanced functionality.

A word of caution to all. Online portals are the future of portals from Microsoft. While xRM Portals Community Edition will be maintained by Adoxio and has the potential to be community driven it will not have the backing or insights of the Microsoft Dynamics product group. If you are considering a long term portal solution and want to have the support of Microsoft for issues/fixes as well as new features and enhancements then you strongly need to look at online solutions. xRM Portals Community Edition is for those upgrading and those understanding of the investments they are making in an open source solution. This not to say xRM Portals Community Edition is not a viable solution just to be aware of the gaps, caveats and limitations of it.

What does the future hold for open source portals?

Many ask why Microsoft has made this release, how in earth could they give away the source for something they purchased and are continuing to iterate on. There are a number of reasons in terms of providing an upgrade path, providing support and an option to on premises customers, allowing legacy ADX ISVs a way to maintain their customizations, and provide a custom code solution for those that demand the capability to implement functionality that requires server code access.

There are major changes ahead for the online portals product after this release. If you look at the code base (MasterPortal) as well as the core Adxstudio library (Adxstudio.Xrm) there are major dependencies to libraries that Microsoft has since deprecated. Both Microsoft.Xrm.Portals as well as Microsoft.Xrm.Client are foundation libraries that the portal relies on for all of its operations. With the deprecated libraries it is very likely that the first modification Microsoft is making to their new branch of the portals code will be to remove the dependencies on these libraries and potentially others. There are major additions as well as improvements in areas like entity permissions and caching the team at Microsoft probably also wants to make to help bring new experiences and a more reliable product to end users. This release marks a point in time where it still follows the old Adxstudio structure and model which may significantly be changing for future releases. Perhaps even a move to ASP.NET Core with .NET Standard lies in the future if you are looking far out (Dynamics/CRM SDK is only around 75% compatible currently with .NET Standard so a little ways to go, and has major dependencies to non .NET Standard based libraries).

The same changes can be made to xRM Portals Community Edition or a future branch of it, to keep it in step with the online Microsoft version of the product. This is no small undertaking though in terms of effort, and will need the backing of the community to do so. The release of the source leaves the power in the hands of the community to make those choices or completely different ones that serve their own use cases the best. Microsoft has really put the power of portals for Dynamics in our hands, shared all the knowledge, and functionality that was developed over many years and experiences at Adxstudio.

Looking to learn more or participate in the community edition?

Dynamics 365 portals: Administrative Wizard

With the release of the July 2017 update for Dynamics 365, comes v8.3 of Dynamics 365 portals. One of the new features of this release is the new administrative wizard which allows you to easily add an entity to the portal. This can really make the pace for development increase and removes the barrier to creating all the components necessary to properly surface Dynamics 365 data on your external portal. Below we will walk through what exactly the administrative wizard create for you and how you can access and use it yourself.

Firstly you need to decide what you want to expose on the portal. This could just be creating a new page and not associating any data other than just CMS content or other web templates. But the administrative wizards real power is that it also allows you to configure full entity interaction on the portal by it creating all the necessary components like entity list, entity form, web pages, and entity permissions. This could be an out of box entity or a custom entity you have created.

For our example we are going to use a custom entity Economic Development Sites. Whichever entity you decide to use you will want to ensure you configure the CRM forms and views that you will expose on the portal prior to starting the wizard.

To start the administrative wizard, in Dynamics 365 navigate to Portals, then with 8.3.x solutions installed you will have a new Administration section with a tile called Portal Management.

Within the Portal Management select Create Portal Content.

You should now be presented with a Create Portal Content dialog which will allow you to create a web page and optionally display an entity. At a minimum you need to fill in the Page Name field. This will auto populate the title and the partial URL with the same value as page name automatically. You can select the parent page you want to associate this new page to (it will default to the home page of the selected website), and change the default layout for the web page.

Optionally you can now enable an entity with this page in the portal by changing the “Display organization entity in the portal” to yes which will review some additional options. Namely you need to first select which entity you want to display, then the view(s) (which can be multiple), the form that will be used for details, edit, and create forms.

Creation can be turned on and off, as can anonymous access. If anonymous access is turned off you will need to select the contact relationship which will require your entity to have a reference/lookup to the contact entity.

Finally you can enable editing of a record as well as if the records should be filtered to only those owned by the user.

With all your options selected you can then click the create button and the wizard will go about creating all the portal data components for you. It will create multiple web pages (if you have enabled create, and edit), entity forms for each function (create, edit, details), an entity list to display all the records on the main web page, and finally an entity permission that allows the functions enabled to work.

On complete of the creation you will be navigated in the CRM to the newly created web page, which has your entity list linked and if you check the child pages will include the create, edit and details web pages with the appropriate entity forms associated to each.

The wizard also does have some error checking so if you were to try to create the same partial URL that already exists to the parent page it will prevent this.

The administrative wizard is a great way to quickly get the scaffolding for your entity on the portal even if the initial configuration isn’t your desired output. With all the portal data it quickly creates it can help cut down your time entering all the information manually and you can now easily go and further enhance each of the components.

Dynamics 365 portals: Upgrade to July 2017 Update (v8.3)

The July 2017 update for Dynamics 365 portals is now available for existing portal customers in the North American region and rolling out to other regions over the coming days and weeks. How can you get this update and all the new cool functionality that is in it is a little different from the previous releases.

When the Dynamics 365 portals came out, you had no control over the time in which your portal was upgraded. With the July 2017 update this changes somewhat. Portal code updates will still be managed and done automatically but now the Dynamics 365 solutions for the portal must be customer initiated.

To initiate your portal solution upgrade you need to navigate to the Dynamics 365 Administration Center where you can manage all the instances in your tenant. From the instance listing select the organization that has the portal already installed and select the edit icon beside solutions in the right hand pane.

Within the Manage Solutions listing for the organization if the upgrade has been made available you will see “Upgrade Available” beside your existing installed portal solution. Highlighting the solution will provide you the details of the upgrade and also allow you to initiate the upgrade process.

Upon selecting upgrade you will be prompted to select the terms and the installation will start.

This process can take some time depending on the portal upgrade you are doing. From my experience and those at Adoxio we have seen this range from 30 minutes to 4 hours. So ensure you plan an appropriate window for this maintenance as it could cause the portal service to be unresponsive at times due to the solution upgrade/install process with the Dynamics 365 instance. To monitor the installation you can just refresh the Manage Solutions or go into the Dynamics 365 instance and go the solutions listing and wait until all solutions show as version 8.3.x.

As in previous upgrades the portal code is fully managed and not currently customer driven. You can check your current portal version by navigating to https://[portaladdress].microsoftcrmportals.com/_services/about. If you do have an 8.3.x portal and signed as an administrator you will now also see a lot more details about your portal including a new admin tool for clearing the cache!

If you haven’t yet got the 8.3.x update then you can still subscribe to the early update functional outlined in Dynamics 365 portals: Early Upgrade Option – July 2017 Update.

Build an ASP.NET Core Web App with Adoxio Connect Framework

Microsoft’s ASP.NET team is going through a big transition period right now to an open source redesign of ASP.NET called ASP.NET Core. ASP.NET Core has major changes that are meant to try to make it more accessible to a larger set of developers as well as bringing it to many platforms with incredible performance improvements. If you’re a web developer building ASP.NET sites that connect to Dynamics 365 this will be an important platform to investigate and use in your solutions. In this post we will walk through a sample of a Dynamics 365 Web App that is built on ASP.NET Core and use the Server-to-Server authentication that Adoxio Connect Framework provides.

Previously we have built samples for a Console Application and a standard ASP.NET Web Application. What makes ASP.NET Core different is that is all the new versions of MVC, Web Api, OWIN and the entire framework being built on .NET Standard instead of the .NET Framework. The change of building ASP.NET Core by following .NET Standard is the single largest change and is what makes the framework now cross platform and able to run on Linux. As Dynamics developers we need to continue using the .NET Framework due to the dependencies the Dynamics 365 SDK has to use .NET Framework components. It is not unexpected though, removing .NET Framework is big change and will take considerable time to make a shift (v8.2 shows approximately 75% compatibility with .NET Standard). This however does not mean they we can’t use ASP.NET Core as Dynamics developers because ASP.NET Core can also be run on .Net Framework since it is .NET Standard compatible. This means you can use .NET Framework based libraries like the Dynamics 365 SDK or others like SharePoint, and even Adoxio Connect Framework.

So Why Use ASP.NET Core
Their are huge changes that are great for developers and builders to make use of. There are major benefits in terms of modularization of the request pipeline, dependency injection a core part of the platform, performance (a factor of 10 compared to ASP.NET 4.6), new MVC version, and open source! If you’re build a brand new web app then you should strong consider starting with ASP.NET Core.

As such let’s look at how you can use Adoxio Connect Framework with this version and understand some of the differences from the ASP.NET implementation.

Firstly let’s start by creating a new ASP.NET Core project. You can do this with the latest version of Visual Studio, 2017. Select from the ASP.NET Core Web Application (.NET Framework) template under Visual C# > Web area. It’s important you select the .NET Framework version so we can support the Dynamics 365 SDK, and select .NET Framework 4.6.1 which Adoxio Connect Framework requires.

Next select Web Application while ensuring that ASP.NET Core 1.1 is selected in the version drop down.

With the new web project just like the standard ASP.NET sample we want to include the necessary NuGet packages necessary to connect to Dynamics 365. As we are going to use a Server-to-Server based authentication we are going to use Adoxio Connect Framework to make that implementation easy in the application. Within the project, right click Dependencies in the Solution Explorer and select Manage NuGet Packages… Within the NuGet package manager, select Browse and search for “Adoxio”, then select and install the latest version of Adoxio.Dynamics.Connect.

Adoxio Connect Framework will also bring in the necessary dependencies when it installs including the Dynamics 365 SDK.

This is the only package to install with ASP.NET Core to get started, making it super simple to start. Now with all the dependencies installed to the project the next step is to ensure you have done the necessary setup for server-to-server authentication. This includes creating an Azure AD application with the appropriate API access, and creating an application user with a security role in CRM. To learn more about the server-to-server authentication setup follow the MSDN documentation. Follow the same steps for multi-tenant for building this single tenant web application, other than you don’t need to worry about creating a process to deploy the application user as it will be a one time process per Dynamics instance. Use Multi-Tenant Server-to-server authentication

Once your have your S2S settings created (you will need a Client Id, Client Secret, the instance or resource – your Dynamics instance URL, and Azure AD tenant ID) then we need to input them into the ASP.NET Core app settings. This differs from the standard ASP.NET application as that configuration was all XML based and heavily used the Configuration Manager. Both in ASP.NET Core are no more. Settings are now stored in JSON and are retrieved via dependency injection in the OWIN App Startup services configuration. First let’s put a structure to read in the appsettings.json file.

  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning"
  "AdoxioConnect": {
    "dynS2S": {
      "ClientId": "1d8925fd-8cbe-4f07-a83f-f59f7b111350",
      "ClientSecret": "ckrtN4TrckIAF1i5ccEcJw+C4/ESfcyjWGBRBI80a3A=",
      "Resource": "https://connectexampleinstance.crm.dynamics.com",
      "TenantId": "ae83bd39-7849-4089-3965-1e5749dc4dc2"

These are just sample values.

With the settings now input we need to have the ASP.NET Core application add them to its dependency injection pipeline so we can then use them when forming the CrmContext constructor so we have a context to communicate with Dynamics 365.

Open the Startup.cs class and navigate to the ConfigureServices method. In this method we are going to use the S2SAppSettings class that comes with Adoxio Connect Framework to register the settings in the appsettings.json as an object that can be accessed in the application.


We can use S2SAppSettings because the names we used in the appsettings.json match that class definition. This class object will now be available to the entire application through the platform based dependency injection. You can read more about the DI in ASP.NET Core here – Introduction to Dependency Injection in ASP.NET Core

With the settings now available we need to make a small extension class to support the DI in ASP.NET Core in Adoxio Connect Framework. Create a new folder called Extensions if you want, and then a new class which you can call CrmContextCore.cs. In this class we simply just want to add a new constructor to the CrmContext that is part of Adoxio Connect Framework which will allow it to read the S2SAppSettings through the dependency injection.

using Adoxio.Dynamics.Connect;
using Microsoft.Extensions.Options;

namespace Adoxio.Connect.WebCore.Extensions
    public class CrmContextCore : CrmContext
        public CrmContextCore(IOptions<S2SAppSettings> s2sAppSettingsOptions) : base(s2sAppSettingsOptions.Value)

Why didn’t we just add this to Adoxio Connect? It would require making a library for both ASP.NET Core and standard ASP.NET because of the IOptions dependency so we decided this was such a small simple change as well as a place to start building extensions to the framework in your own project that we would stick with a single library until there were more benefits.

All that is in this class is firstly it inherits and extends the CrmContext class and add a new constructor that reads the S2SAppSettings as an IOptions object that then calls the base constructor with the value of the S2SAppSettings object. If you wanted to use the Xrm Tooling, CrmServiceClient this would be a good class to make those changes as well. This CrmContextCore class is what we will next be adding to the ASP.NET Core application as a singleton so that it is also available to the whole application through dependency injection.

Back in Startup.cs under the ConfigureServices method we can now add our new class as that singleton object.


Why AddSingleton? You can read more about the different service types for adding objects to the pipeline here with Service Lifetimes and Registration Options, as well there is a good answer on StackOverflow depicting an example of all of them. The reason here is that we really only need 1 connection to the Dynamics 365 instance in the entire application and there is no need to recreate the object on every request. So with a singleton we get a single object created at the startup of the application which makes for great performance on every request.

The ConfigureServices method should now have 2 additional lines as below and that is all the configuration that is actually needed to use the Adoxio Connect Framework and have a context that will allow you to interact with the Dynamics 365 instance through that Server-to-Server connection.

public void ConfigureServices(IServiceCollection services)
    // Add framework services.


Now that the application is setup we can now start creating controllers and other functions in the application that can access these objects easily through the dependency injection. Let’s look at a simple controller that implements some simple SDK calls.

using Microsoft.AspNetCore.Mvc;
using WebApplication13.Extensions;

namespace WebApplication13.Controllers
    public class CrmSdkController : Controller
        private readonly CrmContextCore _crmContext;

        public CrmSdkController(CrmContextCore crmContext)
            _crmContext = crmContext;

        public IActionResult Index()
            return View();

The addition we make to our class to make use of our context is just simply adding a constructor to the class that calls to singleton object we added to the application and then stores it in a private object that is accessible throughout the class. ASP.NET Core’s dependency injection makes it all this easy.

Now you can build methods that use the context to call Dynamics 365 using your normal SDK calls. Below is the same method as both a MVC view and an API JSON return within the exact same controller which is all now combined in ASP.NET Core MVC.

public IActionResult Index()
    var contacts = _crmContext.ServiceContext.CreateQuery("contact").ToList();
    return View(model: string.Join(",", contacts.Select(a => a.GetAttributeValue<string>("fullname"))));

public IEnumerable<Entity> GetContacts()
    var contacts = _crmContext.ServiceContext.CreateQuery("contact").ToList();
    return contacts;

All of this new ASP.NET Core sample code is now part of the samples on the Adoxio Connect Framework GitHub repo.

Again if your starting a new web development project for Dynamics 365 definitely consider ASP.NET Core even though your still using .NET Framework. There is still significant benefit to mixing the 2 together.

If your interested to know more about the Adoxio Connect Framework and Dynamics 365 Server-to-Server authentication I will be giving a webinar with the Xrm Virtual User Group this Tuesday July 11th at 12pm EST / 9am PST.

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