Retrieve published metadata

Makale
02/27/2024

Category: Performance, Usage

Impact potential: High

Symptoms

Retrieving unpublished metadata could result in:

Slower performance
User confusion

Guidance

It isn't common to retrieve unpublished customizations and rarely would you have the need to retrieve those customizations.

An example of when you would need to retrieve unpublished customizations is if you want to create an application to edit customizable metadata. For instance, if you were to create a custom metadata editor, you must retrieve any unpublished definitions of those items. If a developer defines some changes but doesn't publish them, your application must be able to retrieve them to ensure the developer is retrieving the latest developed customizations. Failure to do so could result in the loss of unpublished customizations.

However, if you aren't creating an editor or don't have an explicit need for retrieving unpublished definitions, then only retrieve definitions that are published. The following examples show how to retrieve published customizations:

Default behavior

By default, retrieving metadata gets only published customizations.

public RetrieveAllEntitiesAttributesResponse GetAllEntitiesImplicit(IOrganizationService service)
{
    var request = new RetrieveAllEntitiesRequest();
    request.EntityFilters = EntityFilters.Attributes;

    return service.Execute(request) as RetrieveAllEntitiesAttributesResponse;
}

Explicitly controlling the behavior

Explicitly setting the RetrieveAsIfPublished property to retrieve only published customizations

public RetrieveAllEntitiesAttributesResponse GetAllEntitiesExplicit(IOrganizationService service)
{
    var request = new RetrieveAllEntitiesRequest()
    {
        RetrieveAsIfPublished = false
        EntityFilters = EntityFilters.Attributes
    };

    return service.Execute(request) as RetrieveAllEntitiesAttributesResponse;
}

Problematic patterns

The following operations allow for retrieving unpublished metadata through the RetrieveAsIfPublished parameter:

Examples of retrieving unpublished customizations are documented below:

Warning

These scenarios should be avoided.

public RetrieveEntityKeyResponse GetEntityKey(IOrganizationService service, string entityName, string keyName)
{
    var request = new RetrieveEntityKeyRequest()
    {
        EntityLogicalName = entityName,
        LogicalName = keyName,
        RetrieveAsIfPublished = true
    };

    return service.Execute(request) as RetrieveEntityKeyResponse;
}

public RetrieveRelationshipResponse GetRelationship(IOrganizationService service, Guid id)
{
    var request = new RetrieveRelationshipRequest()
    {
        MetadataId = id,
        RetrieveAsIfPublished = true
    };

    return service.Execute(request) as RetrieveRelationshipResponse;
}

public RetrieveEntityAttributesResponse GetEntity(IOrganizationService service, Guid id)
{
    var request = new RetrieveEntityRequest()
    {
        MetadataId = id,
        RetrieveAsIfPublished = true,
        EntityFilters = EntityFilters.Attributes
    };

    return service.Execute(request) as RetrieveEntityAttributesResponse;
}

Web API functions

This guidance applies to the following Web API functions as well:

Additional information

The Dynamics 365 service allows for retrieval of certain metadata that is published or unpublished. Ever since Dynamics CRM 2011, published metadata is returned, by default, from the application's in-memory metadata cache unless the developer explicitly assigns the RetrieveAsIfPublished property value to true.

Retrieving unpublished metadata not only adds overhead to processing the request itself, performing more slowly, it could also return metadata that the requestor doesn't expect. For example, retrieving unpublished optionset metadata could return a label value that isn't visible in the user interface, causing confusion to the end-user.