Use the Discovery Service with the SDK Assemblies

You can create a client for a specific Common Data Service environment and not provide the user any options about which environment they can connect with. Only valid users for that specific environment can use your client.

If you want people using your client to be able to connect to any Common Data Service environment they have access to you could prompt them to enter the URL for their environment, but this is not recommended. Each user may have access to multiple Common Data Service environments. Users may not know or remember the URL for their environment. Expecting people to enter this URL is bound to frustrate users.

Instead, your client should provide a list of each of the available environments based on the user’s credentials. If there is more than one environment available, your application should prompt the user to choose which environment they want to connect with.

With Common Data Service, server and organization allocation may change as part of datacenter management and load balancing. Therefore, a discovery service provides a way to discover which server is serving an instance at a given time.

To use the discovery service using the SDK assemblies, add a reference to the Microsoft.Xrm.Sdk.dll assembly to your Visual Studio project, and then add a using statement to access the Microsoft.Xrm.Sdk.Discovery namespace.

The DiscoveryServiceProxy implements the IDiscoveryService interface.

The IDiscoveryService interface provides Execute(DiscoveryRequest) method you will use to pass a instance of the abstract DiscoveryRequest class.

Regional Discovery services

When you instantiate the DiscoveryServiceProxy you will need to provide a URL for a regional data center using one of the following values.

Location Discovery Web service URL
North America https://disco.crm.dynamics.com/XRMServices/2011/Discovery.svc
North America 2 https://disco.crm9.dynamics.com/XRMServices/2011/Discovery.svc
Europe, Middle East and Africa (EMEA) https://disco.crm4.dynamics.com/XRMServices/2011/Discovery.svc
Asia Pacific Area (APAC) https://disco.crm5.dynamics.com/XRMServices/2011/Discovery.svc
Oceania https://disco.crm6.dynamics.com/XRMServices/2011/Discovery.svc
Japan (JPN) https://disco.crm7.dynamics.com/XRMServices/2011/Discovery.svc
South America https://disco.crm2.dynamics.com/XRMServices/2011/Discovery.svc
India (IND) https://disco.crm8.dynamics.com/XRMServices/2011/Discovery.svc
Canada https://disco.crm3.dynamics.com/XRMServices/2011/Discovery.svc
United Kingdom (UK) https://disco.crm11.dynamics.com/XRMServices/2011/Discovery.svc

Note

If you do not know the user's region, you need to loop through the available regions until you get results. The Web API provides a single global discovery service. More information: Discover the URL for your organization using the Web API

Discovery service messages

There are three messages that you can use which all inherit from the abstract DiscoveryRequest class.

The following table lists the messages that are supported with Execute(DiscoveryRequest) method.

Message Description
RetrieveUserIdByExternalIdRequest Retrieves the logged-on user's ID in Common Data Service
RetrieveOrganizationRequest Retrieves information about a single organization.
RetrieveOrganizationsRequest Retrieves information about all organizations to which the user belongs.

Example

The following code for a console application uses the RetrieveOrganizationsRequest message to retrieve all the organizations for a user.

using System;
using System.Linq;
using Microsoft.Xrm.Sdk.Discovery;
using Microsoft.Xrm.Sdk.Client;
using System.ServiceModel.Description;

namespace DiscoveryServiceSample
{
  class Program
  {

    static OrganizationDetailCollection GetOrganizationDetails(DiscoveryServiceProxy svc)
    {

      var request = new RetrieveOrganizationsRequest()
      {
        AccessType = EndpointAccessType.Default,
        Release = OrganizationRelease.Current
      };
      try
      {
        var response = (RetrieveOrganizationsResponse)svc.Execute(request);
        return response.Details;
      }
      catch (Exception)
      {
        throw;
      }
    }
    static void Main(string[] args)
    {
      string canadaUrl = "https://disco.crm3.dynamics.com/XRMServices/2011/Discovery.svc";
      Uri discoveryUri = new Uri(canadaUrl);

      ClientCredentials creds = new ClientCredentials();
      creds.UserName.UserName = "you@yourorg.onmicrosoft.com";
      creds.UserName.Password = "yourPassword";

      using (var svc = new DiscoveryServiceProxy(discoveryUri, null, creds, null))
      {

        OrganizationDetailCollection details = GetOrganizationDetails(svc);

        details.ToList().ForEach(x =>
        {
          Console.WriteLine("Organization Name: {0}", x.FriendlyName);
          Console.WriteLine("Unique Name: {0}", x.UniqueName);
          Console.WriteLine("Endpoints:");
          foreach (var endpoint in x.Endpoints)
          {
            Console.WriteLine("  Name: {0}", endpoint.Key);
            Console.WriteLine("  URL: {0}", endpoint.Value);
          }
          Console.WriteLine();
        });
      };
      Console.ReadLine();
    }
  }
}

The results may look like this for a user with access to two instances:

Organization Name: Organization A
Unique Name: orga
Endpoints:
  Name: WebApplication
  URL: https://orgaservice.crm3.dynamics.com/
  Name: OrganizationService
  URL: https://orgaservice.api.crm3.dynamics.com/XRMServices/2011/Organization.svc
  Name: OrganizationDataService
  URL: https://orgaservice.api.crm3.dynamics.com/XRMServices/2011/OrganizationData.svc

Organization Name: Organization B
Unique Name: orgb
Endpoints:
  Name: WebApplication
  URL: https://orgbservice.crm3.dynamics.com/
  Name: OrganizationService
  URL: https://orgbservice.api.crm3.dynamics.com/XRMServices/2011/Organization.svc
  Name: OrganizationDataService
  URL: https://orgbservice.api.crm3.dynamics.com/XRMServices/2011/OrganizationData.svc

Note

The OrganizationDataService is the deprecated Organization Data Service, not the Web API. This service does not include a URL for the Web API.

See also

Discovery Services
Discover the URL for your organization using the Web API