CrmService.RetrieveMultiple Method
.gif) |
Retrieves a collection of entity instances based on the specified query criteria.
Syntax
[Visual Basic]
Public Function RetrieveMultiple(
ByVal query As QueryBase
) As BusinessEntityCollection
[C#]
public BusinessEntityCollection RetrieveMultiple(
QueryBase query
);
[JScript]
public function RetrieveMultiple(
query : QueryBase
) : BusinessEntityCollection;
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 specifed in the QueryExpression.
To perform this action, the caller must have the Read privilege to the entity type being retrieved and access rights on the entity instances retrieved.
This method replaces a number of existing Microsoft CRM V1.X Retrieve methods. Any Retrieve method that passes a property of the calling entity in the method signature is deprecated. Instead, the property that used to be passed in the signature is now passed as criteria in the QueryExpression object.
Deprecated methods include: RetrieveByOrganization, RetrieveByPrincipal, BulkRetrieve, RetrieveByState, RetrieveBySubject, RetrieveByTerritory, RetrieveByType, RetrieveByUser, RetrieveByUserAndYear, RetrieveChildBusinesses, and RetrieveByParent. For more information, see Mapping from Version 1.2.
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.
[C#]
// Standard CRM Service Setup
CrmService service = new CrmService();
service.Credentials = System.Net.CredentialCache.DefaultCredentials;
// Create the ColumnSet indicating the fields to be retrieved
ColumnSet cols = new ColumnSet();
// Sets the ColumnSet's Properties
cols.Attributes = new string [] {"fullname", "contactid"};
// Create the ConditionExpression
ConditionExpression condition = new ConditionExpression();
// Set the Condition for the Retrieval to be when the contact's address' city is Sammamish
condition.AttributeName = "address1_city";
condition.Operator = ConditionOperator.Like;
condition.Values = new string [] {"Sammamish"};
// Create the FilterExpression
FilterExpression filter = new FilterExpression();
// Set the Filter's Properties
filter.FilterOperator = LogicalOperator.And;
filter.Conditions = new ConditionExpression[] {condition};
// Create the QueryExpression Object
QueryExpression query = new QueryExpression();
// Set the QueryExpression Object's Properties
query.EntityName = EntityName.contact.ToString();
query.ColumnSet = cols;
query.Criteria = filter;
// Retrieve the Contacts
BusinessEntityCollection contacts = service.RetrieveMultiple(query);
[Visual Basic .NET]
' Standard CRM Service Setup
Dim service As New CrmService()
service.Credentials = System.Net.CredentialCache.DefaultCredentials
' Create the ColumnSet indicating the fields to be retrieved
Dim cols As New ColumnSet()
' Sets the ColumnSet's Properties
cols.Attributes = New String() {"fullname", "contactid"}
' Create the ConditionExpression
Dim condition As New ConditionExpression()
' Set the Condition for the Retrieval to be when the contact's address' city is Sammamish
condition.AttributeName = "address1_city"
condition.Operator = ConditionOperator.Like
condition.Values = New String() {"Sammamish"}
' Create the FilterExpression
Dim filter As New FilterExpression()
' Set the Filter's Properties
filter.FilterOperator = LogicalOperator.And
filter.Conditions = New ConditionExpression() {condition}
' Create the QueryExpression Object
Dim query As New QueryExpression()
' Set the QueryExpression Object's Properties
query.EntityName = EntityName.contact.ToString()
query.ColumnSet = cols
query.Criteria = filter
' Retrieve the Contacts
Dim contacts As BusinessEntityCollection = service.RetrieveMultiple(query)
See Also