MetadataService Web Service

In addition to the CrmService Web service, the Microsoft CRM API includes a MetadataService Web service that allows you to programmatically access the metadata. With the MetadataService Web service, you can query entities and their attributes. You can also retrieve picklist and status values from the string map table.

The Metadata Web service is located at http://<crmserver>/mscrmservices/2006/metadataservice.asmx

As with the CRMService Web service, you will need to add a Web reference in your project to access the methods and properties available.

However, unlike the CRMService Web service, the MetadataService Web service allows for retrieve (read-only) requests only. Therefore, you can use this service to retrieve information, but you cannot manipulate the underlying metadata. You must use the Web-based customization tools to add, modify, or delete the metadata.

Adding a MetadataService Web Reference to Your Project

1. Open the WorkingWithCrm project you created earlier in this chapter in Visual Studio .NET.

2. Right-click the project, and then click Add Web Reference.

3. In the Add Web Reference dialog box, add the MetadataService reference:

   1. In the URL box, type http://<crmserver>/mscrmservices/2006/metadataservice.asmx.

   2. In the Web reference name box, type MetadataServiceSdk. (Note that this is case-sensitive.)

   3. Click Add Reference.

The Metadata Web service offers four key methods:

• GetTimeStamp Returns the date and time of the last metadata update

• RetrieveAttributeMetadata Returns all information regarding a specific entity's attribute

• RetrieveEntityMetadata Returns all information regarding a specific entity

• RetrieveMetadata Returns all of the metadata

When using the RetrieveEntityMetadata and RetrieveMetadata methods, you must pass in a flag to tell the platform how much data you would like to return. Microsoft CRM refers to this as MetadataFlags, and you can specify one of five values:

• All Returns all metadata

• EntityOnly Retrieves metadata referring to the entity only

• IncludeAttributes Retrieves entity metadata, including attribute information

• IncludePrivileges Retrieves entity metadata, including the security privileges

• IncludeRelationships Retrieves entity metadata, including data relationship information

You should choose your flag based on the needs of your application, keeping in mind that Microsoft CRM provides these different options for performance reasons. The more data you request from the metabase, the longer it will take to process and return the results.

Listing 9-2 shows how you would use the Metadata Web service to access information about a picklist attribute. This example also shows some of the information that you can retrieve about this attribute that you can use in your own application.

Listing 9-2: Retrieving Metadata Information

 <%@ Page Language="C#" %> <%@ Import Namespace="WorkingWithCrm.MetadataServiceSdk" %> <script runat="server">  protected void Page_Load(object sender, EventArgs e)  {   MetadataService service = new MetadataService();   service.Credentials = System.Net.CredentialCache.DefaultCredentials;   service.Url = "http://<crmserver>/mscrmservices/2006/metadataservice.asmx";   try   {    AttributeMetadata attMetaData = service.RetrieveAttributeMetadata("account",      "accountcategorycode");    PicklistAttributeMetadata picklist = (PicklistAttributeMetadata)attMetaData;   System.Text.StringBuilder results = new System.Text.StringBuilder();    results.Append(@"<table width=""600"">");   results.Append(WriteRow("<b>Property</b>","<b>Value</b>"));   results.Append(WriteRow("DisplayName: ",attMetaData.DisplayName.ToString()));   results.Append(WriteRow("DefaultValue: ",attMetaData.DefaultValue.ToString()));   results.Append(WriteRow("DisplayMask: ",attMetaData.DisplayMask.ToString()));   results.Append(WriteRow("IsCustomField: ",attMetaData.IsCustomField.ToString()));   results.Append(WriteRow("Name: ",attMetaData.Name.ToString()));   results.Append(WriteRow("RequiredLevel: ",attMetaData.RequiredLevel.ToString()));   results.Append(WriteRow("Type: ",attMetaData.Type.ToString()));   results.Append(WriteRow("ValidForCreate: ",attMetaData.ValidForCreate.ToString()));   results.Append(WriteRow("ValidForRead: ",attMetaData.ValidForRead.ToString()));   results.Append(WriteRow("ValidForUpdate: ",attMetaData.ValidForUpdate.ToString()));   string optionList = string.Empty;   foreach(Option o in picklist.Options)   {    optionList += o.OptionValue.ToString() + "=" + o.Description + "<br>";   }   results.Append(WriteRow("Options",optionList));   results.Append("</table>");   Response.Write(results.ToString());  }  catch (System.Web.Services.Protocols.SoapException ex)   {    // Handle error.   }  }  // Helper method to write out a table row of output  private string WriteRow(string Label, string Value)  {   return @"<tr style=""font-family:tahoma;font-size:8pt;""><td valign=""top"">" + Label + "</td><td>" + Value + "</td></tr>";  } </script> <html> <head runat="server" >  <title>Metadata Attribute</title>  <style>body { font-family:Tahoma;font-size:9pt; }</style> </head> <body>  <form  runat="server">  </form> </body> </html> 

Figure 9-5 shows the output if you were to run this Web form page in Visual Studio .NET.

Figure 9-5: Picklist metadata

Again, we won't list all of the properties and methods of the MetaData WebService because of space considerations, but you can use the SDK or the Visual Studio IntelliSense feature to discover all of its available properties and methods.