Personnaliser les options

Article
02/24/2023

En règle générale, vous utilisez des choix généraux (groupes d’options) pour définir des champs afin que différents champs puissent partager le même ensemble d’options, qui sont conservées à un même emplacement. Contrairement aux choix locaux uniquement définis pour une colonne de table spécifique, vous pouvez réutiliser des choix globaux. Vous les verrez également utilisées dans les paramètres de demande de façon similaire à une énumération.

Notes

Seul l’éditeur d’un solution gérée peut importer des modifications qui suppriment une option d’un groupe d’options global. Cela inclut les solutions publiées par Microsoft telles que les groupes d’options globales prêtes à l’emploi. Afin d’apporter des modifications aux groupes d’options, il est nécessaire de mettre à niveau la solution qui a ajouté le groupe d’options. Plus d’informations : Mettre à niveau ou mettre à jour une solution. Les utilisateurs peuvent supprimer manuellement une option dans leur environnement s’ils ne parviennent pas à modifier la solution ou à contacter l’éditeur de la solution, mais cette opération doit être effectuée manuellement sur chaque environnement.

Lorsque vous définissez un choix global en utilisant CreateOptionSetRequest, nous vous recommandons de laisser le système affecter une valeur. Pour ce faire, transmettez une valeur null lorsque vous créez l’instance OptionMetadata. Lorsque vous définissez un choix, il contient un préfixe de valeur de choix spécifique au contexte de l’ensemble d’éditeurs pour la solution dans laquelle le choix est créé. Ce préfixe permet de réduire le risque de créer des choix en double pour un solution gérée, et dans tous les choix définis dans les organisations où votre solution gérée est installé. Pour plus d’informations, consultez Fusionner des options de choix.

Vous pouvez télécharger l’exemple de code complet ici.

Classes de demande de message

Utilisez les classes de demande de message suivantes pour travailler avec des choix globaux.

Utilisez les classes de demande de message suivantes pour travailler avec les choix globaux et locaux.

Récupérer un choix global

L’exemple de code suivant montre comment récupérer un choix global par nom à l’aide du message RetrieveOptionSetRequest :

// 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 =
    (RetrieveOptionSetResponse)svc.Execute(
    retrieveOptionSetRequest);

Console.WriteLine("Retrieved {0}.",
    retrieveOptionSetRequest.Name);

// Access the retrieved OptionSetMetadata.
OptionSetMetadata retrievedOptionSetMetadata =
    (OptionSetMetadata)retrieveOptionSetResponse.OptionSetMetadata;

// Get the current options list for the retrieved attribute.
OptionMetadata[] optionList =
    retrievedOptionSetMetadata.Options.ToArray();

Créer un choix global

Utilisez le message CreateOptionSetRequest pour créer un choix global. Met la propriété IsGlobal à true pour indiquer que le choix est global. L’exemple de code suivant crée un choix global appelé « Exemple de groupe d’options » :

// 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 =
    (CreateOptionSetResponse)svc.Execute(createOptionSetRequest);

Créer un choix qui utilise un choix global

L’exemple suivant montre comment créer une colonne de choix qui utilise un choix global avec 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
        }
    }
};

svc.Execute(createRequest);

Mettre à jour un choix global

L’exemple de code suivant montre comment mettre à jour l’étiquette d’un choix global à l’aide de 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
    }
};

svc.Execute(updateOptionSetRequest);

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

Ordre des options

L’exemple de code suivant montre comment ordonner les options d’un choix global à l’aide de 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
svc.Execute(orderOptionRequest);

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

Récupérer tous les choix globaux

L’exemple de code suivant montre comment récupérer tous les choix globaux à l’aide de RetrieveAllOptionSetsRequest :

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

// Execute the request
RetrieveAllOptionSetsResponse retrieveAllOptionSetsResponse =
    (RetrieveAllOptionSetsResponse)svc.Execute(
    retrieveAllOptionSetsRequest);

// 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
        retrieveAllOptionSetsResponse.OptionSetMetadata)
    {
        Console.WriteLine("{0} {1}", count++,
            (optionSetMetadata.DisplayName.LocalizedLabels.Count >0)? optionSetMetadata.DisplayName.LocalizedLabels[0].Label : String.Empty);
    }
}

Supprimer un choix global

L’exemple de code suivant montre comment vérifier si un choix global est utilisé par un autre composant de solution en utilisant un message RetrieveDependentComponents (RetrieveDependentComponents Function ou RetrieveDependentComponentsRequest), puis comment le supprimer en utilisant le message DeleteOptionSet (pour le SDK pour .NET, utilisez 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 =
    (RetrieveDependentComponentsResponse)svc.Execute(
    dependencyRequest);

// 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"
};

svc.Execute(deleteAttributeRequest);

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
};

svc.Execute(deleteRequest);

Voir aussi

Créer et mettre à jour des choix à l’aide de l’API Web