ReadMultiple Operation

Artikkeli
06/05/2016

Reads a filtered set of records. This operation returns an array of entities. The ReadMultiple operation allows the consumer of a web service to specify the number of records to be returned at one time. This can reduce load on the server.

Note

Records on a page that were inserted after the page was retrieved are not read. Records on a page may be incorrectly included in the retrieved dataset if they were deleted after the page was retrieved.

Method Signature

Entity [] ReadMultiple(Entity_Filter[] filterArray, string bookmarkKey, int setSize)

Parameters

Parameter	Description
filterArray	Type: Entity_Filter[] An array of record filters.
bookmarkKey	Type: String The last record bookmark of the page that was previously read. To return the first page of results, set bookmarkKey to NULL.
setSize	Type: Integer The size of the set to be returned. To return the complete set of results, set setSize to zero. To reverse the order of the results, set setSize to negative.

Results

Result name	Description
entity[]	Type: An array of Entities An array of a specific object type that represents the page. Contains the latest values that are present on the page. The server will return at most setSize records. If all records have been already returned, then subsequent calls will return no records (a 0-element array in C#). You should keep calling the ReadMultiple function until no records are returned.
entity.Key	Type: String The key of the last record read. In C#, you can access it with `Entity[Entity.Length-1].Key`. Pass this as bookmarkKey for the next ReadMultiple call.

Faults

This operation does not throw faults when no matching records are present. Instead, it returns an empty record list.

Faults are possible if they are generated by the C/AL code.

Remarks

Retrieving Last Page

To retrieve the last record of a page, set setSize to -1. Using negative numbers in setSize sorts the records in descending order.

Entity_Filter

You use the Entity_Filter parameter with the ReadMultiple operation. It describes a filter that can be applied on a specific field in a record. The Entity_Filter parameter contains two members: Field and Criteria.

Field contains the name of the field that the filter is applied to. This name comes from the Entity_Fields enum.
Criteria is of type string and can contain any valid Dynamics NAV style filter that is specified in a standard Dynamics NAV filter format.

Usage Examples

The following example returns the first 100 customer names that start with an S. For a detailed code example, see Walkthrough: Registering and Using a Page Web Service (SOAP).

List<Customer_Filter> filterArray = new List<Customer_Filter>();  
Customer_Filter nameFilter = new Customer_Filter();  
nameFilter.Field = Customer_Fields.Name;  
nameFilter.Criteria = "S*";  
filterArray.Add(nameFilter);  
Customer[] custList = service.ReadMultiple(filterArray.ToArray(), null, 100);

This example uses the bookmarkKey argument to read customer records in batches of 10:

Customer_Service service = new Customer_Service();  
service.UseDefaultCredentials = true;  
  
const int fetchSize = 10;  
string bookmarkKey = null;  
List<Customer> customerList = new List<Customer>();  
  
// Reads customer data in pages of 10.  
Customer[] results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);  
while (results.Length > 0)  
{  
    bookmarkKey = results.Last().Key;  
    customerList.AddRange(results);  
    results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);  
}  
  
// Prints the collected data.  
foreach (Customer customer in customerList)  
{  
    Console.WriteLine(customer.Name);  
}

Jaa