CrmService.RetrieveMultiple Method

Retrieves a collection of entity instances based on the specified query criteria.

Syntax

  public BusinessEntityCollection RetrieveMultiple(

    QueryBase  query

  );

Parameters

query

Specifies either a QueryExpression or a QueryByAttribute object derived from the QueryBase class. This is the query to be executed for an entity. The QueryExpression or QueryByAttribute object contains the type information for the entity.

Return Value

A BusinessEntityCollection that is a collection of entities of the type of specified in the query parameter.

Remarks

Use this method to retrieve one or more entity instances based on criteria specified in the QueryExpression.

For better performance, use this method instead of using the Execute method with the RetrieveMultiple message.

To perform this action, the caller must have access rights on the entity instance specified in the request class. For a list of required privileges, see Retrieve Privileges.

The ColumnSet specified within the QueryExpression can only include the objects of the type of the calling entity. For more information, see Using ColumnSet.

Example

The following example demonstrates the use of the RetrieveMultiple method.

   1:  //# [ CrmService.RetrieveMultiple Method ]

   2:  // Set up the CRM Service.

   3:  CrmAuthenticationToken token = new CrmAuthenticationToken();

   4:  // You can use enums.cs from the SDK\Helpers folder to get the enumeration for Active Directory authentication.

   5:  token.AuthenticationType = 0; 

   6:  token.OrganizationName = "AdventureWorksCycle";

   7:   

   8:  CrmService service = new CrmService();

   9:  service.Url = "http://<servername>:<port>/mscrmservices/2007/crmservice.asmx";

  10:  service.CrmAuthenticationTokenValue = token;

  11:  service.Credentials = System.Net.CredentialCache.DefaultCredentials;

  12:   

  13:  // Create the ColumnSet that indicates the properties to be retrieved.

  14:  ColumnSet cols = new ColumnSet();

  15:   

  16:  // Set the properties of the ColumnSet.

  17:  cols.Attributes = new string [] {"fullname", "contactid"};

  18:   

  19:  // Create the ConditionExpression.

  20:  ConditionExpression condition = new ConditionExpression();

  21:   

  22:  // Set the condition for the retrieval to be when the contact's address' city is Sammamish.

  23:  condition.AttributeName = "address1_city";

  24:  condition.Operator = ConditionOperator.Like;

  25:  condition.Values = new string [] {"Sammamish"};

  26:   

  27:  // Create the FilterExpression.

  28:  FilterExpression filter = new FilterExpression();

  29:   

  30:  // Set the properties of the filter.

  31:  filter.FilterOperator = LogicalOperator.And;

  32:  filter.Conditions = new ConditionExpression[] {condition};

  33:   

  34:  // Create the QueryExpression object.

  35:  QueryExpression query = new QueryExpression();

  36:   

  37:  // Set the properties of the QueryExpression object.

  38:  query.EntityName = EntityName.contact.ToString();

  39:  query.ColumnSet = cols;

  40:  query.Criteria = filter;

  41:   

  42:  // Retrieve the contacts.

  43:  BusinessEntityCollection contacts = service.RetrieveMultiple(query);