厳密に型指定されたエンティティ

厳密に型指定されたすべてのエンティティは ITypedEntity から派生し、ITypedEntity 自体はIEntityから派生します。

厳密に型指定されたエンティティは、いくつかのエンティティ メンバーを C# プロパティとして提供します。IAsset の例を挙げると、次のようなプロパティがあります。

string FileName { get; set; }

このようなプロパティの実装は非常に簡単です。ゲッターは基本的に、次のように機能します。

return asset.GetPropertyValue<string>("FileName");

セッターは次のように実装します。

asset.SetPropertyValue("FileName", value);

これらは主にショートカットであり、リレーションも同様に処理されます。ただし、厳密に型指定されたエンティティの場合は、プロパティ値とリレーション値の取得と設定だけではなく、より多くの機能を公開することがあります。

厳密に型指定されたエンティティを使用するには、まず、厳密に型指定されたエンティティのインスタンスを取得する必要があります。厳密に型指定されたエンティティは、通知クライアント上の Task<IMailTemplate> GetMailTemplateAsync(...) のように、クライアントから直接返される場合があります。それ以外の場合はキャストが必要になります。

エンティティ クライアントはすべてのエンティティを IEntity として返しますが、エンティティ定義が指定されたエンティティであることが明らかである場合は、ダウンキャストをお勧めします。エンティティ ファクトリであっても、厳密に型指定されたエンティティが存在する場合は、厳密に適切な型を指定したインスタンスを作成します。

たとえば、ID が 1000 のエンティティがアセットであることが確実な場合、次のスニペットを使用してこのエンティティを取得できます。

IAsset asset = await MClient.Entities.GetAsync(1000) as IAsset;

これに対し、ファイル名を次の方法で取得できます。

string filename = asset.FileName;

部分エンティティは、完全に読み込まれていないエンティティです。既定では、SDK はエンティティを部分的にしか読み込みません。既定のカルチャとすべてのプロパティが読み込まれますが、リレーションは読み込まれません。読み込みの構成を指定することで、この動作を変更できます。

プロパティまたはリレーションが読み込まれていない場合に SDK がこのプロパティ値を取得すると、null が返されます。また、一部のリレーションに対しては空のコレクションが返されます。読み込まれていないプロパティに対し、IEntity を使用してプロパティ値を設定しようとすると、欠落プロパティに対する例外がスローされます。

この動作は、厳密に型指定されたエンティティでも同じです。アセットの読み込み時にプロパティが含まれなかった場合に、次のコードでファイル名を取得しようとしたとします。

string filename = asset.FileName;

この場合、このアセットがサーバー上では値を持っていたとしても、filename には null が含まれます。これは、FileName プロパティが読み込まれていなかったためです。

このような問題を防ぐには、使用するメンバーを含めたエンティティが読み込まれるように、常に確認する必要があります。また、ITypedEntity インスタンスは LoadTypedMembersAsync メソッドをサポートします。このメソッドは、厳密に型指定されたインターフェースで公開されているすべてのメンバーを遅延読み込みします。ただし、これには大きなオーバーヘッドが伴うため、十分考慮して使用する必要があります。