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 Microsoft Dynamics NAV style filter that is specified in a standard Microsoft 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).

C# Copy Code
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:

C# Copy Code
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);
}

See Also