Customize option sets


Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

Typically, you use global option sets to set fields so that different fields can share the same set of options, which are maintained in one location. Unlike local options sets which are defined only for a specific attribute, you can reuse global option sets. You will also see them used in request parameters in a manner similar to an enumeration.

When you define a global option set by using CreateOptionSetRequest, we recommend that you let the system assign a value. You do this by passing a null value when you create the new OptionMetadata instance. When you define an option, it will contain an option value prefix specific to the context of the publisher set for the solution that the option set is created in. This prefix helps reduce the chance of creating duplicate option sets for a managed solution, and in any option sets that are defined in organizations where your managed solution is installed. For more information, see Merge option set options.

You can download the sample from here.

Messages Request Classes

Use the following message request classes to work with global option sets

Use the following message request classes with both global and local option sets.

Retrieve a global option set

The following sample shows how to retrieve a global option set by name using the RetrieveOptionSetRequest message:

// Use the RetrieveOptionSetRequest message to retrieve  
// a global option set by it's name.
RetrieveOptionSetRequest retrieveOptionSetRequest =
    new RetrieveOptionSetRequest
        Name = _globalOptionSetName

// Execute the request.
RetrieveOptionSetResponse retrieveOptionSetResponse =

Console.WriteLine("Retrieved {0}.",

// Access the retrieved OptionSetMetadata.
OptionSetMetadata retrievedOptionSetMetadata =

// Get the current options list for the retrieved attribute.
OptionMetadata[] optionList =

Create a global option set

Use the CreateOptionSetRequest message to create a new global option set. Set the IsGlobal property to true to indicate that the option set is global. The following code example creates a global option set called “Example Option Set”:

// Define the request object and pass to the service.
CreateOptionSetRequest createOptionSetRequest = new CreateOptionSetRequest
    // Create a global option set (OptionSetMetadata).
    OptionSet = new OptionSetMetadata
        Name = _globalOptionSetName,
        DisplayName = new Label("Example Option Set", _languageCode),
        IsGlobal = true,
        OptionSetType = OptionSetType.Picklist,
        Options = 
        new OptionMetadata(new Label("Open", _languageCode), null),
        new OptionMetadata(new Label("Suspended", _languageCode), null),
        new OptionMetadata(new Label("Cancelled", _languageCode), null),
        new OptionMetadata(new Label("Closed", _languageCode), null)

// Execute the request.
CreateOptionSetResponse optionsResp =

Create a picklist that uses a global option set

The following sample shows how to create a picklist attribute that uses a global option set by using CreateAttributeRequest:

// Create a Picklist linked to the option set.
// Specify which entity will own the picklist, and create it.
CreateAttributeRequest createRequest = new CreateAttributeRequest
    EntityName = Contact.EntityLogicalName,
    Attribute = new PicklistAttributeMetadata
        SchemaName = "sample_examplepicklist",
        LogicalName = "sample_examplepicklist",
        DisplayName = new Label("Example Picklist", _languageCode),
        RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),

        // In order to relate the picklist to the global option set, be sure
        // to specify the two attributes below appropriately.
        // Failing to do so will lead to errors.
        OptionSet = new OptionSetMetadata
            IsGlobal = true,
            Name = _globalOptionSetName


Update a global option set

The following sample shows how to update the label for a global option set by using UpdateOptionSetRequest:

// Use UpdateOptionSetRequest to update the basic information of an option
// set. Updating option set values requires different messages (see below).
UpdateOptionSetRequest updateOptionSetRequest = new UpdateOptionSetRequest
    OptionSet = new OptionSetMetadata
        DisplayName = new Label("Updated Option Set", _languageCode),
        Name = _globalOptionSetName,
        IsGlobal = true


//Publish the OptionSet
PublishXmlRequest pxReq1 = new PublishXmlRequest { ParameterXml = String.Format("<importexportxml><optionsets><optionset>{0}</optionset></optionsets></importexportxml>", _globalOptionSetName) };

Ordering options

The following sample shows how the options in a global option set can be ordered by using OrderOptionRequest:

// Change the order of the original option's list.
// Use the OrderBy (OrderByDescending) linq function to sort options in  
// ascending (descending) order according to label text.
// For ascending order use this:
var updateOptionList =
    optionList.OrderBy(x => x.Label.LocalizedLabels[0].Label).ToList();

// For descending order use this:
// var updateOptionList =
//      optionList.OrderByDescending(
//      x => x.Label.LocalizedLabels[0].Label).ToList();

// Create the request.
OrderOptionRequest orderOptionRequest = new OrderOptionRequest
    // Set the properties for the request.
    OptionSetName = _globalOptionSetName,
    // Set the changed order using Select linq function 
    // to get only values in an array from the changed option list.
    Values = updateOptionList.Select(x => x.Value.Value).ToArray()

// Execute the request

//Publish the OptionSet
PublishXmlRequest pxReq4 = new PublishXmlRequest { 
ParameterXml = String.Format("<importexportxml><optionsets><optionset>{0}</optionset></optionsets></importexportxml>", _globalOptionSetName) 

Retrieve all global option sets

The following sample shows how to retrieve all global option sets by using RetrieveAllOptionSetsRequest:

// Use RetrieveAllOptionSetsRequest to retrieve all global option sets.
// Create the request.
RetrieveAllOptionSetsRequest retrieveAllOptionSetsRequest =
    new RetrieveAllOptionSetsRequest();

// Execute the request
RetrieveAllOptionSetsResponse retrieveAllOptionSetsResponse =

// Now you can use RetrieveAllOptionSetsResponse.OptionSetMetadata property to 
// work with all retrieved option sets.
if (retrieveAllOptionSetsResponse.OptionSetMetadata.Count() > 0)
    Console.WriteLine("All the global option sets retrieved as below:");
    int count = 1;
    foreach (OptionSetMetadataBase optionSetMetadata in
        Console.WriteLine("{0} {1}", count++,
            (optionSetMetadata.DisplayName.LocalizedLabels.Count >0)? optionSetMetadata.DisplayName.LocalizedLabels[0].Label : String.Empty);

Delete a global option set

The following sample shows how to check whether a global option set is being used by another solution component by using RetrieveDependentComponents message (RetrieveDependentComponents Function or RetrieveDependentComponentsRequest), and then how to delete it by using DeleteOptionSet message (For Organization Service, use DeleteOptionSetRequest):

// Create the request to see which components have a dependency on the
// global option set.
RetrieveDependentComponentsRequest dependencyRequest =
    new RetrieveDependentComponentsRequest
        ObjectId = _optionSetId,
        ComponentType = (int)componenttype.OptionSet

RetrieveDependentComponentsResponse dependencyResponse =

// Here you would check the dependencyResponse.EntityCollection property
// and act as appropriate. However, we know there is exactly one 
// dependency so this example deals with it directly and deletes 
// the previously created attribute.
DeleteAttributeRequest deleteAttributeRequest =
    new DeleteAttributeRequest
    EntityLogicalName = Contact.EntityLogicalName,
    LogicalName = "sample_examplepicklist"


Console.WriteLine("Referring attribute deleted.");
// Finally, delete the global option set. Attempting this before deleting
// the picklist above will result in an exception being thrown.
DeleteOptionSetRequest deleteRequest = new DeleteOptionSetRequest
    Name = _globalOptionSetName


See also

Create and update option sets using the Web API


Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).