You use RetrieveEntityRequest—with its corresponding response message RetrieveEntityResponse—to retrieve a single EntityMetadata object from CRM. The RetrieveEntityRequest object has three properties that should always be set:

The EntityItems property determines whether the five important collections (Privileges, Attributes, ManyToManyRelationships, ManyToOneRelationships, and OneToManyRelationships) are populated when the entity data is retrieved. Retrieving these collections is a heavyweight task, and for performance reasons a developer might choose to retrieve only some of the entity’s related data. Because EntityItems is marked with FlagsAttribute, multiple values can be combined using a bitwise OR (the | operator in C#). The EntityItems enum has the following values:

The RetrieveAsIfPublished property determines whether unpublished metadata is shown. When this property is set to true, CRM simulates an entity publish operation when retrieving the metadata. If you want to retrieve metadata as experienced by end users, set this property to false. If you want to retrieve metadata as experienced by customizers (in the customization user interface of the application), set this property to true.

The LogicalName property determines which entity is retrieved.

More Info

Refer to the following article in the Microsoft Dynamics CRM 4.0 Software Development Kit (SDK), which provides additional information regarding logical names: http://msdn.microsoft.com/en-us/library/cc151044.aspx.

The following code shows how to retrieve a single entity from CRM:

MetadataService metadataService = GetMetadataService("contoso");

RetrieveEntityRequest request = new RetrieveEntityRequest();
request.EntityItems = EntityItems.All;
request.RetrieveAsIfPublished = true;
request.LogicalName = "account";
RetrieveEntityResponse response = (RetrieveEntityResponse)metadataService.Execute(request);

RetrieveAllEntitiesRequest retrieves all entities in CRM (System, Custom, and Customizable). You also need to set the RetriveAsIfPublished property and determine the depth and detail of the related entity collections using the MetadataItems property. RetrieveAllEntitiesRequest uses the MetadataItems property to govern the level of detail returned by the request. The MetadataItems property is an enum type that is also named MetadataItems. Similar to the EntityItems enum, multiple values can be combined to control the retrieval behavior as follows:

Notice that RetrieveAllEntitiesResponse contains an array of CrmMetadata objects. This array will only ever contain EntityMetadata objects (which inherit from CrmMetadata).

The following code retrieves all entities from CRM and writes their logical names to the console. Figure 8-3 displays the resulting output.

MetadataService metadataService = GetMetadataService("contoso");

RetrieveAllEntitiesRequest request = new RetrieveAllEntitiesRequest();
request.MetadataItems = MetadataItems.EntitiesOnly;
request.RetrieveAsIfPublished = false;
RetrieveAllEntitiesResponse response =
  (RetrieveAllEntitiesResponse)metadataService.Execute(request);

foreach (EntityMetadata entity in response.CrmMetadata)
{
    Console.WriteLine(entity.LogicalName);
}

Figure 8-3. RetrieveAllEntities sample code output

When retrieving an attribute with RetriveAttributeRequest you simply provide the logical names of the attribute and its parent entity. You can also use the attribute’s unique MetadataId (a GUID) if known.

Tip

You can often substitute the MetadataId for logical names of entities, attributes, and relationships. Note that these IDs are not consistent between organizations.

When retrieving a relationship with RetrieveRelationshipRequest, you simply provide the logical name of the relationship or its MetadataId (a GUID). You do not need to specify any parent entity information. RetrieveRelationshipRequest returns a RelationshipMetadata object. However, you need to cast this object to one of its child types: OneToManyMetadata or ManyToManyMetadata. ManyToOneMetadata does not exist—a many-to-one relationship is simply a one-to-many relationship viewed from a different perspective.

Two properties often cause confusion with the OneToManyMetadata object: ReferencedEntity and ReferencingEntity. Table 8-1 lists how the user interface describes each property.

RetrieveAllEntitiesResponse contains a copy of each one-to-many relationship in the appropriate arrays (OneToManyRelationships and ManyToOneRelationships) for both the Referenced and Referencing entities, as shown in Table 8-2.

You can locate a relationship’s logical name in the customization user interface. Figure 8-4 shows the relationship’s logical name in the Name field of the relationship customization form.

Figure 8-4. One-to-many relationship customization form

The following code sample demonstrates how to retrieve the equipment_accounts relationship shown in Figure 8-4 and display the Referencing and Referenced entity information.

MetadataService metadataService = GetMetadataService("contoso");

RetrieveRelationshipRequest request = new RetrieveRelationshipRequest();
request.Name = "equipment_accounts";
request.RetrieveAsIfPublished = true;
RetrieveRelationshipResponse response =
    (RetrieveRelationshipResponse)metadataService.Execute(request);

if (response.RelationshipMetadata is OneToManyMetadata)
{
    OneToManyMetadata equipmentAccounts =
     (OneToManyMetadata)response.RelationshipMetadata;

    Console.Write("Referenced Entity: ");
    Console.WriteLine(equipmentAccounts.ReferencedEntity);

    Console.Write("Referencing Entity: ");
    Console.WriteLine(equipmentAccounts.ReferencingEntity);
}

This relationship creates a lookup attribute on the account to the equipment entity.

Therefore, the Account entity is referencing the Equipment entity, and the Equipment entity is being referenced by the Account entity. Figure 8-5 shows console output for the sample.

Figure 8-5. Console output for relationship retrieval sample

You should only use LCIDs for languages installed on the Microsoft Dynamics CRM server. Attempts to use LCIDs for unavailable languages will silently fail. Use RetrieveAvailableLanguagesRequest with the CrmService to retrieve an array of LCIDs in the LocalIds property of the RetrieveAvailableLanguagesResponse object.

The following code shows how to retrieve the available languages and display them in the console:

//Connect to the regular CRM Service
CrmAuthenticationToken token = new CrmAuthenticationToken();
token.AuthenticationType = 0;
token.OrganizationName = "contoso";

CrmService crmService = new CrmService();
crmService.CrmAuthenticationTokenValue = token;
crmService.Credentials = CredentialCache.DefaultCredentials;
crmService.Url = "http://crm/mscrmservices/2007/crmservice.asmx";

RetrieveAvailableLanguagesRequest request = new RetrieveAvailableLanguagesRequest();
RetrieveAvailableLanguagesResponse response =
    (RetrieveAvailableLanguagesResponse) crmService.Execute(request)

Console.WriteLine("Available Languages");
foreach (int i in response.LocaleIds)
{
    Console.WriteLine(i);
}