.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 と属性のタイプは、以下の方法で検出できます。

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

タイプ 内容
EntityReference 検索属性。 別のエンティティ レコードへのリンク。
BooleanManagedProperty WebResource などの、ソリューション コンポーネントになることができるエンティティにのみ使用されます。 詳細: マネージド プロパティの使用
Money 通貨属性。
OptionSetValue オプション セット属性。 状態および状態属性もこの種類を使用します。
Boolean 2 つのオプション属性。
Byte[] イメージ属性。 各エンティティは 1 つのイメージを持つことができ、属性の名前は entityimage です。 イメージをダウンロードする URL は、entityimage_url という名前のコンパニオン属性で取得することができます。 詳細: イメージ属性
DateTime 日時属性は、通常、UTC 値を使用します。 詳細: 日時属性の動作と形式
Decimal 10 進数属性。
Double 浮動小数点数属性。
Guid 通常、エンティティの一意の識別子として使用されます。
Int32 整数属性。
String 複数行テキストおよび 1 行テキスト属性がこの種類を使用します。 文字列を使用するあまり一般的ではない別のタイプは EntityName 列です。これはテーブルの論理名を表す文字列値を格納します。

注意

ファイル列はエンティティから直接利用できません。 ファイル列からデータをアップロードまたはダウンロードするには、一連のリクエストを使用する必要があります。 詳細: ファイルの列データを使用する。

遅延バインド スタイルを使用してエンティティ属性を操作する方法は 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 メソッドを使用して属性値を取得または設定することもできます。

方法 説明
GetAttributeValue<T>(String) 型指定された属性値を戻します
SetAttributeValue(String, Object) 型指定された属性値を設定します

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

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

注意

このメソッドは、生成された Entityクラス インスタンスを別の生成されたクラスに、または Entity に変換するためには使用できません。. Entity インスタンスを、継承した生成クラスの 1 つに変換するためにのみ使用できます。 Entity インスタンスが実際に生成されたクラスのインスタンスでない場合、このメッセージはエラーをスローします。

次の手順

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

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

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。