.NET 用 SDK を使用したエンティティ クラスの操作

.NET 用 SDK を使用して Microsoft Dataverse データを操作する場合は、遅延バインド スタイルで Entity クラスを使用するか、事前バインド スタイルを使用して生成されたエンティティ クラスを使用します。 生成されたエンティティ クラスは Entity クラスから継承されるため、どちらのスタイルでも Entity クラスを理解することが重要です。

このトピックでは、Entity クラスの最も頻繁に使用されるプロパティとメソッドについて説明します。

Entity.LogicalName

遅延バインド スタイルを使用して新しい Entity クラス インスタンスを作成する場合、有効な文字列値を指定してエンティティ タイプを指定する必要があります。 LogicalName はエンティティ メタデータ (テーブル定義) で定義されます。

事前バインド スタイルを使用する場合、この値は生成されたクラスのコンストラクターによって設定されます。 例: var account = new Entity("account");

コードで、エンティティの種類を説明する文字列値を後で取得する場合は、LogicalName プロパティを使用できます。 これは、エンティティ論理名をパラメータとして必要とする API の多くを使用する際に便利です。

Entity.Id

Entityクラスをインスタンス化する場合、遅延バインドを使用するか事前バインド スタイルを使用するかにかかわらず、一意の ID は設定されません。 エンティティを作成する場合は、エンティティを設定する必要はありませんが、エンティティを作成 (保存) するときにはそのエンティティを設定できます。

エンティティを取得する場合は、エンティティを要求したかどうかにかかわらず、主キーの属性値が含まれます。 主キー属性名は、エンティティのタイプごとに異なります。 一般に、主キー属性の名前はエンティティ logicalname + id です。 取引先企業の場合は accountid、取引先担当者の場合は contactid となります。

主キー属性を使用して主キー値を取得または設定できますが、Id プロパティを使用して、主キー属性の名前を覚える必要なく値にアクセスすることができます。

テーブル列への事前バインドのアクセス

生成されたクラスで事前バインド スタイルを使用している場合、クラスの各属性の型付きプロパティがあります。 属性のプロパティは、AttributeMetadata.SchemaName を使用し、 Entity クラスのインスタンスで直接アクセスできます。

例:

//Using the early-bound Account entity class
var account = new Account();
// set attribute values
// string primary name
account.Name = "Contoso";
// Boolean (Two option)
account.CreditOnHold = false;
// DateTime
account.LastOnHoldTime = new DateTime(2017, 1, 1);
// Double
account.Address1_Latitude = 47.642311;
account.Address1_Longitude = -122.136841;
// Int
account.NumberOfEmployees = 500;
// Money
account.Revenue = new Money(new decimal(5000000.00));
// Picklist (Option set)
account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer

テーブル列への遅延バインドのアクセス

エンティティに含まれるデータは、Entity.Attributes プロパティに設定します。 このプロパティは、新しい属性を追加したり、属性が存在するかどうかをチェックしたり、属性を削除したりする一連のメソッドを提供する AttributeCollection です。

列名とデータ型を検出する

遅延バインド スタイルでは、属性とデータ型の AttributeMetadata.LogicalName を 知っておく必要があります。 LogicalName は、SchemaName の小文字のバージョンです。 LogicalName と属性のタイプは、以下の方法で検出できます。

• Web アプリケーションのカスタマイズ ツールで列 (属性) の定義を表示する
• システム テーブルの場合、テーブル/エンティティ参照 を参照する
• 環境のメタデータを参照する で説明されているメタデータ ブラウザーなどの、テーブル定義を参照するツールを使用する
• AttributeMetadata のリファレンス ページに派生クラスのリストが表示されます

属性のタイプは、次のいずれかになります。 リストの内容は一部です。

遅延バインド スタイルを使用してエンティティ属性を操作する方法は 3 つあります。

• Entity クラスでインデクサーを使用する
• Attributes コレクションでインデクサを使用する
• 提供されている Entity メソッドを使用する

エンティティ クラスでインデクサーを使用する

遅延バインド スタイルを使用する場合のほとんどでは、インデクサを使用して、属性の LogicalName を使用する属性の値を取得または設定することによって、コレクションを操作できます。 たとえば、取引先企業の名前属性を設定するには、次のようにします。

//Use Entity class with entity logical name
var account = new Entity("account");
// set attribute values
// string primary name
account["name"] = "Contoso";
// Boolean (Two option)
account["creditonhold"] = false;
// DateTime
account["lastonholdtime"] = new DateTime(2017, 1, 1);
// Double
account["address1_latitude"] = 47.642311;
account["address1_longitude"] = -122.136841;
// Int
account["numberofemployees"] = 500;
// Money
account["revenue"] = new Money(new decimal(5000000.00));
// Picklist (Option set)
account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer

属性コレクションでインデクサを使用する

エンティティと同じように、属性コレクションのインデクサを使用して値にアクセスすることもできます。

string accountName = account.Attributes["name"];

エンティティ メソッドを使用する

Entity メソッドを使用して属性値を取得または設定することもできます。

たとえば、次のようになります。

account.SetAttributeValue("name", "Account Name");
var accountName = account.GetAttributeValue<string>("name");

Entity.FormattedValues

UI に表示され、文字列ではないエンティティ属性値には、UI に値を表示するために使用できる文字列形式の値があります。 たとえば、次のようになります。

• 金額には、適切な通貨と桁数の書式設定の文字列値が含まれます。
• 日付の値は、システムの構成方法に応じて設定されます
• OptionSet (選択肢) の値には、整数値を表すローカライズされたラベルが表示される

インデクサまたはエンティティ GetFormattedAttributeValue(String) メソッドを使用する、FormattedValues コレクションを使用して、書式設定された値にアクセスできます。

たとえば、これらの両方で同じ形式の値を取得します。

var formattedRevenueString1 = account.FormattedValues["revenue"];
var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");

詳細: 書式設定された値にアクセスする

Entity.RelatedEntities

エンティティ レコード (テーブル行) を作成する場合、同じ操作で作成する一連の関連エンティティ レコードを定義することもできます。 詳細情報: 1 回の操作で関連するテーブル行を作成する

RetrieveRequest を使用してエンティティ レコードを取得する場合、クエリでRelatedEntitiesQuery を設定して、関連するエンティティ レコードを結果に含めます。 詳細情報: 関連行で取得する

関連するエンティティ レコードを結果に含める場合、それらの関連レコードで値を更新し、エンティティ レコードを更新するときにそれらを含めることもできます。 詳細情報: 1 回の操作で関連するテーブル行を更新する

EntityReference への変換

多くのメッセージ プロパティは EntityReference のみを必要とします。 Entity.ToEntityReference() エンティティ レコードをエンティティ参照に変換するメソッド。

エンティティ クラスに変換する

事前バインド スタイルを使用している場合、生成された、使用しているエンティティ クラスの種類に Entity インスタンスを変換する必要があります。 これは通常、キャストで行うことができますが、Entity.ToEntity<T>() メソッドを使用することもできます。 メソッド。

Account account1 = (Account)retrievedEntity;
Account account2 = retrievedEntity.ToEntity<Account>();

次の手順

これらのトピックでは、Dataverse エンティティ (テーブル行) に関する作業について詳細に説明します。

クイック スタート: .NET 用 SDK のサンプル (C#)
データのクエリ
テーブル行の作成
テーブル行の取得
テーブル行の更新と削除
テーブル行の関連付けと関連付け解除
事前バインド プログラミングのクラスを生成する