Use the Discovery Service with the SDK Assemblies


Effective March 2, 2020, the regional Discovery Service will be deprecated.

For information on how to transition to use the global Discovery Service, see Modify your code to use global Discovery Service.

You can create a client for a specific Microsoft Dataverse 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 Dataverse 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 Dataverse 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 Dataverse, 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 access the Discovery Service using SDK assembly APIs, add a reference to the Microsoft.Xrm.Sdk.dll assembly in your Visual Studio project, and then add a using statement to access the Microsoft.Xrm.Sdk.Discovery namespace.

The DiscoveryWebProxyClient 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 DiscoveryWebProxyClient 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
North America 2
Europe, Middle East and Africa (EMEA)
Asia Pacific Area (APAC)
Japan (JPN)
South America
India (IND)
United Kingdom (UK)


If you do not know the user's region, you need to loop through the available regions until you get results. A single global Discovery Service is also available. More information: Discover the URL for your organization

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 Microsoft Dataverse
RetrieveOrganizationRequest Retrieves information about a single organization.
RetrieveOrganizationsRequest Retrieves information about all organizations to which the user belongs.


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.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Xrm.Sdk.WebServiceClient;

namespace DiscoveryServiceSample
    class Program
        //These sample application registration values are available for all online instances.
        // this sample requires 5.2 or later
        public static string clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";

        static OrganizationDetailCollection GetOrganizationDetails(DiscoveryWebProxyClient svc)

            var request = new RetrieveOrganizationsRequest()
                AccessType = EndpointAccessType.Default,
                Release = OrganizationRelease.Current
                var response = (RetrieveOrganizationsResponse)svc.Execute(request);
                return response.Details;
            catch (Exception)
        static void Main(string[] args)
            string authority = @"";
            string northAmericaResourceUrl = "";
            string discoveryUrl = $"{northAmericaResourceUrl}/XRMServices/2011/Discovery.svc/web";
            Uri discoveryUri = new Uri(discoveryUrl);

            AuthenticationContext authContext = new AuthenticationContext(authority, false);
            string username = "";
            string password = "yourPassword"; 

            AuthenticationResult authResult = null;
            if (username != string.Empty && password != string.Empty)
                UserPasswordCredential cred = new UserPasswordCredential(username, password);
                authResult = authContext.AcquireTokenAsync(northAmericaResourceUrl, clientId, cred).Result;

            using (var svc = new DiscoveryWebProxyClient(discoveryUri))
                svc.HeaderToken = authResult.AccessToken;

                OrganizationDetailCollection details = GetOrganizationDetails(svc);

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

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

Organization Name: Organization A
Unique Name: orga
  Name: WebApplication
  Name: OrganizationService
  Name: OrganizationDataService

Organization Name: Organization B
Unique Name: orgb
  Name: WebApplication
  Name: OrganizationService
  Name: OrganizationDataService


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