Usar colunas de escolhas para armazenar várias opções

Os personalizadores podem definir uma coluna de escolhas que permite a seleção de várias opções. Este artigo explica como definir, consultar e criar colunas de opções usando a API Web e o SDK para .NET. A MultiSelectPicklistAttributeMetadata classe define um tipo de coluna que herda da EnumAttributeMetadata classe. Assim como a PicklistAttributeMetadata classe, esta coluna inclui uma propriedade OptionSetMetadata.Options que contém as opções válidas para a coluna. A diferença é que os valores obtidos ou definidos são do tipo OptionSetValueCollection, que contém uma matriz de inteiros que representa as opções selecionadas. Os valores formatados para esta coluna são uma cadeia de caracteres separada por ponto-e-vírgula que contém os rótulos das opções selecionadas.

Com a API Web, você define essa coluna usando o tipo de entidade MultiSelectPicklistAttributeMetadata.

Assim como as colunas de opções, tecnicamente não há nenhum limite superior no número de opções que você pode definir. Aplique considerações de usabilidade como o fator limitante. No entanto, você pode selecionar apenas 150 opções para uma única coluna. Além disso, você não pode definir um valor padrão.

Definir valores da coluna de opções

Os exemplos a seguir mostram como definir valores de opções para uma coluna chamada sample_outdooractivities que você adiciona à contact tabela.

Web API
SDK para .NET

Usando a API Web, defina os valores passando uma cadeia de caracteres contendo valores de número separados por vírgulas:

Solicitação:

POST [organization uri]/api/data/v9.2/contacts HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "@odata.type": "Microsoft.Dynamics.CRM.contact",
    "firstname": "Wayne",
    "lastname": "Yarborough",
    "sample_outdooractivities": "1, 9"
}

Resposta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [organization uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Usando o SDK para .NET, use o OptionSetValueCollection para definir valores para esta coluna:

public static Guid CreateContactWithChoicesColumnSetExample(IOrganizationService service) {

   OptionSetValueCollection activities = new OptionSetValueCollection();
   activities.Add(new OptionSetValue(1)); //Swimming
   activities.Add(new OptionSetValue(9)); //Camping

   Entity contact = new Entity("contact");
   contact["firstname"] = "Wayne";
   contact["lastname"] = "Yarborough";
   contact["sample_outdooractivities"] = activities;

   return service.Create(contact);

}

Consultar dados de colunas Choices

Dois operadores de condição dão suporte à consulta de valores em opções:

Web API	FetchXml	ConditionOperator
ContainValues	`contain-values`	ContainValues
DoesNotContainValues	`not-contain-values`	DoesNotContainValues

Note

Esses operadores dependem da indexação de texto completo aplicada às tabelas de banco de dados que armazenam os vários valores. Há alguma latência depois que novos registros são criados e o índice de texto completo entra em vigor. Talvez seja necessário aguardar vários segundos após a criação de novos registros antes que os filtros que usam esses operadores possam avaliar os valores.

Outros operadores de condição existentes que podem ser usados com esse tipo de coluna incluem o seguinte:

Web API	FetchXml	ConditionOperator
`eq`	`eq`	Equal
`ne`	`neq`	NotEqual
`not null`	`not-null`	NotNull
`eq null`	`null`	Null
In	`in`	In
NotIn	`not-in`	NotIn

Os exemplos a seguir mostram como usar os operadores DoesNotContainValues e ContainValues no conjunto de dados a seguir, na coluna de opções nomeada sample_outdooractivities na tabela contact.

Valores de escolhas `sample_outdooractivities`

Valor	Label
1	Natação
2	Caminhada
3	Alpinismo
4	Pesca
5	Busca
6	Running
7	Navegação
8	Esqui
9	Acampamento

Consulte Criar colunas de opções com código para código de exemplo para criar esta coluna.

Valores da tabela de contatos

`fullname`	`sample_outdooractivities`
Wayne Yarborough	1,9
Monte Orton	2
Randal Maple	4
Hiram Mundy	2,3,8,9
Barbara Weber	1,4,7
Georgette Sullivan	4,5,9
Verna Kennedy	2,4,9
Marvin Bracken	1,2,8,9

Web API
SDK para .NET

Este exemplo mostra como usar a ContainValues função de consulta para retornar todos os contatos que gostam de caminhadas. A resposta inclui o texto das opções como anotações devido à preferência aplicada odata.include-annotations="OData.Community.Display.V1.FormattedValue".

Solicitação:

GET [organization uri]/api/data/v9.2/contacts?$select=fullname,sample_outdooractivities&$filter=Microsoft.Dynamics.CRM.ContainValues(PropertyName='sample_outdooractivities',PropertyValues=%5B'2'%5D) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
Content-Length: 1092

{
    "@odata.context": "[organization uri]/api/data/v9.2/$metadata#contacts(fullname,sample_outdooractivities)",
    "value": [{
        "@odata.etag": "W/\"529811\"",
        "fullname": "Monte Orton",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Hiking",
        "sample_outdooractivities": "2",
        "contactid": "cdbcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529823\"",
        "fullname": "Hiram Mundy",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Hiking; Mountain Climbing; Skiing; Camping",
        "sample_outdooractivities": "2,3,8,9",
        "contactid": "d7bcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529838\"",
        "fullname": "Verna Kennedy",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Hiking; Fishing; Camping",
        "sample_outdooractivities": "2,4,9",
        "contactid": "e6bcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529843\"",
        "fullname": "Marvin Bracken",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Swimming; Hiking; Skiing; Camping",
        "sample_outdooractivities": "1,2,8,9",
        "contactid": "ebbcc48e-0b8d-e711-811c-000d3a75bdf1"
    }]
}

Este exemplo mostra como usar o ContainValues membro para retornar todos os contatos que gostam de caminhadas. A resposta inclui o texto das opções como valor formatado.

public static void WriteContactsWhoLikeHikingExample(IOrganizationService service)
{
    ArgumentNullException.ThrowIfNull(service);

    var likesHikingQuery = new QueryExpression("contact")
    {
        ColumnSet = new ColumnSet("fullname", "sample_outdooractivities"),
        Criteria = new FilterExpression
        {
            Conditions =
            {
                new ConditionExpression(
                    "sample_outdooractivities",
                    ConditionOperator.ContainValues,
                    new int[] { 2 })
            }
        }
    };

    var hikers = service.RetrieveMultiple(likesHikingQuery);

    Console.WriteLine("\nContacts who like Hiking");
    Console.WriteLine("=========================");
    foreach (var contact in hikers.Entities)
    {
        var fullname = contact.GetAttributeValue<string>("fullname") ?? "(no name)";
        var values = contact.FormattedValues.TryGetValue("sample_outdooractivities", out var formattedValue)
            ? formattedValue
            : "null";

        Console.WriteLine($"{fullname} {values}");
    }
}
    /*OUTPUT:
    Contacts who like Hiking
    =========================
    Monte Orton Hiking
    Hiram Mundy Hiking; Mountain Climbing; Skiing; Camping
    Verna Kennedy Hiking; Fishing; Camping
    Marvin Bracken Swimming; Hiking; Skiing; Camping
    */

Código de exemplo usando FetchXml

O código a seguir mostra o uso de FetchXml com API Web e SDK para .NET.

Web API
SDK para .NET

Este exemplo mostra o uso do not-contain-values operador na consulta a seguir FetchXml usando a API Web.

<fetch>
    <entity name='contact'>
        <attribute name='fullname' />
        <attribute name='sample_outdooractivities' />
            <filter type='and'>
                <condition attribute='sample_outdooractivities' operator='not-contain-values'>
                    <value>2</value>
                </condition>
            </filter>
    </entity>
</fetch>

Solicitação:

GET [organization uri]/api/data/v9.2/contacts?fetchXml=%253Cfetch%2520distinct%253D'false'%2520no-lock%253D'false'%2520mapping%253D'logical'%253E%253Centity%2520name%253D'contact'%253E%253Cattribute%2520name%253D'fullname'%2520%252F%253E%253Cattribute%2520name%253D'sample_outdooractivities'%2520%252F%253E%253Cfilter%2520type%253D'and'%253E%253Ccondition%2520attribute%253D'sample_outdooractivities'%2520operator%253D'not-contain-values'%253E%253Cvalue%253E2%253C%252Fvalue%253E%253C%252Fcondition%253E%253C%252Ffilter%253E%253C%252Fentity%253E%253C%252Ffetch%253E HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[organization uri]/api/data/v9.2/$metadata#contacts(fullname,sample_outdooractivities,contactid)",
    "value": [{
        "@odata.etag": "W/\"529806\"",
        "fullname": "Wayne Yarborough",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Swimming; Camping",
        "sample_outdooractivities": "1,9",
        "contactid": "c8bcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529816\"",
        "fullname": "Randal Maple",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Fishing",
        "sample_outdooractivities": "4",
        "contactid": "d2bcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529828\"",
        "fullname": "Barbara Weber",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Swimming; Fishing; Boating",
        "sample_outdooractivities": "1,4,7",
        "contactid": "dcbcc48e-0b8d-e711-811c-000d3a75bdf1"
    }, {
        "@odata.etag": "W/\"529833\"",
        "fullname": "Georgette Sullivan",
        "sample_outdooractivities@OData.Community.Display.V1.FormattedValue": "Fishing; Hunting; Camping",
        "sample_outdooractivities": "4,5,9",
        "contactid": "e1bcc48e-0b8d-e711-811c-000d3a75bdf1"
    }]
}

Este exemplo mostra o uso do operador not-contain-values por meio do uso de FetchExpression com IOrganizationService.RetrieveMultiple.

public static void RetrieveContactsWhoDoNotLikeHikingExample(IOrganizationService service)
{
    ArgumentNullException.ThrowIfNull(service);

    var fetchXml = """
        <fetch>
            <entity name='contact'>
                <attribute name='fullname' />
                <attribute name='sample_outdooractivities' />
                <filter type='and'>
                    <condition attribute='sample_outdooractivities' operator='not-contain-values'>
                        <value>2</value>
                    </condition>
                </filter>
            </entity>
        </fetch>
        """;

    var doesNotLikeHiking = new FetchExpression(fetchXml);
    var nonHikers = service.RetrieveMultiple(doesNotLikeHiking);

    Console.WriteLine("\nContacts who do not like Hiking");
    Console.WriteLine("===============================");
    foreach (var contact in nonHikers.Entities)
    {
        var fullname = contact.GetAttributeValue<string>("fullname") ?? "(no name)";
        var values = contact.FormattedValues.TryGetValue("sample_outdooractivities", out var formattedValue)
            ? formattedValue
            : "null";

        Console.WriteLine($"{fullname} {values}");
    }
}

    /* OUTPUT
    Contacts who do not like Hiking
    ===============================
    Wayne Yarborough Swimming; Camping
    Randal Maple Fishing
    Barbara Weber Swimming; Fishing; Boating
    Georgette Sullivan Fishing; Hunting; Camping 
    */

Criar colunas de opções com código

A maneira mais fácil de criar opções é usar o editor de colunas nas ferramentas de personalização. Saiba como criar e editar colunas.

Se você precisar automatizar a criação desse tipo de coluna, use os exemplos a seguir com a API Web ou o SDK para .NET. Ambos os exemplos criam uma coluna de opções para atividades ao ar livre na contact tabela. Saiba mais sobre como criar colunas.

Web API
SDK para .NET

Envia uma POST solicitação com conteúdo de tipo de entidade MultiSelectPicklistAttributeMetadata para a /Attributes coleção da contact tabela para criar uma coluna como parte de uma solução com o nome exclusivo mySampleSolutionUniqueName. Saiba como associar um componente de solução a uma solução

Solicitação:

POST [organization uri]/api/data/v9.2/EntityDefinitions(LogicalName='contact')/Attributes HTTP/1.1
Accept: application/json
MSCRM.SolutionUniqueName: mySampleSolutionUniqueName
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "@odata.type": "Microsoft.Dynamics.CRM.MultiSelectPicklistAttributeMetadata",
    "SchemaName": "sample_OutdoorActivities",
    "DisplayName": {
        "LocalizedLabels": [
            {
                "Label": "Outdoor activities",
                "LanguageCode": 1033
            }
        ]
    },
    "RequiredLevel": {
        "Value": "None"
    },
    "Description": {
        "LocalizedLabels": [
            {
                "Label": "Outdoor activities that the contact likes.",
                "LanguageCode": 1033
            }
        ]
    },
    "OptionSet": {
        "IsGlobal": false,
        "OptionSetType": "Picklist",
        "Options": [
            {
                "Value": 1,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Swimming", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 2,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Hiking", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 3,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Mountain Climbing", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 4,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Fishing", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 5,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Hunting", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 6,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Running", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 7,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Boating", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 8,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Skiing", "LanguageCode": 1033 }
                    ]
                }
            },
            {
                "Value": 9,
                "Label": {
                    "LocalizedLabels": [
                        { "Label": "Camping", "LanguageCode": 1033 }
                    ]
                }
            }
        ]
    }
}

Resposta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [organization uri]/api/data/v9.2/EntityDefinitions(LogicalName='contact')/Attributes(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Usa CreateAttributeRequest para criar uma coluna MultiSelectPicklistAttributeMetadata na tabela de contatos como parte de uma solução com o nome exclusivo mySampleSolutionUniqueName. Saiba como associar um componente de solução a uma solução

public static Guid CreateOutdoorActivitiesOptionSetExample(IOrganizationService service)
{
    ArgumentNullException.ThrowIfNull(service);

    const int languageCode = 1033; // English

    static OptionMetadata CreateOption(string label, int value, int localeId) =>
        new(new Label(label, localeId), value);

    var outdoorActivitiesAttribute = new MultiSelectPicklistAttributeMetadata
    {
        SchemaName = "sample_OutdoorActivities",
        LogicalName = "sample_outdooractivities",
        DisplayName = new Label("Outdoor activities", languageCode),
        RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
        Description = new Label("Outdoor activities that the contact likes.", languageCode),
        OptionSet = new OptionSetMetadata
        {
            IsGlobal = false,
            OptionSetType = OptionSetType.Picklist,
            Options =
            {
                CreateOption("Swimming", 1, languageCode),
                CreateOption("Hiking", 2, languageCode),
                CreateOption("Mountain Climbing", 3, languageCode),
                CreateOption("Fishing", 4, languageCode),
                CreateOption("Hunting", 5, languageCode),
                CreateOption("Running", 6, languageCode),
                CreateOption("Boating", 7, languageCode),
                CreateOption("Skiing", 8, languageCode),
                CreateOption("Camping", 9, languageCode)
            }
        }
    };

    var createAttributeRequest = new CreateAttributeRequest
    {
        EntityName = "contact",
        Attribute = outdoorActivitiesAttribute,
        SolutionUniqueName = "mySampleSolutionUniqueName"
    };

    var response = (CreateAttributeResponse)service.Execute(createAttributeRequest);
    return response.AttributeId;
}

Consulte também

Definições de coluna
Criar uma linha de tabela usando a API Web
Consultar dados usando a API Web
Trabalhar com definições de coluna
Exemplo: trabalhar com definições de colunas

Comentários

Esta página foi útil?

Última atualização em 2026-10-30

Usar colunas de escolhas para armazenar várias opções

Definir valores da coluna de opções

Consultar dados de colunas Choices

Valores de escolhas sample_outdooractivities

Valores da tabela de contatos

Código de exemplo usando FetchXml

Criar colunas de opções com código

Consulte também

Comentários

Recursos adicionais

Valores de escolhas `sample_outdooractivities`