Why use IOrganizationService instead of CrmServiceClient in Dynamics 365 XRM tooling SDK?

Question

Microsoft sample code for accessing Dynamics often looks like this:

    static void Main(string[] args)
    {
        try
        {
            string connectionString =
                "Url=https://myorg.crm.dynamics.com; [email protected]; Password=******; authtype=Office365";

            using (CrmServiceClient conn = new CrmServiceClient(connectionString))
            {
                // Cast the proxy client to the IOrganizationService interface.
                IOrganizationService orgService = (IOrganizationService)conn.OrganizationWebProxyClient ??
                                                  conn.OrganizationServiceProxy;

                Console.WriteLine("Microsoft Dynamics CRM version {0}.", ((RetrieveVersionResponse)orgService.Execute(new RetrieveVersionRequest())).Version);
            }
        }
        catch (FaultException<OrganizationServiceFault> osFaultException)
        {
            Console.WriteLine("Fault Exception caught");
            Console.WriteLine(osFaultException.Detail.Message);
        }
        catch (Exception e)
        {
            Console.WriteLine("Uncaught Exception");
            Console.WriteLine(e);
        }
    }
}

But it is equally possible (and simpler) to use the Crm Service Client directly, like this:

class Program
{
    static void Main(string[] args)
    {
        try
        {
            string connectionString =
                "Url=https://myorg.crm.dynamics.com; [email protected]; Password=******; authtype=Office365";

            using (CrmServiceClient conn = new CrmServiceClient(connectionString))
            {
                Console.WriteLine("Microsoft Dynamics CRM version {0}.", ((RetrieveVersionResponse)conn.Execute(new RetrieveVersionRequest())).Version);
            }
        }
        catch (FaultException<OrganizationServiceFault> osFaultException)
        {
            Console.WriteLine("Fault Exception caught");
            Console.WriteLine(osFaultException.Detail.Message);
        }
        catch (Exception e)
        {
            Console.WriteLine("Uncaught Exception");
            Console.WriteLine(e);
        }
    }
}

My question: Why use that IOrganizationService property ever? It seems as if it has only a subset of the functionality of the CrmServiceClient. And CrmServiceClient used directly seems both faster, simpler, more efficient, and more feature-rich.

Any idea about why the sample code always has this additional layer of indirection?

Thanks.

Answer 1

IOrganizationService is an interface that defines the most basic methods required to access all Dynamics functions. There are a number of general benefits to using interfaces.

IOrganizationService has been around since CRM 2011, whilst CrmServiceClient was introduced around CRM 2016. A simple reason for using IOrganizationService is that has been around much longer and is present in existing code bases.

CrmServiceClient implements IOrganizationService, and also provides a range of other methods, e.g. authenticating with CRM. Before CrmServiceClient was introduced we used CrmConnection to authenticate to CRM. When we had to migrate from CrmConnection to CrmServiceClient, we only had to change to CrmServiceClient, extract IOrganizationService and the rest of the code base remains the same.

Programming to the IOrganizationService interface makes your code far more portable, and reusable. For example; when you don't know your service object is going to be created.

IOrganizationService orgService = IOrganizationService)conn.OrganizationWebProxyClient ?? conn.OrganizationServiceProxy;

For testing purposes when you want to mock IOrganizationService with a new MockOrganizationService class.

When you want to move code between an external application and a plugin. In a plugin the CrmServiceClient is not provided.