AutoWert-Spalten erstellen

Artikel
05/04/2024

Mit Microsoft Dataverse können Sie eine AutoWert-Spalte für eine beliebige Tabelle hinzufügen. Weitere Informationen zum Erstellen von AutoWert-Spalten in Power Apps finden Sie in AutoWert-Spalten.

Dieser Artikel erläutert, wie Sie AutoWert-Spalten programmgesteuert erstellen und einen Startwert für sequenzielle Elemente festlegen können. Außerdem wird im Artikel gezeigt, wie die Sequenznummer für den nächsten Datensatz festgelegt wird, wenn Sie später den Startwert jederzeit zurücksetzen müssen.

Hinweis

Die Einstellung des Startwerts ist optional. Es ist nicht erforderlich, den Startwert anzurufen, wenn Sie ihn nicht erneut festlegen müssen.

Sie können eine AutoWert-Spalte auf die gleiche Weise erstellen, wie Sie eine Zeichenfolgen-Spalte mit der StringAttributeMetadata-Klasse erstellen, außer dass Sie die AutoNumberFormat-Eigenschaft verwenden. Verwenden Sie die AutoNumberFormat-Eigenschaft, um ein Muster zu definieren, das Sequenznummern und zufällige Zeichenfolgen beim Zusammenstellen der Platzhalter enthält, die die Länge und den Typ der generierten Werte angeben. Die zufälligen Zeichenfolgen helfen Ihnen, Duplikate oder Kollisionen zu vermeiden, besonders wenn Offline-Clients versuchen, AutoWerte zu erstellen.

Wenn Sie eine AutoWert-Spalte erstellen, müssen die Werte der FormatName-Eigenschaft oder der Format-Eigenschaft Text sein. Da diese Werte die Standardwerte sind, legen Sie in der Regel diese Eigenschaft nicht fest. Sie können keine AutoWert-Spalte erstellen, die jedes andere besondere Format wie Email, Phone, TextArea, Url oder andere vorhandene Formate verwendet.

SQL generiert das sequenzielle Segment und garantiert die Eindeutigkeit.

Hinweis

Sie können eine bestehende Formattext-Spalte so ändern, dass sie ein AutoWert-Format ist.

In modellgesteuerten Apps, die die einheitliche Benutzeroberfläche verwenden, müssen Steuerelemente, die an eine AutoWert-Spalte gebunden sind, explizit als deaktiviert festgelegt werden. Wenn Sie den Anfangswert der Spalte nicht im Formular festlegen, wird der Wert erst nach dem Speichern der Tabelle festgelegt. Die automatische Nummerierung kann auf Spaltenwerte in Ansichten, Rastern usw. angewendet werden.

Beispiele

Die folgenden Beispiele zeigen, wie Sie eine neue AutoWert-Spalte namens new_SerialNumber für eine benutzerdefinierte Tabelle namens new_Widget erstellen, die mithilfe der Web-API und dem Dataverse-SDK für .NET einen Wert hat, der wie folgt aussieht: WID-00001-AB7LSFG-20170913070240.

Web-API
SDK für .NET

Sie können Tabellendefinitionen über die Web-API erstellen und aktualisieren. Weitere Informationen: Erstellen und Aktualisieren von Tabellendefinitionen mit der Web-API.

Anforderung:

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
}

Antwort:

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)

Verwendung der SDK für .NET-Klassen CreateAttributeRequest und StringAttributeMetadata:

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

Hinweis

AutoWert-Werte werden von der Datenbank beim Starten des Datensatzes vorab ausgewählt. Wenn ein Datensatz gestartet, dann aber storniert wird, wird die zugewiesene Zahl nicht verwendet. Wenn während dieser Zeit ein weiterer Datensatz mit der folgenden sequenziellen Zahl fertiggestellt wird, können Lücken in der automatischen Nummerierung von Datensätzen auftreten.

AutoNumberFormat-Optionen

Diese Beispiele zeigen, wie Sie die AutoNumberFormat-Eigenschaft konfigurieren können, um verschiedene Ergebnisse zu erhalten:

AutoNumberFormat-Wert	Beispielwert
`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`

Die Platzhalter für zufällige Zeichenfolgen sind optional. Sie können mehr als einen Platzhalter für zufällige Zeichenfolgen einfügen. Verwenden Sie einen der Formatwerte für Datums- und Zeitplatzhalter aus Standard-Datums- und Zeitformatzeichenfolgen.

Zeichenfolgenlänge

Die Tabelle stellt den Zeichenfolgenlängenwert für die zufälligen und sequenziellen Platzhalter dar.

Platzhalter	Zeichenfolgenlänge	Ausgabeszenario
`{RANDSTRING:MIN_LENGTH}`	Der Wert von `MIN_LENGTH` liegt zwischen 1 und 6.	Wenn Sie die Zeile speichern, wird die AutoWert-Spalte die zufällige Zeichenfolge mit der bestimmten Länge generieren, wenn der Wert zwischen 1 und 6 liegt. Wenn Sie den `MIN_LENGTH`-Wert von 7 oder höher verwenden, sehen Sie einen Fehler des falschen Arguments.
`{SEQNUM:MIN_LENGTH}`	Der Minimalwert Wert der `MIN_LENGTH` ist 1. Die Nummer wächst inkrementell über die minimale Länge hinaus.	Wenn Sie die Zeile speichern, funktioniert AutoWert-Spalte perfekt und wird weiter bei höheren Werten von `MIN_LENGTH` perfekt funktionieren.

Für sequenzielle Wertplatzhalter ist die MIN_LENGTH eine minimale Länge. Wenn Sie den Wert auf 2 setzen, ist der Anfangswert 01 und der Wert der 100. Zeile ist 100. Die Nummer wächst inkrementell über die minimale Länge hinaus. Das Festlegen der Länge für sequenzielle Werte dient dazu, eine konsistente Länge für den automatisch generierten Wert festzulegen, indem weitere 0s zum Anfangswert hinzugefügt werden. Es schränkt den absoluten Wert nicht ein. Zufallswertplatzhalter sind immer gleich lang.

Da die sequenziellen Werte höher als die minimale Länge, die dafür eingeräumt ist, werden können, sollten Sie die StringAttributeMetadata.MaxLength-Eigenschaft nicht anpassen, um der Länge Ihres formatierten Werts zu entsprechen. Es gibt einen geringen Wert, diese Eigenschaft festzulegen, und es könnte zu einem Fehler in der Zukunft führen, wenn der Wert den MaxLength-Wert überschreitet. Stellen Sie sicher, dass Sie genug Raum für einen realistischen Bereich von sequenziellen Werten gelassen haben.

Hinweis

Es gibt keine Validierung der Platzhalterwerte, wenn Sie die Spalte erstellen. Dieser Fehler wird nur dann angezeigt, wenn Sie versuchen, eine Tabelle zu speichern, die einen falsch konfigurierten AutoNumberFormat-Wert verwendet. Wenn Sie z. B. die Länge der zufälligen Zeichenfolge mit mehr als 6 angeben, erhält derjenige, der eine neue Tabelle erstellt, einen Fehler „Ungültiges Argument“, wenn er zum ersten Mal versucht, die Tabelle zu speichern, die die neue Autonummern-Spalte enthält.

Autonummern-Spalten aktualisieren

Wenn Sie eine AutoWert-Spalte für eine fehlerhafte Konfiguration erstellen, oder wenn Sie eine vorhandene AutoWert-Spalte ändern möchten, können Sie die Spalte des AutoNumberFormat-Werts aktualisieren.

Der folgende Codeschnipsel zeigt, wie die AutoWert-Spalte mit dem SDK für .NET abgerufen, geändert und aktualisiert wird:

Um eine vorhandene AutoWert-Spalte zu ändern, müssen Sie die Spalte mithilfe der RetrieveAttributeRequest-Klasse abrufen.

// 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);

Nachdem Sie die AutoWert-Spalte abgerufen haben, müssen Sie die Spalte ändern und aktualisieren.

//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);

Einen Startwert festlegen

Standardmäßig beginnen alle fortlaufenden Autonummern mit 1000 und verwenden 0 als Präfix, je nach Länge. Deswegen ist die Länge des Werts immer gleich. Wenn Sie den Anfangswert ändern möchten, müssen Sie den ursprünglichen Startwert mithilfe der SetAutoNumberSeed-Nachricht ändern, um die nächste Nummer festzulegen, die für das sequenzielle Segment verwendet wird.

Zum Beispiel, wenn die Länge der sequenziellen Nummer 5 ist, möchten Sie vielleicht ab einem Anfangswert von 10.000 anstelle des Standardwerts von 00001 beginnen. Wenn Sie nach dem Erstellen der AutoWert-Spalte einen anderen Startwert wählen wollen, verwenden Sie die SetAutoNumberSeed-Nachricht. Verwenden Sie die SetAutoNumberSeedRequest-Klasse beim Verwenden der SDK-Assemblys und die SetAutoNumberSeed-Aktion beim Verwenden der Web-API.

Die AutoNumberSeed-Nachricht hat die folgenden Parameter:

Name	Typ	Beschreibung
`EntityName`	Zeichenfolge	Der logische Name der Tabelle, die die Spalte enthält, für die Sie den Startwert festlegen wollen.
`AttributeName`	Zeichenfolge	Der logische Name der Spalte, für die Sie den Startwert festlegen wollen.
`Value`	Int	Nächster AutoWert-Wert für die Spalte.

Hinweis

Das Festlegen des Startwerts ändert nur den aktuellen Zahlenwert für die angegebene Spalte in der aktuellen Umgebung. Es impliziert keinen allgemeinen Startwert für die Spalte. Der Startwert ist nicht in einer Lösung enthalten, wenn er in einer anderen Umgebung installiert ist. Um die Startzahl nach dem Import einer Lösung festzulegen, verwenden Sie SetAutoNumberSeed-Nachricht in der Zielumgebung.

SetAutoNumberSeed-Beispiele

Die folgenden Beispiele legen den Startwert bis 10.000 für eine AutoWert-Spalte namens new_SerialNumber für eine benutzerdefinierte Tabelle namens new_Widget fest.

Web-API
SDK für .NET

Verwenden der SetAutoNumberSeed-Aktion der Web-API.

Anforderung:

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
}

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0

Weitere Informationen: Verwenden der Web-API-Aktionen > Ungebundene Aktionen

Verwenden der SetAutoNumberSeedRequest-Klasse:


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

Community-Tools

Automatischer Nummerierungsmanager

Der Auto Number Manager für XrmToolBox ist ein Community-gesteuertes Tool für Dataverse, das eine Benutzeroberfläche zum Festlegen, Aktualisieren und Entfernen des Formats von AutoWerten für neue oder vorhandene Spalten bietet.

Weitere Informationen finden Sie im Entwicklertools Artikel für Community entwickelte Tools und anm.xrmtoolbox.com zum automatischen Zahlen-Manager.

Hinweis

Die Communitytools sind kein Produkt von Dataverse, und es wird kein Support für die Communitytools angeboten. Wenn Sie Fragen zu dem Tool haben, setzen Sie sich bitte mit dem Herausgeber in Verbindung. Weitere Informationen: XrmToolBox.

Siehe auch

Arbeiten mit Tabellendefinitionen über Code
Anpassen von Tabellendefinitionen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

AutoWert-Spalten erstellen

Beispiele

AutoNumberFormat-Optionen

Zeichenfolgenlänge

Autonummern-Spalten aktualisieren

Einen Startwert festlegen

SetAutoNumberSeed-Beispiele

Community-Tools

Automatischer Nummerierungsmanager

Siehe auch

Zusätzliche Ressourcen