.NET 用 SDK を使用したデータのクエリ

.NET 用 SDK は、データをクエリするメソッドをいくつか提供します。 それぞれにはさまざまな利点があります。

要求を送信する方法

FetchExpression、QueryExpression、および QueryByAttribute は、QueryBase 抽象クラスから派生しています。 これらのクラスを使用して定義されたクエリの結果を取得するには、2 つの方法があります。

• これらのクラスのいずれかのインスタンスを query パラメータとしてIOrganizationService.RetrieveMultiple メソッドに渡すことができます。

• クラスの RetrieveMultipleRequest.Query プロパティを設定し、IOrganizationService.Execute メソッドを使用できます。

  一般的には、IOrganizationService.RetrieveMultiple メソッドが使用されますが、RetrieveMultipleRequest クラス を使用して オプション パラメーター を使用したり、ExecuteMultipleRequest または ExecuteTransactionRequest クラスを使用してバッチの一部として要求を送信したりすることもできます。

これらのメソッドは両方とも、Entities コレクション プロパティにクエリの結果が含まれる EntityCollection を返します。 EntityCollection は、返されるページング結果を管理するための他のプロパティがあります。

これらのクラスを使用してデータを取得する場合、理解しておく必要がある概念がいくつかあります。 この記事の残りの部分では、SDK for .NET クラスを使用してデータを取得する際の一般的な概念について説明します。

Null 列値は返されません

テーブル列に null 値が含まれている場合、または列が要求されなかった場合、Entity.Attributes コレクションはその値に含まれません。 属性にアクセスするためのキー、または返す値はありません。 属性の欠落は、それが null であることを示しています。

読み取りに有効でない列は常に null 値を返します。 これらの列の定義では、AttributeMetadata.IsValidForRead プロパティが false に設定されています。

早期バインドクラスは null 値を管理する

早期バインドスタイル を使用する時、エンティティ クラス から継承される生成されたクラスのプロパティがこれを管理し、null 値を返します。 早期バインドクラスの生成について学ぶ

遅延バインドクラスを使用して null 値を軽減する方法

遅延バインド スタイル を使用する場合、Entity.Attributes または Entity.FormattedValues コレクションのインデクサを使用して値にアクセスしようとすると、メッセージ: The given key was not present in the dictionaryの KeyNotFoundException が発生します。

遅延バインド スタイルを使用するときにこの問題を避けるには、2 つの方法があります。

1. Null になる可能性がある列の場合は、インデクサーを使用してアクセスする前に、Entity.Contains(System.String) メソッドを使用して、列の値が null かどうかを確認します。 例:

   Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);

2. 値にアクセスするには、Entity.GetAttributeValue<T>(System.String) メソッドを使用します。 例:

   Money revenue = entity.GetAttributeValue<Money>("revenue");

   注意

   Entity.GetAttributeValue<T>(System.String) で指定されたタイプが、Boolean または DateTime のような null にはできない値タイプの場合、返される値は、null ではなく false または 1/1/0001 12:00:00 AM のような null にはできません。

各リクエストは最大 5000 件のレコードを返すことができます

対話型アプリケーションでは通常、表示されるレコードの数を人間が操作できる数に制限し、データのページを移動するオプションを提供します。 たとえば、モデル駆動型アプリは、ユーザーが 25 から 250 までの値を選択できる 個人オプション に依存します。 この情報は、UserSettings.PagingLimit列に保存されます。

アプリ内にデータを表示せずに Dataverse からデータを取得するアプリケーションでは、ページ サイズを指定する必要はありません。 既定の最大ページサイズは 5,000 行です。 ページサイズを設定しない場合、Dataverse は一度に 5,000 行までのデータを返します。 さらに多くの行を取得するには、追加のリクエストを送信する必要があります。

ページングは​​、EntityCollection.PagingCookie プロパティで Dataverse が返されるページング Cookie データを使用すると最適に機能しますが、これは必須ではなく、一部の要求ではページング Cookie 値が返されません。 詳細情報:

• FetchXml を使用したページ結果
• QueryExpression を使用して結果をページングする

一部の列ではフォーマットされた値が返されます

EntityCollection.Entities の各 エンティティ について、Entity.Attributes コレクションを使用してテーブル列 (属性) のデータ値にアクセスします。

数値や文字列などの単純なデータ型をアプリケーション内で直接表示および編集できます。 特定のデータ型の場合、Dataverse はアプリケーションで表示できる読み取り専用の書式設定された文字列値を提供します。 これらの文字列値の一部の形式は、管理者 によって設定され、各ユーザーによって上書きされる設定によって異なります。

• 管理者は、すべての新規ユーザーに適用される デフォルトの地域オプションをカスタマイズ できます。 これらの設定は、組織テーブル に保存されます。
• 各ユーザーは 個人の好みに合わせてこれらの設定を上書き できます。 これらの設定は、UserSettings テーブル に保存されます。

次の種類の列のフォーマットされた値にアクセスするには、Entity.FormattedValues コレクションを使用します。

次のサンプルは、次の取引先企業列の書式設定された文字列値にアクセスする方法を示しています。

static void FormattedValuesExample(IOrganizationService service)
{
    List<string> columns = new() {
        "name",
        "primarycontactid",
        "createdon",
        "revenue",
        "statecode"
    };

    QueryExpression query = new("account")
    {
        ColumnSet = new ColumnSet(columns.ToArray()),
        TopCount = 3
    };

    EntityCollection accounts = service.RetrieveMultiple(query);

    accounts.Entities.ToList().ForEach(x =>
    {
        string name = (string)x.Attributes["name"];
        string primarycontactid = x.Contains("primarycontactid") ? 
           x.FormattedValues["primarycontactid"] : 
           string.Empty;
        string createdon = x.FormattedValues["createdon"];
        string revenue = x.Contains("revenue") ? 
           x.FormattedValues["revenue"] : 
           string.Empty;
        string statecode = x.FormattedValues["statecode"];

        Console.WriteLine(@$"
name:{name}
    primary contact: {primarycontactid}
    created on: {createdon}
    revenue: {revenue}
    status: {statecode}"
            );
    });
}

書式設定された結果は、次のように表示されます。

name:A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2020 11:04 AM
  revenue: $10,000.000
  status: Active

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2024 11:04 AM
  revenue: $100,000.000
  status: Active

name:Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.000
  status: Active

エイリアスを使用する列は AliasedValue を返します

集計値を取得するときは、集計値を含む列の名前を指定する必要があります。 あまり一般的ではありませんが、'通常の' クエリに別の列名を指定することもできます。

エイリアスを指定すると、返される値は エイリアス値 にパッケージ化されています。 AliasedValue クラスには 3 つのプロパティがあります。

列エイリアスを使用する場合は、Value プロパティをキャストして返された値にアクセスする必要があります。

列エイリアスの詳細について:

• FetchXMl 列エイリアス
• QueryExpression 列のエイリアス

FetchXml と QueryExpression の間でクエリを変換する

QueryExpression クエリを FetchXml、および FetchXml を QueryExpression に変換するには、QueryExpressionToFetchXmlRequest および FetchXmlToQueryExpressionRequest クラスを使用します。

SavedQuery テーブルには、テーブル (エンティティ タイプ) のシステムビューと UserQuery テーブルには、保存されたユーザー クエリが格納されます。 他のテーブルもクエリを FetchXml 文字列として格納する場合があります。 これらのメソッドを使用すると、FetchXml 文字列を QueryExpression に変換し、オブジェクト モデルを使用して操作し、FetchXml に変換して文字列として保存できるようになります。

詳細: サンプル: Fetch と QueryExpression の間でクエリを変換する

クエリ条件の制限

Dataverse で、クエリで許可される条件の合計は 500 に制限されています。 クエリに含まれる結合はすべて、この制限の一部としてカウントされます。 クエリ (およびその結合) の条件が 500 件を超えると、クエリの実行時にユーザーに次のエラーが表示されます: Number of conditions in query exceeded maximum limit.。

このエラーが発生した場合、ユーザーは次のいずれかを行う必要があります。

• クエリの条件の数を減らします。
• In 句を使用します。これにより、整数に制限のない最大 850 文字の GUID と文字列が許可されます。

文字列値のすべてのフィルター条件では、大文字と小文字は区別されません

文字列値を比較するときは、大文字と小文字を区別する必要はありません。 次の QueryExpression クエリは、Contoso, Ltd そして CONTOSO, LTD という名前のアカウントレコードを返します。

QueryExpression query = new("account")
{
   ColumnSet = new ColumnSet("name"),
   Criteria = new FilterExpression(LogicalOperator.And) { 
      Conditions = {
         { 
               new ConditionExpression(
                  attributeName: "name", 
                  conditionOperator: ConditionOperator.Equal, 
                  value: "CONTOSO, LTD") 
         }
      }
   },
   TopCount = 3
};