自動付番の属性を作成

Dynamics 365 Customer Engagement (on-premises) バージョン 9 リリースでは、任意のエンティティに自動採番属性を追加できます。 現在、属性はプログラムで追加できます。 このタイプの属性を追加するためのユーザー・インターフェースはありません。 この記事では、プログラムで自動採番属性を作成し、シーケンシャル エレメントのシード値を設定する方法について説明します。 さらに、この記事では、後でシードをリセットする必要がある場合に、次のレコードのシーケンス番号を設定する方法を示します。

自動採番属性は、 StringAttributeMetadata クラスを使用して文字列属性を作成するのと同じ方法で作成できますが、新しい AutoNumberFormat プロパティを使用する点が異なります。 AutoNumberFormat プロパティを使用して、生成される値の長さと種類を示すプレースホルダーを作成することで、連番とランダムな文字列を含むパターンを定義します。 ランダムな文字列は、特にオフラインクライアントが自動番号を作成しようとするときに、重複や衝突を回避するのに役立ちます。

自動採番属性を作成するときは、 StringAttributeMetadata.FormatName プロパティまたは StringAttributeMetadata.Format プロパティの値を Text にする必要があります。 これらはデフォルト値であるため、通常はこのプロパティは設定しません。 メール、電話、テキストエリア、URL、その他の 既存の形式など、他の特殊な形式を使用する自動採番属性は作成できません。

自動番号順序付けは SQL によって管理され、一意であることが保証されます。

従来の Web クライアントでは、自動採番属性にバインドされたフォームにコントロールを追加すると、コントロールは自動的に無効になり、エンド ユーザーがコントロールを編集できないフォームでは読み取り専用として動作します。 統一インターフェイスでは、自動採番属性にバインドされたコントロールを明示的に無効に設定する必要があります。 フォームで初期属性値を設定しない場合、値はエンティティを保存した後にのみ設定されます。 自動ナンバリングは、ビューやグリッドなどの属性フィールド値に適用できます。

例示

次の例は、new_Widget という名前のユーザー定義エンティティに対して new_SerialNumber という名前の新しい自動採番属性を作成する方法を示しています。この属性の値は WID-00001-AB7LSFG-20170913070240 のようになります。 SDK アセンブリ CreateAttributeRequest クラスと StringAttributeMetadata クラスで組織サービスを使用する場合:

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

Web API の使用

エンティティ定義は、Web API を使用して作成および更新できます。

詳細: Web API を使用したエンティティ定義の作成および更新 > 属性の作成。

リクエスト

POST [Organization URI]/api/data/v9.1/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.1/EntityDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/Attributes(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

AutoNumberFormat のオプション

次の例は、 AutoNumberFormat プロパティを構成して異なる結果を得る方法を示しています。

ランダムな文字列プレースホルダーはオプションです。 ランダムな文字列プレースホルダーを複数含めることができます。 datetime プレースホルダーには、標準の日付と時刻の書式指定文字列から任意のフォーマット値を使用してください。

文字列の長さ

この表は、ランダムプレースホルダとシーケンシャルプレースホルダの文字列の長さの値を示しています。

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

シーケンシャル値は、割り当てられた最小長よりも大きくなる可能性があるため、書式設定された値の長さに合わせて StringAttributeMetadata.MaxLength プロパティを調整しないでください。 これを行うことにはほとんど価値がなく、値が MaxLength 値を超えると、将来エラーが発生する可能性があります。 シーケンシャル値の現実的な範囲のために十分なスペースを確保してください。

自動付番の属性を更新

正しくない構成で自動採番属性を作成した場合、または既存の自動採番属性を変更する場合は、属性の AutoNumberFormat 値を更新できます。

次のコード スニペットは、auto-number 属性を取得、変更、および更新する方法を示しています。

既存の自動採番属性を変更するには、 RetrieveAttributeRequest クラスを使用して属性を取得する必要があります。

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

自動採番属性を取得したら、属性を変更および更新する必要があります。

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

// Update the auto-number attribute            
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
                        {
                            Attribute = retrievedAttributeMetadata,
                            EntityName = "newWidget",
                        };
// Execute the request
_serviceProxy.Execute(updateRequest);

シード値を設定する

デフォルトでは、すべての自動連番の連続した値は 1000 から始まり、長さに応じてプレフィックスとして 0 が使用されます。 このように、値の長さは常に同じです。 初期値を変更する場合は、以下のAPIを使用して初期シード値を変更し、シーケンシャルセグメントに使用される次の数値を設定する必要があります。

たとえば、シード値を使用しなかった場合、またはシード値を 1 桁に設定した場合、最初の数値は 1 桁になり、番号の長さと等しくなるように接頭辞 0 が追加されます。 表示長が 5 の 1 桁のシードは、"5" を "00005" と表示します。 シード値を使用すると、より大きな初期値から開始できるため、シードを "10000" に設定すると、値 5 は "10005" と表示されます。

自動番号付け属性を作成した後で別の開始値を選択する場合は、 SetAutoNumberSeed メッセージを使用します。 SDK アセンブリを使用する場合は SetAutoNumberSeedRequest クラスを使用し、Web API を使用する場合は SetAutoNumberSeed アクションを使用します。

AutoNumberSeed メッセージには、次のパラメータがあります。

例示

次の例では、new_Widget という名前のユーザー定義エンティティの new_SerialNumber という名前の自動番号属性のシードを 10000 に設定します。

SDK アセンブリの SetAutoNumberSeedRequest クラスで組織サービスを使用する場合:

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

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

詳細: Web API アクションの使用 > バインド解除アクション

リクエスト

POST [Organization URI]/api/data/v9.1/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

コミュニティ ツール

自動番号マネージャー

XrmToolBox の自動番号マネージャーは 、Dynamics 365 Customer Engagement (on-premises) のコミュニティ主導のツールで、新規または既存の属性の自動番号形式を設定、更新、および削除するための UI を提供します。 自動番号マネージャーの詳細については、コミュニティが開発したツールと anm.xrmtoolbox.com の開発者ツールの記事を参照してください。

こちらもご覧ください

メタデータとデータモデル
エンティティ属性メタデータのカスタマイズ