IOrganizationService.RetrieveMultiple(QueryBase) Method

Reference

Definition

Namespace:: Microsoft.Xrm.Sdk

Assembly:: Microsoft.Xrm.Sdk.dll

Package:: Microsoft.PowerPlatform.Dataverse.Client v1.1.32

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Retrieves a collection of records.

public:
 Microsoft::Xrm::Sdk::EntityCollection ^ RetrieveMultiple(Microsoft::Xrm::Sdk::Query::QueryBase ^ query);

[System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))]
[System.ServiceModel.OperationContract]
public Microsoft.Xrm.Sdk.EntityCollection RetrieveMultiple (Microsoft.Xrm.Sdk.Query.QueryBase query);

[<System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))>]
[<System.ServiceModel.OperationContract>]
abstract member RetrieveMultiple : Microsoft.Xrm.Sdk.Query.QueryBase -> Microsoft.Xrm.Sdk.EntityCollection

Public Function RetrieveMultiple (query As QueryBase) As EntityCollection

Parameters

query: QueryBase

A query that determines the set of records to retrieve.

Returns

EntityCollection

The collection of entities returned from the query.

Attributes: FaultContractAttribute OperationContractAttribute

Examples

For the following examples to work correctly, you must be connected to the server to get an IOrganizationService interface instance.

The following example shows how to use the RetrieveMultiple(QueryBase) method using the QueryExpression class.

/// <summary>
/// Demonstrates RetrieveMultiple with QueryExpression
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void QueryExpressionExample(IOrganizationService service)
{

      // Define the query
      QueryExpression query = new("account")
      {
         TopCount = 5
      };
      // Add columns to query.ColumnSet
      query.ColumnSet.AddColumns("name", "primarycontactid");

      // Add conditions to query.Criteria
      query.Criteria.AddCondition("address1_city", ConditionOperator.Equal, "Redmond");

      // Add orders
      query.AddOrder("name", OrderType.Ascending);

      // Send the request
      EntityCollection results = service.RetrieveMultiple(query);
      // Show the data
      foreach (Entity record in results.Entities)
      {
         Console.WriteLine($"name:{record.GetAttributeValue<string>("name")}");
      }
}

The following example shows how to use the RetrieveMultiple(QueryBase) method using the FetchExpression class.

/// <summary>
/// Demonstrates RetrieveMultiple with FetchXml
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void FetchXmlExample(IOrganizationService service)
{

      // Define the query
      string fetchXml = @"<fetch top="5"><entity name="account"><attribute name="name"></attribute><attribute name="primarycontactid"></attribute><filter type="and"><condition attribute="address1_city" operator="eq" value="Redmond"></condition></filter><order attribute="name"></order></entity></fetch>";

      FetchExpression query = new(fetchXml);
      // Send the request
      EntityCollection results = service.RetrieveMultiple(query);
      // Show the data
      foreach (Entity record in results.Entities)
      {
         Console.WriteLine($"name:{record.GetAttributeValue<string>("name")}");
      }
}

The following example shows how to use the RetrieveMultiple(QueryBase) method using the QueryByAttribute class.

/// <summary>
/// Demonstrates RetrieveMultiple with QueryByAttribute
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void QueryByAttributeExample(IOrganizationService service)
{
      // Define the query
      QueryByAttribute query = new("account")
      {
         ColumnSet = new ColumnSet("name", "primarycontactid"),
         PageInfo = new PagingInfo() { Count = 5, PageNumber = 1 }
      };
      query.AddAttributeValue("address1_city", "Redmond");
      query.AddOrder("name", OrderType.Ascending);

      // Send the request
      EntityCollection results = service.RetrieveMultiple(query);
      // Show the data
      foreach (Entity record in results.Entities)
      {
         Console.WriteLine($"name:{record.GetAttributeValue<string>("name")}");
      }
}

You can find more samples on GitHub:

Remarks

Learn how to query data using the SDK for .NET.

Privileges and Access Rights

To perform this action, the caller must have Read privileges on the table that is specified in the query. This method only returns the records for which the calling user has Read access rights. Learn more about how to verify access with code.

Notes for Callers

The collection of returned records contains the values for the properties that are specified in the query for which the calling user has access rights. Any other property values are not returned.

If the query includes columns that are not valid for retrieval, they are ignored. Columns are not valid for retrieval when AttributeMetadata.IsValidForRead is false. For common Dataverse tables you can find the IsValidForRead value in the Dataverse table/entity reference. For custom tables or tables added by other solutions, you can use a table definition browser like the one described in Browse table definitions in your environment.

For more information about the exceptions that can be thrown when this method is called, see Handle exceptions in your code.

Supported tables

You can use this method to create any record of a table that supports the RetrieveMultiple message. Learn more about Table support for messages and Message support for tables.

Applies to

Jaa