Créer des colonnes de numérotation automatique

Article
05/09/2024

Avec Microsoft Dataverse, vous pouvez ajouter une colonne de numérotation automatique pour n’importe quelle table. Pour créer des colonnes à numérotation automatique dans Power Apps, voir Colonnes à numérotation automatique.

Cet article explique comment créer par programme une colonne à numérotation automatique et définir une valeur initiale pour les éléments séquentiels. En outre, cet article explique comment définir le numéro séquentiel de l’enregistrement suivant si vous devez réinitialiser la valeur initiale ultérieurement.

Notes

Le paramétrage de la valeur de départ est facultatif. Il n’est pas nécessaire d’appeler la valeur de départ si vous n’effectuez pas de réinitialisation.

Vous pouvez créer une colonne à numérotation automatique de la même façon que vous créez une colonne de chaîne avec la classe StringAttributeMetadata à ceci près que vous utilisez la nouvelle propriété AutoNumberFormat. Utilisez la propriété AutoNumberFormat pour définir un modèle contenant des numéros séquentiels et des chaînes aléatoires en composant des espaces réservés qui indiquent la longueur et le type de valeurs générées. Les chaînes aléatoires vous aident à éviter les doublons ou les collisions, surtout quand les clients hors connexion essaient de créer des numéros automatiques.

Lorsque vous créez une colonne à numérotation automatique, les valeurs de la propriété FormatName ou de la propriété Format doivent être Text. Comme il s’agit des valeurs par défaut, il n’est pas généralement nécessaire de définir cette propriété. Vous ne pouvez pas créer de colonne à numérotation automatique qui utilise tout autre format spécial, par exemple Email, Phone, TextArea, Url ou tout autre format existant.

SQL génère le segment séquentiel qui garantit l’unicité.

Notes

Vous pouvez modifier une colonne de texte de format existant en format de numérotation automatique.

Dans les applications pilotées par modèle qui utilisent Unified Interface, les contrôles liés à une colonne à numérotation automatique doivent être explicitement définis comme désactivés. Si vous ne définissez pas la valeur de la colonne initiale sur le formulaire, la valeur n’est définie qu’après avoir enregistré la table. La numérotation automatique peut être appliquée aux valeurs de colonne dans les vues, grilles, etc.

Examples

Les exemples suivants montrent comment créer une colonne à numérotation automatique nommée new_SerialNumber pour une table personnalisée nommée new_Widget dont la valeur se présente comme suit : WID-00001-AB7LSFG-20170913070240 à l’aide de l’API web et du Kit de développement logiciel (SDK) Dataverse pour .NET.

API web
SDK pour .NET

Vous pouvez créer et mettre à jour les définitions de table à l’aide de l’API web. Pour plus d’informations, voir Créer et mettre à jour les définitions de table à l’aide de l’API web.

Demande :

POST [Organization URI]/api/data/v9.0/EntityDefinitions(LogicalName='new_widget')/Attributes HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "AttributeType": "String",
 "AttributeTypeName": {
  "Value": "StringType"
 },
 "Description": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number of the widget.",
    "LanguageCode": 1033
   }
  ]
 },
 "DisplayName": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number",
    "LanguageCode": 1033
   }
  ]
 },
 "RequiredLevel": {
  "Value": "None",
  "CanBeChanged": true,
  "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
 },
 "SchemaName": "new_SerialNumber",
 "AutoNumberFormat": "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
 "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
 "FormatName": {
  "Value": "Text"
 },
 "MaxLength": 100
}

Réponse :

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/EntityDefinitions(402fa40f-287c-e511-80d2-00155d2a68d2)/Attributes(f01bef16-287c-e511-80d2-00155d2a68d2)

Utilisation des classes CreateAttributeRequest et StringAttributeMetadata pour le SDK pour .NET :

string conn = $@"
    Url = {url};
    AuthType = OAuth;
    UserName = {userName};
    Password = {password};
    AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
    RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
    LoginPrompt=Auto;
    RequireNewInstance = True";

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

var widgetSerialNumberAttributeRequest = new CreateAttributeRequest
  {
    EntityName = "newWidget",
    Attribute = new StringAttributeMetadata
      {
        //Define the format of the column
        AutoNumberFormat = "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
        LogicalName = "new_serialnumber",
        SchemaName = "new_SerialNumber",
        RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
        // The MaxLength defined for the string column must be greater than the length of the 
        // AutoNumberFormat value, that is, it should be able to fit in the generated value.
        MaxLength = 100, 
        DisplayName = new Label("Serial Number", 1033),
        Description = new Label("Serial Number of the widget.", 1033)
      }
  };
  service.Execute(widgetSerialNumberAttributeRequest);

Notes

Les valeurs de numérotation automatique sont présélectionnées par la base de données quand l’enregistrement démarre. Si un enregistrement a démarré mais a été annulé, le numéro qui a été attribué n’est pas utilisé. Si, pendant ce temps, un autre enregistrement contient le numéro séquentiel suivant, il existe alors des écarts dans la numérotation automatique des enregistrements.

Options AutoNumberFormat

Ces exemples montrent comment configurer la propriété AutoNumberFormat pour obtenir différents résultats :

Valeur AutoNumberFormat	Valeur d’exemple
`CAR-{SEQNUM:3}-{RANDSTRING:6}`	`CAR-123-AB7LSF`
`CNR-{RANDSTRING:4}-{SEQNUM:4}`	`CNR-WXYZ-1000`
`{SEQNUM:6}-#-{RANDSTRING:3}`	`123456-#-R3V`
`KA-{SEQNUM:4}`	`KA-0001`
`{SEQNUM:10}`	`1234567890`
`QUO-{SEQNUM:3}#{RANDSTRING:3}#{RANDSTRING:5}`	`QUO-123#ABC#PQ2ST`
`QUO-{SEQNUM:7}{RANDSTRING:5}`	`QUO-0001000P9G3R`
`CAS-{SEQNUM:6}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}`	`CAS-002000-S1P0H0-20170913091544`
`CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMMddhh}-{RANDSTRING:6}`	`CAS-002002-2017091309-HTZOUR`
`CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMM}-{RANDSTRING:6}-{DATETIMEUTC:hhmmss}`	`CAS-002000-201709-Z8M2Z6-110901`

Les espaces réservés de chaîne aléatoires sont facultatifs. Vous pouvez inclure plusieurs espaces réservés de chaîne aléatoires. Utilisez l’une des valeurs de format pour les espaces réservés de date et d’heure qui sont disponibles dans Chaînes de format de date et d’heure.

Longueur de chaîne

Le tableau indique la valeur de longueur de chaîne pour les espaces réservés aléatoires et séquentiels.

Espace réservé	Longueur de chaîne	Scénario de sortie
`{RANDSTRING:MIN_LENGTH}`	La valeur de `MIN_LENGTH` est comprise entre 1 et 6.	Quand vous enregistrez la ligne, la colonne de numérotation automatique génère la chaîne aléatoire avec la longueur définie si la valeur est comprise entre 1 et 6. Si vous définissez la valeur `MIN_LENGTH` sur 7 ou plus, une erreur Argument non valide s’affiche.
`{SEQNUM:MIN_LENGTH}`	La valeur minimale de `MIN_LENGTH` est 1. Le nombre continue à incrémenter au-delà de la longueur minimale.	Quand vous enregistrez la ligne, la colonne de numérotation automatique fonctionne correctement et continuera à fonctionner correctement pour les valeurs plus grandes de `MIN_LENGTH`.

Pour les espaces réservés à valeur séquentielle, la valeur MIN_LENGTH est une longueur minimale. Si vous définissez la valeur sur 2, la valeur initiale est 01, et la valeur de la 100e ligne est 100. Le nombre continue à incrémenter au-delà de la longueur minimale. La définition de la longueur des valeurs séquentielles permet de créer une longueur cohérente pour la valeur générée automatiquement en ajoutant plus de 0 à la valeur initiale. Elle ne limite pas la valeur absolue. Les espaces réservés à valeur aléatoire ont toujours la même longueur.

Comme les valeurs séquentielles peuvent être plus grandes que la longueur minimale qui leur est allouée, vous ne devez pas ajuster la propriété StringAttributeMetadata.MaxLength pour la faire correspondre à la longueur de votre valeur mise en forme. Il y a peu d’intérêt à définir cette propriété et cela pourrait entraîner une erreur dans l’avenir si la valeur dépasse la valeur MaxLength. Pensez à laisser suffisamment d’espace pour une plage réaliste de valeurs séquentielles.

Notes

Les valeurs d’espace réservé ne sont pas validées lorsque vous créez la colonne. L’erreur apparaît uniquement lorsque vous essayez d’enregistrer une table qui utilise une valeur AutoNumberFormat configurée de manière incorrecte. Par exemple, si vous spécifiez la longueur de la chaîne aléatoire sur une valeur supérieure à 6, la première personne qui crée une nouvelle table obtient une erreur Argument non valide lorsqu’elle essaie d’enregistrer la table contenant la nouvelle colonne de numérotation automatique.

Mettre à jour des colonnes de numérotation automatique

Si vous créez une colonne de numérotation automatique avec une configuration incorrecte ou si vous souhaitez modifier une colonne de numérotation automatique existant, vous pouvez mettre à jour la valeur AutoNumberFormat de la colonne.

L’extrait de code suivant vous montre comment récupérer, modifier et mettre à jour la colonne à numérotation automatique à l’aide du Kit de développement logiciel (SDK) pour .NET.

Pour modifier une colonne à numérotation automatique existante, vous devez récupérer la colonne à l’aide de la classe RetrieveAttributeRequest.

// Create the retrieve request
var attributeRequest = new RetrieveAttributeRequest
  {
    EntityLogicalName = entityName.ToLower(),
    LogicalName = "new_serialnumber",
    RetrieveAsIfPublished = true
  };
// Retrieve attribute response
var attributeResponse = (RetrieveAttributeResponse)_serviceProxy.Execute(attributeRequest);

Après avoir récupéré la colonne de numérotation automatique, vous devez modifier et mettre à jour la colonne.

//Modify the retrieved autonumber column
AttributeMetadata retrievedAttributeMetadata = attributeResponse.AttributeMetadata;
//Modify the existing column by writing the format as per your requirement
retrievedAttributeMetadata.AutoNumberFormat = "CAR-{RANDSTRING:5}{SEQNUM:6}";  

// Update the autonumber column            
var updateRequest = new UpdateAttributeRequest
  {
    Attribute = retrievedAttributeMetadata,
    EntityName = "newWidget",
  };
// Execute the request
_serviceProxy.Execute(updateRequest);

Définir une valeur de départ

Par défaut, toutes les valeurs séquentielles de numérotation automatique commencent par 1000 et utilisent 0 comme préfixe selon la longueur. Ainsi, la longueur de la valeur est toujours la même. Si vous voulez modifier la valeur initiale, vous devez modifier la valeur initiale à l’aide du message SetAutoNumberSeed pour définir le numéro suivant utilisé pour le segment séquentiel.

Par exemple, si la longueur du numéro séquentiel est 5, vous pouvez commencer par une valeur initiale de 10 000 au lieu de la valeur par défaut 00001. Si vous souhaitez choisir une autre valeur initiale après avoir créé la colonne à numérotation automatique, utilisez le message SetAutoNumberSeed. Utilisez la classe SetAutoNumberSeedRequest lorsque vous utilisez les assemblys du SDK et l’action SetAutoNumberSeed lorsque vous utilisez l’API web.

Le message AutoNumberSeed a les paramètres suivants :

Nom	Type	Description
`EntityName`	string	Nom logique de la table contenant la colonne dont vous souhaitez définir la valeur de départ.
`AttributeName`	string	Nom logique de la colonne dont vous souhaitez définir la valeur de départ.
`Value`	int	Valeur de numérotation automatique suivante pour la colonne.

Notes

La définition d’une valeur de départ permet de ne changer que la valeur numérique actuelle pour la colonne spécifiée dans l’environnement actuel. Elle ne requiert pas une valeur de départ commune pour la colonne. La valeur de départ n’est pas incluse dans une solution en cas d’installation dans différents environnements. Pour définir le numéro de départ après l’importation d’une solution, utilisez le message SetAutoNumberSeed dans l’environnement cible.

Exemples SetAutoNumberSeed

Les exemples suivants définissent la valeur de départ sur 10 000 pour une colonne de numérotation automatique nommée new_SerialNumber pour une table personnalisée nommée new_Widget.

API web
SDK pour .NET

Utilisation de l’action SetAutoNumberSeed de l’API web

Demande :

POST [Organization URI]/api/data/v9.0/SetAutoNumberSeed HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "EntityName": "new_Widget",
 "AttributeName": "new_Serialnumber",
 "Value": 10000
}

Réponse :

HTTP/1.1 204 No Content
OData-Version: 4.0

Pour plus d’informations : Utiliser les actions de l’API Web > Actions non liées

À l’aide de la classe SetAutoNumberSeedRequest :


string conn = $@"
    Url = {url};
    AuthType = OAuth;
    UserName = {userName};
    Password = {password};
    AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
    RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
    LoginPrompt=Auto;
    RequireNewInstance = True";

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

//Define the seed 
SetAutoNumberSeedRequest req = new SetAutoNumberSeedRequest();
req.EntityName = "newWidget";
req.AttributeName = "newSerialnumber";
req.Value = 10000;
service.Execute(req);

Outils de la communauté

Gestionnaire de numérotation automatique

Le gestionnaire de numérotation automatique pour XrmToolBox est un outil basé sur la communauté pour Dataverse qui fournit une interface utilisateur pour définir, mettre à jour et supprimer le format de numérotation automatique dans des colonnes nouvelles ou existantes.

Lisez l’article Outils pour développeurs pour les outils développés par la communauté et anm.xrmtoolbox.com pour plus d’informations concernant Auto Number Manager.

Notes

Les outils de la communauté ne sont pas un produit de Dataverse et n’étendent pas le support aux outils de la communauté. Si vous avez des questions relatives à cet outil, contactez l′éditeur. Pour plus d′informations : XrmToolBox.

Voir aussi

Utiliser des définitions de table avec du code
Personnaliser les définitions de table

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Partager via

Créer des colonnes de numérotation automatique

Examples

Options AutoNumberFormat

Longueur de chaîne

Mettre à jour des colonnes de numérotation automatique

Définir une valeur de départ

Exemples SetAutoNumberSeed

Outils de la communauté

Gestionnaire de numérotation automatique

Voir aussi

Ressources supplémentaires