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”