Determine your Dynamics 365 portal data center

When you deploy a portal for Dynamics 365 you always want it located as close to your Dynamics 365 instance physically so that the latency for all communications between the portal and Dynamics 365 is as low as possible. With Microsoft managing the portal provisioning they take care of this for you. You still may want to determine the location for hosting of other services that will communicate with your portal, like when your looking at deploying a companion web app for your portal it would be ideal if it is the same data center as your portal.

You can quickly determine your major data center region just by looking at the address to your Dynamics 365 instance. The following link has a listing of all current major regions – Discover the URL for your organization using the Organization Service.  However within these major regions are regional data centers. For instance, https://*.crm.dynamics.com (North America which should actually be called USA/Mexico now since there is a region for Canada) has 3 different regional data centers and they are even creating secondary data centers regionally.  Within North America (or USA/Mexico) you could be in West US, Central US, East US, or even East US2.  Within CRM3 (Canada) you could be in Canada Central or Canada East as your primary data center. You can see all the Azure datacenter locations in the following link – Azure Datacenter locations.

Previous ways to determine your data center have involved spinning up an Azure VM and moving it through regions while doing latency tests.  You can also use a IP locator service to help you determine provided the IP address you testing has the proper location data registered with it (this sometimes can give false information as IP addresses can be re-routed to different regions).  Another way which the guys over at Peak Engagement blogged about is using the debug information page which reveals information about your Dynamics instance including the server name, database server, database name and much more.  If you look at patterns you may notice that the names of the servers are based on those regional data centers.

The Dynamics 365 portal has something similar but you can even use this technique on any Dynamics 365 portal without even being the owner of that site.  On every request response to the portal if you inspect the headers you will notice 2 additional response header keys added specifically for the Dynamics 365 portal, x-ms-portal-app and x-ms-request-id. The x-ms-request-id is just a unique GUID for each request, likely exposed to help assist with debugging. The x-ms-portal-app is a value for the site itself, it remains constant through all requests. Taking a look at the value found, there is the site GUID which is the GUID of the Azure Web App and then appended to that is a data center code.

You can easily get to this yourself without even being logged into the portal. The request headers are available on all requests. To look at this value open your browsers developer tools (F12), then select the network tab, open the details of any request and view the response headers. Below is a screenshot of Chrome’s developer tools highlighted with the navigation tips.

Below is a list of the data center region codes found on Dynamics 365 portals from the portals I have checked thus far.

  • EUw – West Europe
  • EUn – North Europe
  • USw – West US
  • GCv – US Government Cloud Virginia
  • GCi – US Government Cloud Iowa
  • USe2 – East US2
  • CAc – Canada Central
  • AUse – Australia Southeast

This is not an exhaustive list, if you come across others then feel free to drop a note in the comments.

You can now use this information to help you when picking a hosting location for a companion app as this region should be in same as your Dynamics 365 instance so you can attempt to get the best performance between applications and the backend Dynamics 365 instance.

Note there are instances where the Dynamics 365 instance and the portal will not be located in the same data center. This is not often the case but instances of this have seen that East US can host Dynamics 365 and East US2 can host the portal, this type of setup might also occur in other locations.

Building a Dynamics 365 ASP.NET Web App with Adoxio Connect Framework

The primary purpose behind the Adoxio Connect Framework was to help facilitate an easy server-to-server connection for a Web App. By using the Adoxio Connect Framework it helps by providing an implementation of OrganizationWebProxyClient and Active Directory Authentication Library so that you can easily interact through the Dynamics 365 SDK within your web application. This guide will walk you through starting an ASP.NET MVC and Web API project with the Adoxio Connect Framework to build your own forms, and APIs. If you’re looking to build a companion app to the Dynamics 365 portal or any CMS that can access a Dynamics instance and interact with it, then this is the guide to help you get that process started. This will also include the option of using the XRM Tooling API so you can utilize the CrmServiceClient extensions in your web application.

For this guide I am using Visual Studio 2017, but it should also be the same with Visual Studio 2015 provided you have the latest updates.

To start we need to create an an ASP.NET Web Application and this should be done using .NET Framework 4.6.1.

After creating, you should be prompted to select the template for the project. Here its up to the requirements you have and your preferred application templates, all templates are supported to implement the Connect Framework. For this guide I will be selecting the MVC template but also enabling Web API.

When you create a new ASP.NET Web Application depending on your template and references selected it will download a certain set of NuGet packages. Optionally you can update all the packages to the latest version. To update all the packages and install the additional NuGet packages I suggest using the Package Manager Console (View > Other Windows > Package Manager Console).

To update all packages run the following command in the Package Manager Console:

Update-Package

Next we need to install OWIN host for IIS (System.Web) as well OWIN for ASP.NET Identity. We are going to be using the OWIN framework to add the CrmContext object from the Adoxio Connect Framework so that it will make the context easily available from all controllers, API controllers, classes, and other application components.

Run the following 2 package install commands to get the necessary OWIN NuGet packages:

Install-Package Microsoft.Owin.Host.SystemWeb -Version 3.0.1
Install-Package Microsoft.AspNet.Identity.Owin

Finally we will run the install package command for the Adoxio Connect Framework which will also install the Dynamics 365 SDK.

Install-Package Adoxio.Dynamics.Connect

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

With the server-to-server settings created you will need to add the following settings to the web.config, completing the settings with your values (this are not working values only for sample purposes):

<appSettings>
  <add key="dyn:ClientId" value="1d8925fd-8cbe-4f07-a83f-f59f7b111350" />
  <add key="dyn:ClientSecret" value="ckrtN4TrckIAF1i5ccEcJw+C4/ESfcyjWGBRBI80a3A=" />
  <add key="dyn:Resource" value="https://connectexampleinstance.crm.dynamics.com" />
  <add key="dyn:TenantId" value="ae83bd39-7849-4089-3965-1e5749dc4dc2" />
</appSettings>

With these settings present you can use the default constructor of the CrmContext object, alternatively you can use the other constructors to have your settings loaded from another location like an Azure Key Vault. The Connect Framework also includes a setting manager if you want to save the application settings to a file on disk. The setting manager contains methods both to save and load the 4 application settings from a settings.json file in the App_Data folder.

However you choose to instantiate the CrmContext object we can use OWIN to make it easy to access this object throughout the application. By adding a OWIN Startup class to the application and loading the CrmContext into the OwinContext it becomes available everywhere in the application that the OwinContext can be accessed. To create an OWIN Startup class, right click in the solution explorer on your project name and select Add > OWIN Startup Class.

Within the startup class we want to ensure that the CrmContext object using the default constructor is going to load properly so there is a method in the SettingManager called InitAppSettings that will check it can properly load the settings first. This would allow you to insert other logic here if the settings don’t exist to potentially gather them from the user or throw/route the exception based on your desired application output. Below is a small sample of this check as well as if it succeeds how you can use the OWIN framework to register the CrmContext through dependency injection.

public void Configuration(IAppBuilder app)
{
    if (SettingManager.InitAppSettings())
    {
        app.CreatePerOwinContext<CrmContext>(CrmContext.Create);
    }
    else
    {
        throw new Exception("Adoxio Connect Framework app settings not found.");
    }
}

CreatePerOwinContext will register a callback of CrmContext.Create on the OwinContext and this callback called once per request so that you can access it easily throughout the application. To match the CrmContext constructors there are also CrmContext.Create methods to support you injecting server-to-server application settings easily in this callback format.

Once you have registered the CrmContext on the OwinContext you can easily access it in MVC controllers with the following code:

var context = Request.GetOwinContext().Get<CrmContext>();

For a Web API controller:

var context = HttpContext.Current.GetOwinContext().Get<CrmContext>();

Within both you will need to add using statements for Adoxio.Dynamics.Connect as well as Microsoft.AspNet.Identity.Owin. For the API controller to access HttpContext add a using statement for System.Web.

Both of these statements are using the Get method on the OwinContext, which is initiating the callback that was registered for type CrmContext and making the result available within your controller. Once you have this object returned it will already be set based on the logic within your OWIN startup class. If using the default constructor of CrmContext it will use the app settings to build the connection including the token so you can easily make requests using either the OrganizationWebProxyClient or an OrganizationServiceContext.

With this CrmContext now easily available you can now just build your ASP.NET Web Application as you would build any web application for your requirements. The CrmContext acts as your persistent application database context that is available on every request. To see a full MVC and API controller read examples check out the Git repo for Adoxio.Dynamics.Connect in the samples\Adoxio.Connect.WebApp folder.

Based on how you build applications with the Dynamics 365 SDK you may want to use the XRM Tooling API as well. You can easily add the CrmServiceClient as another type registered on the OwinContext or have this as your only type registered. The CrmServiceClient actual provides a constructor for OrganizationWebProxyClient and because the CrmContext object contains a property of this type it is very easy to use both together.

The rest of this guide is optional if you want to use the XRM Tooling API / CrmServiceClient Continue reading “Building a Dynamics 365 ASP.NET Web App with Adoxio Connect Framework”

What is Adoxio Connect Framework for Dynamics 365 the Technical Details

For those of you who are interested in utilizing the Adoxio Connect Framework for Dynamics 365 in your own projects, be that a console application, Azure Function App, or an ASP.NET web app then this post will help you understand why we built this framework and the settings that it exposes. The goal of the Adoxio Connect Framework is to make it easy to use the new Dynamics 365 Server-to-Server authentication and help build applications based on this authentication schema without having to take on the management overhead of authentication.

When looking at the history of the Dynamics platform and how you built applications for it, you always had to do some sort of impersonation or maintain a service account of some sort. You could utilize a non-interactive user if you wanted to try to avoid taking up a license but this had a number of limitations with it and you actually still needed a user license to initially set it up. With Dynamics 365, Microsoft launched Server-to-Server authentication, or often referred to as S2S auth, that removes the previous need of a user account.

Developers over the last number of years have already been very used to this Server-to-Server type of authentication schema in that it was client credential or certificate based authentication and not user credential based. What that means is you have either a client ID and client secret or use client certificates as your credentials, you don’t need a user license at any step of the process. This is actually the proper way to authenticate an application as a service, like a portal or a scheduled process. Many mistake the Dynamics 365 Server-to-Server authentication as only for use with multi-tenant applications, meaning 1 code base or 1 service that accesses many different tenants, like AppSource applications, when in fact it can be used in multi-tenant as well as single tenant scenarios.

A really good example of a single tenant scenario is a portal or web app, and this is how the Dynamics 365 portal itself (or CRM portal if your still on the initial Microsoft release) does its authentication with the Dynamics instance (they use a slightly different version but the concepts are the same). A portal or web app is an application that runs as a service on a server, the users accessing the application are often not Dynamics users, they are external to the organization and it needs to basically be always on.

At present the Xrm tooling API library with the CrmServerClient does not easily support or provide the easy constructs to create a server-to-server auth based client. This is really due to the Active Directory Authentication Library (ADAL) and how it works in certain versions. As a result you need to do a lot of the figuring out and management of the ADAL yourself and requires you to really understand the concepts at play.

The Adoxio Connect Framework is meant to fill that gap in the Xrm tooling API and make using Server-to-Server authentication super easy, especially in a web app. You don’t have to worry about tokens, how to get them, attach them, etc., you just plug-in some settings and construct the context. The framework is not limited to only a web app, you can easily plug it into console applications, Azure Function Apps or any other .NET based applications. It allows you to construct a S2S auth based context, which we have called CrmContext (yes CRM, it is still CrmServiceClient 🙂 ) with a couple of settings and then you can utilize that context in various ways. CrmContext implements OrganizationWebProxyClient and then uses ADAL to get an Oauth bearer token and will attach it to the web proxy client. It figures out the hard bits for you, all you as a developer need to worry about is then using that context. To help make using it even easier the CrmContext also has an OrganizationServiceContext so that you can start using the Linq provider right away as well.

Part of making that easy is making sure you just have to add a couple of settings to the application. Those use to Adxstudio Portals development will know entering a connection string that consisted of an instance or organization URL, username and password. The Adoxio Connect Framework isn’t much different, it requires a resource (instance URL), client ID, client secret and the Azure AD tenant identifier. All of these can be stored in 2 different ways currently, either as appSettings in an application or web configuration file or as a settings.json. The framework contains a SettingManager to help assist with loading, validating and even saving the settings to they can persist through application restarts if you aren’t using a configuration file. Below is some example settings (they don’t actually work) of how you would put it in a configuration file.

<appSettings>
  <add key="dyn:SdkClientVersion" value="8.2" />
  <add key="dyn:ClientId" value="1d8925fd-8cbe-4f07-a83f-f59f7b111350" />
  <add key="dyn:ClientSecret" value="ckrtN4TrckIAF1i5ccEcJw+C4/ESfcyjWGBRBI80a3A=" />
  <add key="dyn:Resource" value="https://connectexampleinstance.crm.dynamics.com" />
  <add key="dyn:TenantId" value="ae83bd39-7849-4089-3965-1e5749dc4dc2" />
</appSettings>

You’ll also notice dyn:SdkClientVersion in that list. This one is optional, if you want to override the version of the SDK being used on the service endpoint and we haven’t updated the library to that version yet you can make that override yourself. If you don’t include the setting it will currently default to 8.2. The setting allows you to change the version in the following service endpoint URI:

{dyn:Resource}/xrmservices/2011/organization.svc/web?SdkClientVersion={dyn:SdkClientVersion}

At this point you might be asking how do I get a client ID and client secret and where the heck do I get my tenant ID from. This process could be a blog post of its own, which a couple of others have already done, as well as there is MSDN documentation on the process so I am going to refer you to them for the time being (let me know in the comments if you want to see this as a post).

The short is, you need to create an Azure AD application (so you’re going to need to be or need to get your Azure AD admin to assist you), this will giving you a client ID. Once you have an application you can define a client secret for it, and then assign the application permission to the Dynamics Online service. Within Azure AD you can also find your tenant ID. Once you have those you need to then create an Application User in Dynamics and assign it a non-default (not an out of box security role). Don’t copy the System Administrator role, for your sake and everyone’s create a proper security role restricted to the entities the service application actually needs. You will then need to consent or authorize the application. Once you have that process complete, your set, it never has to be done again for that organization instance.

It gets really simple now, you have either your appSettings defined or you have defined your own process to use the Save function in the SettingsManager to write a settings.json. You can now just use the default constructor of CrmContext and it will default to Load function in SettingManager which looks in both locations (appSettings first) and utilizes those in instantiating the OrganizationWebProxyClient in CrmContext.

using (var context = new CrmContext())
{
    var contacts = context.ServiceContext.CreateQuery("contact").Select(a => a.GetAttributeValue<string>("fullname"));

    foreach (var contact in contacts)
    {
        Console.WriteLine(contact);
    }
}

You’re done, you now have an IOrganizationService (OrganizationWebProxyClient) and an OrganizationServiceContext. You can make requests (Execute, Retrieve, RetrieveMultiple) and the full Linq provider (CreateQuery, UpdateObject, AddObject, etc.) at your disposal. If you want to use Xrm.Tooling, you can as well since CrmServiceClient has a constructor that takes OrganizationWebProxyClient as a parameter.

using (var context = new CrmContext())
{
	using (var serviceClient = new CrmServiceClient(context.WebProxyClient)
	{
		// insert CrmServiceClient calls
	}
}

Let’s talk about licensing for a quick bit here. We have made this open source using GNU LGPLv3. You should go read the details of that license but we have done this with good reason. I got asked this a lot at Extreme, “You guys are giving this away?! With the source code?!”. Yes, we want everyone to be successful with portals, as well as Dynamics and we think this is a little bit of help to kick start everyone with the new authentication schema. You’re free to fork or clone this repo into your own projects but LGPL also means if you enhance or modify this framework you too have to contribute it back and make it open source. You think you want another constructor or make some other addition to the framework? Make a pull request on the GitHub repo, we are all ears. Please contribute and collaborate with us as we want to grow and improve this framework, it’s going to benefit all of us.

How do you get it? The most current and all past versions will always be available on NuGet. You can easily put it in any project just by using the NuGet package manager, just search for Adoxio. Or by running the following from the NuGet Package Manager Console:

Install-Package Adoxio.Dynamics.Connect

The complete source code is published on the Adoxio GitHub if you want a look at the details.

Next post I will specifically discuss utilizing the CrmContext in an ASP.NET web app and you can see how easy it is to make it available everywhere in your web application.

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

eXtreme365 Lisbon 2017 Highlights

Extreme365, the new ExtremeCRM has just completed in Lisbon, Portugal. What an amazing, beautiful and fun location to hold a great Dynamics conference. Lisbon was great, the food, historic locations, and the landscape were second to none. This event exceeded expectations with the quality of the sessions, the information shared by partners, MVPs and Microsoft themselves. I met so many smart Dynamics professionals and just really fun people to hang out with. It was an honor to be both an attendee to a great conference and a speaker. Big shout out to Nelson Lopes from Microsoft Canada for guiding us on an amazing Portuguese experience over the week.

So what was the hot news coming out of the event? A lot of great sessions from a number of partners as well as the Microsoft product group, here are some of the top things that caught my attention:

  • Virtual entities – allow data in external systems to be represented as CRM entities and can take advantage of Business Process capabilities. These are just models in the Dynamics system but no tables created in the database and no data is replicated. Plug-in to APIs and surface external data to Dynamics within the Dynamics interface. Have an Azure DocumentDB you want to show in Dynamics, or maybe some Salesforce data (😈), as long as it has an API or you can create your own you can surface the data and interact with it within Dynamics like its native Dynamics data. Important to note that there is no security model in Dynamics for virtual entities, security is the responsibility of the source system or API.
  • Flow and Logic Apps are major investment areas for the Dynamics product group. I think we can expect a lot of improvement to existing features and new functionality coming to these components, it is the workflow engine of the future.
  • Read only replicas across regions – if you’re a global organization then this one is for you. No longer will you have to deal with long latency to access to Dynamics data in another region. Coming in a future release will be the ability to replicate your Dynamics data to various regions but only in a read-only state, one region will remain as your primary with full read/write functionality.
  • 3rd party search functionality to allow a pluggable search provider instead of the relevance search that is powered by Azure.
  • Event Management – still coming and with an Event Management Portal! Organize events into sessions and tracks, manage schedules and conflicts, and track registrations.
  • On Premise Dynamics to need an Azure Pack in a future release to support items like a service bus and other functions so that closer parity between online and on premises can be maintained.
  • ALM for Dynamics – the cries for more robust Application Lifecycle Management tooling with Dynamics 365 have been heard and the platform team will be bringing PowerShell and API functions to provide better ALM functions for online. Exact details in terms of functionality are unknown as is the timeframe for this, but great news to hear — personally and from Adoxio’s perspective we really hope to see similar tooling to the ADX AlmToolkit and scripting capability for Configuration Data Manager so that it doesn’t have to be run interactively.
  • Custom controls like the Gantt chart in Project Service will be part of the solution architecture (they actually already are for PSA) in the next release so you as an partner or ISV can build your own controls and easily transport them just like other Dynamics components. Custom controls will be developed using standard web development technologies, JavaScript, CSS and image file assets.

For myself and Adoxio this was also a big event in that we launched both the Adoxio Connect Framework for Dynamics 365 as well as Adoxio Connect365. We were extremely excited to be able to do it at this event so we could share it with the Dynamics community and it has already been a great success. The Adoxio Connect Framework has been released as an open source library under GNU LGPLv3 so other partners are able to utilize the same core connection framework as we do to build our own products. We really want everyone to succeed with Dynamics 365 portals and we think the framework and the concepts we presented are a great way to help fill the functional gaps whatever they maybe for your implementation.

Adoxio Connect365 is our subscription based service built on top of the framework that has a number commonly requested extensions for the portals; modules available: SharePoint, Payment Services, ESRI and soon to come PowerBI. Connect365 can help you immediately add functionality that wasn’t possible before to your portals without having to invest, develop, maintain or even worrying about hosting and be supported by those that know portals the best. To learn more about Adoxio Connect Framework for Dynamics 365 and Adoxio Connect365 check out some of the links below. This is just the beginning, there will be so much more to come.

Thanks to the Extreme365 team for putting on incredible event, myself and the whole Adoxio team can’t wait till the next one!

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

Speaking at eXtreme365 2017 Lisbon

I am very excited to be speaking at the new eXtreme365 (formerly eXtremeCRM) in Lisbon March 13 – 17, 2017!

I will be delivering two sessions at the partner and customer events on Dynamics 365 portals, and excited to make public a new framework Adoxio has been working on to bring extended customization capabilities to Dynamics 365 portals. As part of this we will be demoing, as well making available our core common template that our solutions and products are built on to eXtreme365 attendees.

The purpose of the eXtreme365 conference is to help the Microsoft Dynamics 365 (CRM) community more effectively grow their business by selling, deploying and extending the Microsoft Dynamics 365 solution. eXtreme365 is dedicated to providing insight to the Microsoft Dynamics 365 future vision and strategy and encourages sharing of knowledge among the Microsoft Dynamics 365 community. eXtreme supports critical connections with Microsoft, ISVs and partners – all with a goal of helping the community learn, grow and work more productively together.

If you’re in Lisbon and want to learn about Dynamics 365 portals then it would be great to meet you and to have you at the sessions.


Partner Session: Extend Dynamics 365 portals with Custom Code

14/03/2017 16:45 – 18:00

Reached the limitations of configuration with your Dynamics 365 portal and need to extend it with custom functionality? In this session learn how to create your own portal companion web app using Dynamics 365 Server-to-Server authentication and a secure token service (STS) for seamless integration with your Dynamics 365 portal and the ability to write your own custom C# code.

Attendees will see an end to end solution example and gain access to the templates to kick start your own custom portal development. Build custom integration or a complex API or whatever your business requirements demand with the power of the CRM SDK and the .NET Framework for your portal.


Customer Session: Everything you need to know – Dynamics 365 portals Implementations

17/03/2017 15:15 – 16:15

Interested in learning about Microsoft Dynamics 365 portals and what an implementation looks like? Join our session to learn about best practices, methodology, and get a basic understanding of how this solution can be applied to your organization.