強型型のエンティティ

使用例

強型型のエンティティは、一部のエンティティメンバーをC#プロパティとして露出させます。例えば、IAssetには以下のプロパティが含まれます:

string FileName {get; set;}

以下の文がFileNameの値を取得するために用いられます:

return asset.GetPropertyValue ("FileName");

以下の文がFileNameの値を更新するために使われます:

asset.SetPropertyValue("FileName", value);

これらは主にショートカットであり、関係も同様の方法で管理されます。しかし、強型型エンティティは、単にプロパティやリレーションの値にアクセスしたり変更したりする以上の機能を提供することがあります。

強型付けされたエンティティを使うには、まずその特定のエンティティのインスタンスを取得する必要があります。場合によっては、通知クライアントからTask GetMailTemplateAsync(...) メソッドのようにエンティティがクライアントから直接返されることもあります。他の場合、エンティティを手動でキャストする必要があります。

エンティティのクライアントはすべてのエンティティをIEntityとして返しますが、定義を知っていればエンティティを正しい型にキャストできます。強型型のバージョンが存在する場合、エンティティファクトリーは自動的に適切なインスタンスを作成します。

例えば、ID 1000を持つエンティティが資産であると確信している場合は、以下のスニペットを使ってそのエンティティを取得できます:

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

その後、ファイル名を以下の方法で取得できます:

string filename = asset.FileName;

部分的な実体

部分的なエンティティとは、完全に読み込まれていないエンティティのことです。デフォルトでは、SDKはエンティティの一部だけを読み込みます

プロパティやリレーションシップが取得されない場合、SDKはロードされていないプロパティに対してnullを返し、ロードされていないリレーションについては空のコレクションを返します。ロードされていないエンティティにプロパティを設定しようとすると、SDKは例外を投げ出します。これは強型型のエンティティにも当てはまります。

例えば、プロパティなしでアセットを読み込み、FileNameにアクセスしようとした場合:

string filename = asset.FileName;

ファイル名がサーバー上に存在していても、FileNameプロパティが読み込まれていないため、結果はnullになります。

これを避けるために、必要なメンバーをエンティティに必ずロードしてください。さらに、強型エンティティはLoadTypedMembersAsyncメソッドをサポートしており、必要に応じて強型インターフェースのすべてのメンバーをロードできます。しかし、この方法はよりリソースを消費し、慎重に使用する必要があります。

!警告強型付けのアセットは、そのメンバーが親エンティティと一致している場合にのみ正しく動作します。例えば、M.Asset定義のFileNameプロパティを名前を変えると、強型付けの方法は機能しなくなります。しかし、IEntityメソッドを使って値を取得することは可能です。