Retrieve published metadata

Category: Performance, Usage

Impact potential: High

Symptoms

Retrieving unpublished metadata can cause:

Slower performance
User confusion

Guidance

It's uncommon to retrieve unpublished customizations and you rarely need to retrieve those customizations.

You might need to retrieve unpublished customizations if you want to create an application to edit customizable metadata. For example, if you 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're not 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 set 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 can retrieve unpublished metadata through the RetrieveAsIfPublished parameter:

The following examples show how to retrieve unpublished customizations:

Warning

Avoid these scenarios.

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 also applies to the following Web API functions:

Additional information

The Dynamics 365 service allows retrieval of certain metadata that is published or unpublished. Since Dynamics CRM 2011, the application's in-memory metadata cache returns published metadata by default, unless you explicitly set the RetrieveAsIfPublished property to true.

Retrieving unpublished metadata adds overhead to processing the request, so it performs more slowly. It can also return metadata that the requestor doesn't expect. For example, retrieving unpublished optionset metadata can return a label value that isn't visible in the user interface, causing confusion for the end-user.

Feedback

Was this page helpful?

Last updated on 2026-03-05