Fixing a Strange Connection Bug in the CrmServiceClient

CrmServiceClient and Multiple Environments in D365

Authors: Thomas Cunningham | Principal Developer |Richard Hancock | Managed Services Specialist | Formus Professional Software | Feb 2021
Developer Tips - Dynamics SDK Bug in the CrmServiceClient

If you have spent nearly any amount of time working as a Dynamics developer, it is highly likely you have used the XrmTooling package to connect to a Dynamics CE instance. It provides abstractions for speaking to the Dynamics web APIs which makes our lives a lot easier.

Screen grab of Assembly Dynamics package

However, you have likely also noticed that it is not always as well documented as it could be, with some aspects of its functionality remaining a bit mysterious.

For example you may notice that the essential CrmServiceClient class implements the IDisposable interface.

So that means we dispose of it right? What behaviour should we expect if we do? I am afraid Microsoft does not deign to tell us, and we may never have the answers to these questions!

A Point in the Right Direction

CrmServiceClient and useUniqueInstance

Occasionally this lack of information can be a serious frustration, which can only be resolved by careful experimentation, and guidance from the developer community.

An example I would like to highlight in this article (and hopefully save you some stress!) is that some of the key constructor overloads of the CrmServiceClient require a barely documented parameter named useUniqueInstance’.

From the official sources I scoured the most information I found on its was this:

Code snippet: useUniqueInstance Parameter

Reusing a connection sounds like a win for efficiency to me, so why would you not pass a false?

Particularly when we have not been warned of any caveats! Well, one good reason would be that we have little insight into what this functionality entails. I can confirm that in at least once scenario it results in unexpected and potentially breaking behaviour.

If you are developing a service that needs to speak to more than one Dynamics system and do not pass true for this parameter, the SDK will happily ignore all of the other credentials you have provided and produce you an instance of CrmServiceClient that does in fact connect to the previous environment you authenticated with.

No exception is thrown and no warning is given, you simply now have a redundant re-instantiation of the object you had previously.

I can see how this functionality could be useful, and it is not unreasonable that ‘’reusing” a connection would leave it attached to the original system. But it is poorly communicated and will leave many a developer scratching their head over the ignored connection credentials.

If it must work like this, and must be a part of the constructor, could it not have its own overload? Or just an exception if the connection conflicts with the new credentials?

Stay Informed - Sign up to Tech News Updates

We keep a close eye on Microsoft Release Waves as there can be significant updates to software. Most good, some bad and a few ugly. While we cannot change or influence Microsoft’s actions, we do actively seek out and review these release documents.

Our Microsoft Wave updates give you a summary of the original Microsoft documents

  • Inform you of new or improved features
  • A heads-up on any tricky bits you may have to navigate
  • Include advice on how to mitigate any hidden nasties (where possible).

You can sign up to receive these MS Wave updates automatically to your email account. Alternatively, keep checking back here within our resources pages.