オートナンバー列を作成する

[アーティクル]
05/04/2024

Microsoft Dataverse では、任意のテーブルにオートナンバー列を追加することができます。 Power Apps にオートナンバー列を作成するには、オートナンバー列を参照してください。

この記事では、プログラムでオートナンバー列を作成してシーケンシャル要素のシード値を設定する方法を説明します。また、後からシードをリセットする必要がある場合はいつでも、次のレコードにシーケンス番号を設定する方法についての記事を表示します。

注意

シードの設定は任意です。リシードする必要がない場合、シードを呼び出す必要はありません。

オートナンバー列は、新しい AutoNumberFormat プロパティを使用する以外は、StringAttributeMetadata クラスを使用して文字列カラムを作成するのと同じ方法で作成できます。プレースホルダーを構成することにより、シーケンス番号およびランダム文字列を含むパターンを定義するために、AutoNumberFormat プロパティを使用します。これにより生成される値の長さと種類を表示します。特にオフラインのクライアントが自動付番を作成しようとしている場合、ランダム文字列は重複または競合を回避するのに役立ちます。

オートナンバー列を作成する際は、FormatName プロパティまたは Format プロパティの値は Text である必要があります。これらの値は既定値なので、通常はこのプロパティを設定することはありません。 Email、Phone、TextArea、Url のような他の特別な書式や、他の既存の書式を使用するオートナンバー列を作成することはできません。

SQL は、一意性を保証する連続セグメントを生成します。

注意

既存の形式テキスト列をオートナンバー形式に変更することができます。

Unified Interface を使用したモデル駆動型アプリでは、オートナンバー列にバインドされたコントロールを明示的に無効として設定する必要があります。フォーム上で列の初期値を設定しなかった場合、テーブルを保存した後にのみ値が設定されます。オートナンバー処理は、ビューやグリッドなどの列の値に適用することができます。

使用例

次の例は、次のような値を持つ new_Widget というカスタムテーブルに new_SerialNumber という新しいオートナンバー列を作成する方法を示しています: Web API と Dataverse SDK for .NETを使用して WID-00001-AB7LSFG-20170913070240 を作成します。

Web API
.NET 用 SDK

Web API を使用してテーブル定義を作成・更新することができます。詳細情報: Web API を使用してテーブルの定義を作成・更新する。

要求:

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
}

応答:

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)

.NET CreateAttributeRequest 用 SDK の使用および 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);

注意

オートナンバー値は、レコードの開始時にデータベースによって事前に選択されます。レコードを開始してからキャンセルした場合、割り当てられた番号は使用されません。この間に次の連続番号を持つ別のレコードが完了した場合は、レコードの自動付番にギャップが生じます。

AutoNumberFormatオプション

これらの例は、異なる結果を取得するための AutoNumberFormat プロパティの設定方法を示します:

AutoNumberFormat 値	入力値の例
`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`

ランダムな文字列のプレースホルダーはオプションです。複数のランダム文字列プレースホルダーを含めることができます。標準日付と時刻のフォーマット文字列の datetime プレースホルダーのフォーマット値のいずれかを使用します。

文字列の長さ

次の表は、ランダムおよびシーケンスプレースホルダーの文字列の長さの値を示します。

プレースホルダー	文字列の長さ	シナリオを出力
`{RANDSTRING:MIN_LENGTH}`	`MIN_LENGTH` の値は1 ~ 6の間です。	行を保存する際に、値が1 ~ 6の間の場合、オートナンバー列は定義された長さの任意の文字列を生成します。 7または7を超える場合に `MIN_LENGTH` 値を使用すると、｢無効な引数｣エラーが発生します。
`{SEQNUM:MIN_LENGTH}`	`MIN_LENGTH` の最小値は1です。数は、最小長を超えて増加し続けます。	行を保存する際に、`MIN_LENGTH` の数値がより大きい場合に、オートナンバー列は良好に動作し、かつ良好に動作し続けます。

シーケンス値のプレースホルダーの場合、MIN_LENGTH が最小長です。 2 になるように値を設定する場合、初期値は 01 で、100 番目の行の値は 100 です。数は、最小長を超えて増加し続けます。シーケンス値の長さの設定する際は、初期値に追加の 0 を追加することにより、自動生成された値に対して一定の長さを確立します。絶対値は制限されません。ランダム値のプレースホルダーは常に同じ長さです。

シーケンス値が割り当てられた最小長より大きくなるため、StringAttributeMetadata.MaxLength プロパティを調整してフォーマットされた値の長さに合わせる必要はありません。このプロパティを設定する価値はほとんどなく、将来、値が MaxLength 値を超えた場合にエラーを引き起こす可能性があります。シーケンス値の現実的な範囲に対して十分な余裕を残しているか確認します。

注意

カラムを作成する際は、プレースホルダーの値の検証は行われません。エラーは、誤って設定されている AutoNumberFormat 値を使用するテーブルを保存しようとするときにのみ表示されます。たとえば、ランダムな文字列の長さを 6 以上に指定した場合、新しいテーブルを作成したユーザーが、新しいオートナンバー列を含むテーブルを最初に保存しようとすると、無効な引数エラーが発生します。

オートナンバー列を更新する

正しくない構成でオートナンバー列を作成するか、または既存のオートナンバー列を変更したい場合、AutoNumberFormat 値の列を更新できます。

次のコードスニペットは、SDK for .NETを使用して、autonumber 列を取得、変更、更新する方法を示しています:

既存のオートナンバー列を変更するには、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);

次のコードスニペットでは、オートナンバー列の取得、変更、および更新について説明しています。

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

シード値の設定

既定では、すべての自動付番のシーケンス値は 1000 から始まり、長さに応じて接頭辞は 0 を使います。このように、値の長さは常に同じです。初期値を変更したい場合は、SetAutoNumberSeed メッセージを使用して初期シード値を変更し、シーケンシャルセグメントに使用される次の番号を設定する必要があります。

たとえば、シーケンス番号の長さが 5 の場合、既定値の 00001 ではなく 10000 の初期値から開始することができます。自動採番列を作成した後に別の開始値を選択したい場合は、SetAutoNumberSeed メッセージを使用してください。 Web APIを使用する際に、SDKアセンブリと SetAutoNumberSeed アクションを使用する場合は、 SetAutoNumberSeedRequest クラスを使用します。

AutoNumberSeed メッセージには以下のパラメーターがあります:

名前	タイプ	説明
`EntityName`	文字列	シードを設定する列を含むテーブルの論理名です。
`AttributeName`	文字列	シードを設定する列の論理名です。
`Value`	int	列の次のオートナンバーの値です。

注意

シードを設定しても、現在の環境では、指定した列の現在の数値が変わるだけです。これは列の共通の 開始値 を意味するものではありません。異なる環境にインストールされるとき、シード値はソリューションに含まれません。開始番号をソリューションのインポート後に設定するには、ターゲット環境内の SetAutoNumberSeed メッセージを使用します。

SetAutoNumberSeed の例

次のサンプルでは、new_Widget というカスタムテーブルの new_SerialNumber という名前のオートナンバー列で、シードを 10000 に設定します。

Web API
.NET 用 SDK

Web API SetAutoNumberSeed アクションを使用します。

要求:

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
}

応答:

HTTP/1.1 204 No Content
OData-Version: 4.0

詳細: Web API アクションを使用 > アンバインドされたアクション

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

コミュニティツール

自動付番マネージャ

XrmToolBox 用**自動付番マネージャー** は、新規または既存の列にオートナンバーフォーマットを設定、更新、削除する UI を提供する Dataverse 用のコミュニティ駆動のツールです。

自動付番マネージャの詳細については、コミュニティ開発ツールの開発者ツールの記事および anm.xrmtoolbox.com を参照してください。

注意

コミュニティツールは Dataverse の製品ではなく、コミュニティツールのサポートを拡張するものではありません。このツールに関するご質問は、その発行元にお問い合わせください。詳細: XrmToolBox。

次の方法で共有

オートナンバー列を作成する

使用例

AutoNumberFormatオプション

文字列の長さ

オートナンバー列を更新する

シード値の設定

SetAutoNumberSeed の例

コミュニティツール

自動付番マネージャ

関連項目

その他のリソース

次の方法で共有

オートナンバー列を作成する

使用例

AutoNumberFormatオプション

文字列の長さ

オートナンバー列を更新する

シード値の設定

SetAutoNumberSeed の例

コミュニティ ツール

自動付番マネージャ

関連項目

その他のリソース

コミュニティツール