ADO.NET Data Services v1.5 CTP1 – Server Driven Paging
This post is a drill down into the Server Driven Paging (SDP) feature added in data services v1.5 CTP1. Since this is the first CTP release of this feature we look forward to hearing your feedback.
What is Server Driven Paging?
This feature is best described by example. If you had a data service that exposes photos, you would likely want to limit the total number of photos a single request to the service can retrieve because the total collection of photos may be very large. This feature allows a service author to set per collection limits on the total number of entities returned for each request. In addition to limiting the number of photos returned per request, the server provides the client a “next link” which is simply a URI specifying how to continue retrieving the rest of the entities in the collection not returned by the first request.
For those familiar with AtomPub (IETF RFC 5023, section 10.1), this feature adds support for AtomPub <link rel=”next” …> elements to the data service runtime.
For CTP1 we’ve included server side support for this feature only. Client library support will likely come in a future CTP.
Feature Walkthrough
The remainder of this post is a step-by-step walkthrough describing how to enable and work with the Server Driven Paging feature in a data service.
To get started, you’ll want to download all of the required software I use in the walk through:
The steps we’ll follow in this walkthrough are noted below. If you are already familiar with ADO.NET Data Services v1 you may want to skip down to Step 2.
Step 1: Create an ASP.NET Web Application project and create the data model to be exposed by an ADO.NET Data Service using the Entity Framework (EF) and SQL Server. Note: Any data source (EF, custom provider, etc) supported by ADO.NET Data Services could be used.
Step 2: Create a v1.5 ADO.NET Data Service which exposes the data model created in step 1.
Step 3: Enable Server Driven Paging limits on the data service created in step 2.
Step 1: Create the Project & Data Model
Nothing new yet, simply create a new Web Application (named SDPDemo).
Our first data access related task is to generate the Entity Framework-based data access layer to the Northwind database. Right click the ASP.NET project and select ‘Add New Item’, then select ‘ADO.NET Entity Data Model’. Name the new item nw.edmx:
After clicking ‘Add’ on the screen above, a wizard will open to walk you through creating the Entity Data Model for the Northwind database. Use the default settings (selecting the Northwind DB along the way) and click the ‘Next’ button until you reach the screen shown below:
Once you reach the ‘Choose Your Database Objects’ screen, select all the Tables and click ‘Finish’. This will open the Entity Data Model designer view. This view allows you to customize the generated conceptual data model. To learn more about the mapping capabilities of the Entity Framework, see here. For this demo we’ll just use the default model created by the wizard without any customizations.
Step 2: Create the v1.5 CTP1-based ADO.NET Data Service
The next step is to create our v1.5 CTP1-based ADO.NET Data Service which we’ll subsequently set Server Driven Paging limits on.
To create the data service, right click the ASP.NET project and select ‘Add New Item’. Add an ‘ADO.NET Data Service v1.5 CTP1’ item called nw.svc:
This will generate a file (nw.svc.cs) which represents the skeleton of a v1.5 data service. All we need to do now is point the data service at the data model to be exposed as a REST-service and we’ll be set. The snippet below shows the 2 or so lines of code you need to write to do this. One thing to note is that a data service is locked down by default, so we need to take explicit steps to open access to it. For this simple application we’ll enable read and write access to the entire model quickly using the call to ‘SetEntitySetAccessRule’ shown below.
That’s it, our data service is now created. To test this, run the project and navigate to the nw.svc file. You should see a listing as shown below that outlines all the entry points to the data service. If you don’t, tweak your IE settings and reload.
Step 3: Set Server Driven Paging Limits
At this point we have a working data service and are ready to configure the Server Driven Paging limits for the service. For example, to limit the number of Customer entities the data service will return per request to 4, we would add the following call to ‘SetResourceSetPageSize’ to our data service:
If you view the nw.svc file in the browser and navigate to the nw.svc/Customers endpoint of the service you should now only see four customer entities returned even though the Northwind DB has many more than four customers in it.
The next thing to notice is the response from the data service includes a “next link” which is a URI indicating how a client can continue retrieving the rest of the entities in the collection not returned by the first request. The images below show the AtomPub and JSON representations returned (and the associated “next links”) when querying the nw.svc/Customers URI.
Sending an HTTP GET request to the “next link” in the above listing would allow the client to continue making progress towards obtaining the entire set of Customer entities. In this example a GET request sent to the URI nw.svc/Customers?$skiptoken=’AROUT’ would retrieve the next four Customers (sorted by key) from the data service after those in the above listing.
This feature works in conjunction with all query requests (arbitrary filters, result ordering, etc). For example, if a GET request is sent to the URI: nw.svc/Customers?$filter=City eq ‘London’&$orderby=PostalCode , the results returned will be the first four Customers in London sorted by PostalCode and the “next link” returned will be equal to: nw.svc/Customers?$filter=City eq ‘London’&$orderby=PostalCode&$skiptoken=’WA1 1DP’,’AROUT’.
It is important to note this feature is a server driven paging mechanism which allows a data service to gracefully return partial sets to a client. If a client application knows it wants a subset of the total number of entities in an entity set (perhaps to bind to a paged grid UI control) then it should use the client driven paging query string options ($top and $skip) available starting with the v1 data services framework. For additional information on $top and $skip see this “Using ADO.NET Data Services” (v1) whitepaper.
Providing Feedback
We have created a new forum dedicated to providing feedback on “pre-release” versions of data services such as this CTP. Please direct all your questions and comments about this feature to this new forum which is available at: (http://social.msdn.microsoft.com/Forums/en-US/dataservices/threads).
Note: The forum intended for questions on currently shipping versions of ADO.NET Data Services is still available at: (http://social.msdn.microsoft.com/Forums/en-US/adodotnetdataservices/threads/ )
We look forward to hearing your feedback.
-Mike Flasko
ADO.NET Data Services, Program Manager
Light
Dark
0 comments