Commonly, you will want to write applications that allow the MetadataService endpoint to be specified in a configuration file or registry entry. This allows the most control over the endpoint location and still permits it to be specified at deployment. If your application is located on the Microsoft Dynamics CRM 4.0 server, it can access a registry key maintained by Microsoft Dynamics CRM 4.0 itself. The following code demonstrates the simplest way to access the service endpoint.

public static MetadataService GetMetadataService(string organizationName)
  {
    CrmAuthenticationToken token = new CrmAuthenticationToken();
    token.OrganizationName = organizationName;

    MetadataService service = new MetadataService();
    // Replace <crmserver> with your own value
    service.Url = "http://<crmserver>/MSCRMServices/2007/MetadataService.asmx";
    service.UseDefaultCredentials = true;
    service.CrmAuthenticationTokenValue = token;

    return service;
  }

For the sake of brevity, we will use the GetMetadataService method throughout the sample code in the remainder of this chapter.

You use the CrmMetadataServiceUrl property of the OrganizationDetail object to determine the URL of the MetadataService, as demonstrated in the following code sample:

string orgName = "contoso";
string metadataServiceUrl;

CrmDiscoveryService discoveryService = new CrmDiscoveryService();
discoveryService.Credentials = CredentialCache.DefaultCredentials;
// Replace localhost with the correct URL for your application
discoveryService.Url = "http://localhost/MSCRMServices/2007/AD/CrmDiscoveryService.asmx";

RetrieveOrganizationsRequest retrieveOrgRequest = new RetrieveOrganizationsRequest();
RetrieveOrganizationsResponse retrieveOrgResponse =
    (RetrieveOrganizationsResponse)discoveryService.Execute(retrieveOrgRequest);

foreach (OrganizationDetail orgDetail in retrieveOrgResponse.OrganizationDetails)
{
    if (orgDetail.OrganizationName == orgName)
    {
        metadataServiceUrl = orgDetail.CrmMetadataServiceUrl;
        break;
    }
}

You should consider using the Discovery service option when you are unsure of the actual endpoints of your final deployment or when you are using Microsoft Dynamics CRM Online.

Just as the ICrmService interface is provided to plug-ins for accessing the CrmService Web service API from within a plug-in, an interface is also exposed for the MetadataService. This interface is called IMetadataService and is generated using the CreateMetadataService method on the IPluginExecutionContext object, as shown in the following code:

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace MetadataPluginSample
{
    public class MyPlugin : IPlugin
    {
        public void Execute(IPluginExecutionContext context)
        {
             IMetadataService metadataService = context.CreateMetadataService(true);
        }
    }
}

More Info

Please review Chapter 5, for more information regarding plug-ins and the IPluginExecutionContext object.

The MetadataService is also available in Microsoft Dynamics CRM for Outlook with Offline Access. Chapter 3 details how to locate and configure the URL endpoint and offline development is covered extensively in Chapter 10.

The offline client’s middle tier does not support customization, and subsequently not all MetadataService messages are available while offline. Only the following messages are available:

Chapter 3 introduced the CrmImpersonator class as a way to seamlessly authenticate with IFD deployments. Take special care when using the MetadataService with the CrmImpersonator class. Because of the way the CrmImpersonator class operates, you should avoid using the discovery service for locating the endpoint. Either manually set the endpoint from a configuration setting or use the registry.

The following sample code shows how to access the MetadataService Web service from the registry when using the impersonation pattern with the metadata service:

//Retrieve Server URL from the Registry
string metadataServiceUrl;
using (RegistryKey key = Registry.LocalMachine.OpenSubKey("Software\Microsoft\MSCRM"))
{
    metadataServiceUrl =
        key.GetValue("ServerUrl").ToString() + "/2007/metadataservice.asmx";
}

//Wrap Code in Using statement
using (new CrmImpersonator())
{
    CrmAuthenticationToken token =
     CrmAuthenticationToken.ExtractCrmAuthenticationToken(Context,"MyOrganizationName");
    token.AuthenticationType = 0;
    token.OrganizationName = "MyOrganizationName";
    MetadataService metadataService = new MetadataService();
    metadataService.CrmAuthenticationTokenValue = token;
    metadataService.Credentials = CredentialCache.DefaultCredentials;
    metadataService.Url = metadataServiceUrl;
}

As we mentioned earlier, the 3.0 version of Microsoft Dynamics CRM included a MetadataService Web service. The URL of this Web service is http://<crmserver>/mscrm-services/2006/metadataservice.asmx. Even though Microsoft Dynamics CRM 4.0 includes a new MetadataService, you can still access the 3.0 service. Some developers refer to this Web service as the 2006 endpoint (because of the 2006 in its URL) and the 4.0 Web service is known as the 2007 endpoint.

The capabilities of the 2006 endpoint service differ significantly from the 2007 endpoint. The 2006 endpoint is only capable of reading the metadata, and you can only connect to the default organization. When writing new code, you should only use the 2007 endpoint. Microsoft included the 2006 endpoint in Microsoft Dynamics CRM 4.0 for backward compatibility for customers upgrading from Microsoft Dynamics CRM 3.0 to 4.0.