次の方法で共有

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

  • [アーティクル]

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

メソッド 利点
FetchExpression クラス 独自の FetchXML クエリ言語を使用して、ページ化されたデータ セットやグループ化および集約されたデータを返すことができる複雑なクエリを作成します。 関連するレコードのデータを含める結合を作成できます。 FetchXml は他のオプションにはない機能を提供します。
FetchXML を使用してデータをクエリする方法について
QueryExpression クラス 強力な種類のオブジェクトモデルを使用して、ページ化されたデータ セットやグループ化および集約されたデータを返すことができる複雑なクエリを作成します。 関連するレコードのデータを含める結合を作成できます。 FetchXML で ほとんどの機能 をサポートします。
QueryExpression を使用してデータをクエリする方法について
QueryByAttribute クラス クエリ内のすべての条件に一致する行を返す、一般的なクエリ用のよりシンプルなオブジェクト モデル。 ページングは​​サポートしますが、グループと集約されたデータ セットはサポートしません。 単一のテーブルからのみデータを返すことができます。
QueryByAttribute クラスを使用してデータをクエリする方法について
LINQ OrganizationServiceContext.QueryProvider を使用して、一般的な LINQ 構文を使用してクエリを作成します。 すべての LINQ クエリは QueryExpression に変換されるため、この機能は QueryExpression で使用できるものに限定されています
この記事では、データを取得するための SDK クラスに焦点を当てます。 LINQ (.NET 統合言語クエリ) を使ってデータをクエリする方法について

要求を送信する方法

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

これらのメソッドは両方とも、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 値が返されません。 詳細情報:

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

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

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

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

タイプ 返されるデータの種類 書式設定された値の説明
はい/いいえ
BooleanAttributeMetadata		 ブール値 対応する BooleanOptionSetMetadata.FalseOption または BooleanOptionSetMetadata.TrueOption プロパティのローカライズされたラベル。
顧客、検索、および 所有者
LookupAttributeMetadata		 EntityReference レコードのプライマリ名列の値である、EntityReference.Name 値。
日時
DateTimeAttributeMetadata		 DateTime 列の動作と形式設定、組織の設定、およびユーザーが設定した個人オプション (ユーザーのタイムゾーンなど) によって異なります。
エンティティ名
EntityNameAttributeMetadata		 文字列 値が noneでない場合、フォーマットされた値はテーブルのローカライズされた DisplayName 値になります。
Currency
MoneyAttributeMetadata		 Money 列に選択された通貨、組織とユーザーの設定によって異なります。
選択肢
MultiSelectPicklistAttributeMetadata		 OptionSetValueCollection 単一のオプションが選択されている場合、選択されたオプションのローカライズされたラベル。 複数のオプションが選択されている場合、選択された各オプションのローカライズされたラベルを含む文字列が ; で区切られます。 例: Appetizer; Entree; Dessert
選択肢
PicklistAttributeMetadata
状況
StateAttributeMetadata
ステータス 理由
StatusAttributeMetadata		 OptionSetValue 選択したオプションのローカライズされたラベル。

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

論理名 タイプ
primarycontactid EntityReference
createdon DateTime
revenue Money
statecode OptionSetValue 
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 つのプロパティがあります。

Property タイプ プロパティ
EntityLogicalName String データの取得元の列を持つテーブルの論理名。
AttributeLogicalName String データの取得元の列の論理名。
Value Object 集計された値、または別名を使用した列行の値。

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

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

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

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

注意

QueryExpression にはない FetchXml 機能がいくつかあります。 FetchXml クエリを QueryExpression に変換すると、これらの違いは失われます。 QueryExpression の制限事項の詳細

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
};

注意

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

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