Connecting to Microsoft Dynamics 365 using the SDK

If you are .Net developer and you need to connect to 365 from an external application, e.g. console application, then your easiest option is to the use the SDK. In this article, I’ll describe the basic steps to setup a project and connect to 365 use the Xrm Tooling assembly. In follow up articles I’ll go into more detail about using the connection to do something useful. If you are writing a plugin or custom workflow you will create your connection in a different manner, search the MSDN for more details.

This article is part of a series

The complete code sample is on GitHub, see Woodsworkblog.ConsoleApp, for this example see the ConnectingTo365 class.

Add the required assemblies to your project

I’ve created a basic Visual Studio Console Application (.Net Framework) but you can use pretty much whatever you like. The key assemblies we need to add are the following:

• Microsoft.Xrm.Sdk – defines the core methods and types for working with 365.
• Microsoft.Xrm.Tooling.Connector – defines a set of classes which assists with creating the connection.

You can find the assemblies in the downloadable SDK. However, I use the following Nuget packages, this also handles a number of dependencies that both assemblies have.

• Sdk – Install-Package Microsoft.CrmSdk.CoreAssemblies
• Tooling – Install-Package Microsoft.CrmSdk.XrmTooling.CoreAssembly

Create the service client

Using the CrmServiceClient we can create a service client that allows us to easily create a connection to 365. The class has a variety of constructors and approaches for creating the connection to CRM, we will be using a connection string. The format of the connection string varies depending on the infrastructure you are connecting to, check the documentation linked above for more information.

Create a new CrmServiceClient with a connection string, assuming your connection string is valid, that’s it, you now have a connection to 365. In a real application I would probably read the connection string from the app.config.

CrmServiceClient client = new CrmServiceClient("Url=https://abc.crm4.dynamics.com; Username=james@email.co.uk; Password=password; authtype=Office365");

Checking if your connection was successful

You can check if the CrmServiceClient successfully connected by examining the IsReady property. If IsReady is false the something has gone wrong, examine the LastCrmError and LastCrmException properties to find out why.

if (!client.IsReady)
{
    Console.WriteLine("Connection failed");

    Console.WriteLine(client.LastCrmError);
    Console.WriteLine(client.LastCrmException);
}

Getting the organization service object

Now we have the connection to 365 we need to access the organization service object, this will be our primary object for interacting with 365 data. The required object is presented as either a OrganizationServiceProxy or OrganizationWebProxyClient from matching properties of the CrmServiceClient. In at least some cases one of these will be null, I believe it depends on how the connection is made. On the MSDN the OrganizationWebProxyClient is described as the “instance for the active CRM connection using OAuth”. Whilst a little different both perform similar functions and meet the same IOrganizationService interface. I suspect in most cases using whatever is populated will be fine for most people, especially if (as I do) you primarily reference the organization service object by the IOrganizationService interface.

if (client.IsReady)
{
    Console.WriteLine("Connection successful");

    OrganizationServiceProxy organizationServiceProxy = client.OrganizationServiceProxy;

    OrganizationWebProxyClient organizationWebProxyClient = client.OrganizationWebProxyClient;

    IOrganizationService service = organizationServiceProxy ?? organizationWebProxyClient as IOrganizationService;

    Console.WriteLine($"OrganizationServiceProxy is populated?  {organizationServiceProxy != null}");

    Console.WriteLine($"OrganizationWebProxyClient is populated?  {organizationWebProxyClient != null}");
}

Usage of the service client

In this example I have used the CrmServiceClient primarily to get access to an IOrganizationService object – our primary object for 365 data interactions. The CrmServiceClient has a number of properties that are useful in determining what you have connected to, e.g. ConnectedOrgFriendlyName. It also has several general methods for interacting with CRM data like those found on the IOrganizationService (Create, Update, or Delete) along with more specific use cases not found on the IOrganizationService (CloseActivity, CloseTroubleTicket, or CancelSalesOrder).

In older releases of the SDK we used the CrmConnection which is similar in that it creates a connection, but didn’t have the extra functions for data interactions. With 365 it looks like you could just use the data functions on CrmServiceClient alone, without an IOrganizationService, I’ll leave the choice to you. An advantage in going the extra step to get the IOrganizationService is that you will probably find it has better backwards compatibility, as the interface has been around since CRM 2011.

Original Post https://woodsworkblog.wordpress.com/2017/06/25/connecting-to-microsoft-dynamics-365-using-the-sdk/