Fun for all the family

Gripping headline, I know. My current contract has involved communicating with a third-party Dynamics CRM, and while there is plenty of advice out there on the internet, I didn’t find anything that completely worked. So this, for now at least, will fill that gap.

We’re going to need a couple of things before we start:

• The service URL and credentials for the Dynamics instance.
• The MS Dynamics SDK. I’m using the 2011 version; you may need a different one.

The SDK contains the CrmSvcUtil.exe command line tool, which will generate code for early-binding to the CRM objects. Getting the correct parameters for this was the hardest part of the integration, and essentially this is the meat of this blog post.

You’ll find CrmSvcUtil.exe in the bin folder in the SDK. Open a command prompt there with admin privileges, then construct your command using this form:

CrmSvcUtil.exe /codeCustomization:"Microsoft.Xrm.Client.CodeGeneration.CodeCustomization, Microsoft.Xrm.Client.CodeGeneration" /out:Xrm.cs /url:[DYNAMICS SERVICE URL] /username:[DYNAMICS USER NAME] /password:[DYNAMICS PASSWORD] /namespace:Xrm /serviceContextName:XrmServiceContext


The parameters you’ll need to set for your particular instance are:

• [DYNAMICS SERVICE URL] – You can find this in your dynamics management site, under Settings > Customization > Developer Resources. You want the SOAP Organization Service. This will be of the form https://[YOUR-CRM-NAME].[LOCATION].dynamics.com/XRMServices/2011/Organization.svc. This example contains 2011 in the URL because I’m using the 2011 version. [YOUR-CRM-NAME] will have been set when your instance was created. [LOCATION] depends on the physical location of your instance and the identity provider being used. For example, mine is crm4.
• [DYNAMICS USER NAME] – This will be the email address of the account you are using to access Dynamics.
• [DYNAMICS PASSWORD] – The password for the same account, duh.

Note that I’ve set the out parameter to be Xrm.cs. This will dump all the generated code into that file in the SDK/Bin folder. If you’re going to regenerate the code often you may want to set the output path to somewhere in your project, but I’m trying to keep things simple in this example.

With everything in place, hit return and wait while the utility does its stuff. It will probably sit there looking like it’s doing nothing for a little while. Be patient, and eventually it will start spewing out logs like something from The Matrix. If you’ve got a large organization this could take some time.

At the end of the process you should have a massive pile of autogenerated code. In my case it ran to over 100,000 LOC which Visual Studio choked on when I tried to open it. So if you need to look at it, use something like Notepad++ instead.

If it isn’t already there, copy the generated file to somewhere suitable in the project. We will reference it in the next step.

If you’re still awake

The XRM SDK contains the very useful CrmConnection. This provides a way of getting authentication details from a connection string and reusing this connection throughout the application. This may sound counter-intuitive. Surely it would be better to have multiple connections? The problem the single shared connection solves is that authenticating the connection takes a while. Rather than go through the process for every transaction, the shared connection means subsequent transactions are pre-authenticated. The CrmConnection is thread-safe, and performance issues with multiple transactions are avoided by creating a new XrmServiceContext with the connection for each transaction.

Let’s get started by adding the Microsoft Dynamics CRM 2015 SDK client and portal assemblies via nuget. You may have noticed that’s the 2015 version. I couldn’t find an exact equivalent for 2011, and my best guess didn’t work. So this may be the part where this blog post falls apart and causes great anguish, but so far I’ve had no issues using the 2015 one.

Now we have the XRM objects we need, let’s add a connection string. Add it to web.config, in the usual place where connection strings live:

The tokenised parts are exactly the same as described in the CrmSvcUtil parameters above.

To use the connection across your application you’ll most likely want to set it up using your dependency injection weapon of choice. I’m using StructureMap:

container.For().Singleton().Use(ctx => new CrmConnection("CrmConnection"));

Note that I’m creating it as a singleton because we want to share it across the application. It’s thread-safe, remember.

Now we’re ready to use it. Here’s an extremely basic example, which retrieves a contact from the ContactSet:

public class XrmExample
{
	private readonly CrmConnection _crmConnection;

	public XrmExample(CrmConnection crmConnection)
	{
		_crmConnection = crmConnection;
	}

	public Contact GetContact(string username)
	{
		using (var xrm = new XrmServiceContext(_crmConnection))
		{
			var contact = xrm.ContactSet.FirstOrDefault(x => x.EMailAddress1 == username.ToLower());
			if (contact != null)
			{
				return contact;
			}
		}
		return null;
	}
}

EMailAddress1 probably doesn’t exist in your instance, but you get the idea. The main points are that we’re getting the CrmConnection singleton and using it to create a new XrmServiceContext for our transaction. Repeat this pattern throughout your application and all will be well.