Data Service Quick Start (ADO.NET Data Services Framework)

By following the procedures in this topic, you will use ADO.NET Data Services to create and test a data service that connects to the Northwind sample database.

To create this sample data service, first make sure that the required components, as listed below in the Prerequisites section of this topic, have been installed on your computer. To create this data service, follow this process:

Create an ASP.NET Web application.
Create the Entity Data Model (EDM) and connection string to the database that is used by the model.
Create the data service in the Web application.
Enable access to the data service.

After you create and enable the data service by using these procedures, you can try the sample data service you have implemented.

Prerequisites

To use the ADO.NET Data Services framework to create a data service, the following components have to be installed on your computer:

ADO.NET Data Services and the ADO.NET Entity Framework. Both are installed when you install the Microsoft .NET Framework 3.5 Service Pack 1 (SP1) or later versions.

The ADO.NET Data Services framework consists of runtime and data access components. The runtime component implements URI translation, AtomPub and JSON transport formats, and the interaction protocol. The data-access component is a LINQ-enabled data source. A set of conventions maps common language runtime (CLR) types to the URI syntax and payload protocols that the ADO.NET Data Services use.
The Entity Framework tools. These tools are included in Visual Studio 2008 Service Pack 1 (SP1).
ADO.NET data-access providers. These providers are supported by any version of Microsoft SQL Server 2005. This includes SQL Server Express and SQL Server Compact.
The Northwind sample database. To download this sample database, see the download page, Sample Databases for SQL Server.

Create the ASP.NET Web Application

ADO.NET Data Services are an implementation of Windows Communication Foundation services. ADO.NET Data Services run within ASP.NET sites.

If you already have an ASP.NET Web application and prefer to add the sample data service to this existing application, you can skip the following steps and go to the next section, "Create the Entity Data Model."

Note
The following procedure uses the Standard, Professional, and Team System versions of Visual Studio 2008 SP1. If you use Visual Studio Web Developer, you will have to create a new Web site instead of a new Web application.

In Visual Studio, on the File menu, select New, and then select Project.
In the New Project dialog box, select either Visual Basic or Visual C# as the programming language.
In the Templates pane, select ASP.NET Web Application.
Type a name, such as SimpleDataService, for the project.
Click OK.

Create the Entity Data Model

To create an EDM based on a relational database using the ADO.NET Entity Framework:

In Solution Explorer, right-click the name of the ASP.NET project that you just created, and then click Add New Item.
In the Add New Item dialog box, select ADO.NET Entity Data Model.
For the name of the data model, type Northwind.edmx.

Northwind.edmx is the file name for the data model created by the Entity Data Model Wizard. The schema of the data model being created maps one-to-one to the Northwind sample database.
In the Entity Data Model Wizard, select Generate from Database, and then click Next.

Connect the data model to the database by doing one of the following steps, and then click Next:

If you do not have a database connection already configured, click New Connection and create a new connection. For more information, see How to: Create Connections to SQL Server Databases.

Note
If you are using SQL Server 2005, we recommend that you set the MultipleActiveResultSets option to true. If this option is not set to true in the connection string, in the Connection Properties dialog box, click Advanced, and then locate the MultipleActiveResultSets option to true. This option is often needed for traversal of associations in `foreach` loops.

—or—

If you have a database connection already configured to connect to the Northwind database, select that connection from the list of connections.

On the final page of the wizard, select the check boxes for all tables in the database, and clear the check boxes for views and stored procedures.

The final page of the wizard displays a list of the tables, views, and stored procedures that are available from the database. To keep the data model that you create in this topic simple, select only the tables.
Click Finish to close the wizard.

The wizard generates the files that represent the database metadata and adds these files to the project.

Create the Data Service

Creating an ADO.NET data service deploys the data model created in the previous steps as a service that can be accessed by Internet protocol.

To create the data service:

In Solution Explorer, right-click the name of your ASP.NET project, and then click Add New Item.
In the Add New Item dialog box, select ADO.NET Data Service.

Note

Be sure to select ADO.NET Data Service, not other similar options, such as Web Service.
For the name of the service, type Northwind.

Visual Studio creates the XML markup and code files for the new service. By default, the code-editor window opens. In Solution Explorer, the service will have the name, Northwind, with the extension .svc.cs or .svc.vb.
At the beginning of the code for the data service, do one of the following steps to include the namespace of the data model classes that the Entity Data Model Wizard generated:
- If your ASP.NET application uses Visual Basic, add an imports statement.
- If your ASP.NET application uses C#, add a using statement.
The Visual Studio object browser displays the namespace that is derived from the database that the data service uses. In this example, the database is named Northwind, and the namespace is named NorthwindModel.
In the code for the data service, locate the "TODO" comment and replace this comment with the name of the class generated by the Entity Data Model Wizard.

In this example, the name of the class generated by the Entity Data Model Wizard is NorthwindEntities in the NorthwindModel namespace.

Note
Be sure to select ADO.NET Data Service, not other similar options, such as Web Service.

Enable Access to the Data Service

By default, the data service does not enable access to entity or association sets. Access must be explicitly enabled before the data service can return data.

To enable read and write access to all resources that are associated with the service, find the InitializeService function in the class derived from DataService. To this function, add the code that is required to set the resource rights for the container to All. This authorizes access to all items in the data model and should only be used in testing, not in the production environment. In C#, add the line config.SetResourceContainerAccessRule("*", ResourceContainerRights.All), to the InitializeService function, as shown in the following code:

using System;
using System.Collections.Generic;
using System.Data.Services;
using System.Linq;
using System.ServiceModel.Web;
using System.Web;
using NorthwindModel;

namespace SimpleDataService
{
    public class Northwind : DataService< NorthwindModel.NorthwindEntities >
    {
        // This method is called only once to initialize service-wide policies.
        public static void InitializeService(IDataServiceConfiguration config)
        {
            // TODO: set rules to indicate which entity sets and
           // service operations are visible and updatable. 
           // Use *(all sets) only for testing.
            config.SetEntitySetAccessRule("*", EntitySetRights.AllRead);

        }
    }
}

Now, you can run the service from Visual Studio. Press F5 to start the development Web server. The next section explains how to use the newly created data service.

Try the Data Service

For the purpose of this sample, use a Web browser to interact with the data service. A Web browser is an easy way to experiment with the addressing syntax of requests and view the results. However, a Web browser is not the method that most applications use to interact with the data service when it is finished and in use. Typically, applications interact with the data service through code or scripting languages.

Note
For more information about the HTTP syntax used by ADO.NET Data Services, see Simple Addressing Scheme for Data with Uniform URIs (ADO.NET Data Services Framework) and Client Applications of ADO.NET Data Services.

Retrieve the Default Service Document

By default, the XML document that the data service returns is an AtomPub service document. AtomPub is the default serialization method. For more information about the ATOM protocol, see the ADO.NET Data Services team site.

To request the default service document:

Open a Web browser, and then enter a URI such as the following URL. In Visual Studio the ASP.NET Development Server will assign a port number, which will be visible in the URL that is used for testing the service:

http://localhost:50781/northwind.svc

If access rules have been set according to the previous URI, the data service returns the default service document to the browser. This default service document contains a list of entity sets that represent the Northwind data that the data service deploys. This default service document will resemble the following XML sample:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
<service xml:base="http://localhost:1365/Northwind.svc/" 
xmlns:atom="http://www.w3.org/2005/Atom" 
xmlns:app="http://www.w3.org/2007/app" xmlns="http://www.w3.org/2007/app">
<workspace>
 <atom:title>Default</atom:title> 
<collection href="Categories">
 <atom:title>Categories</atom:title> 
 </collection>
<collection href="CustomerDemographics">
 <atom:title>CustomerDemographics</atom:title> 
 </collection>
<collection href="Customers">
 <atom:title>Customers</atom:title> 
 </collection>
<collection href="Employees">
 <atom:title>Employees</atom:title> 
 </collection>
<collection href="Order_Details">
 <atom:title>Order_Details</atom:title> 
 </collection>
<collection href="Orders">
 <atom:title>Orders</atom:title> 
 </collection>
<collection href="Products">
 <atom:title>Products</atom:title> 
 </collection>
<collection href="Region">
 <atom:title>Region</atom:title> 
 </collection>
<collection href="Shippers">
 <atom:title>Shippers</atom:title> 
 </collection>
<collection href="Suppliers">
 <atom:title>Suppliers</atom:title> 
 </collection>
<collection href="Territories">
 <atom:title>Territories</atom:title> 
 </collection>
 </workspace>
 </service>

Retrieve an Entity Set

To browse the contents of the data service, use the entity sets in the default service document as the starting point. For example, some of the entity sets in the default service document for the sample data service include Products, Shippers, and Territories. You can return all the entities in one of these entity sets.

Note
By default Internet Explorer displays feeds instead of XML. To get a pure XML view of the data, you need to change the viewing mode. From the Tools menu, select Internet Options, click the Content tab, click Settings, and clear Turn on feed viewing.

To request a list of products

In the Web browser, enter the following URI:

http://localhost/northwind.svc/Products

By adding /Products to the URI, the URI returns all the products in storage. The following XML shows the first four products returned, which is a partial listing of the results:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<feed xml:base="http://localhost:1365/Northwind.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Products</title>
  <id>http://localhost:1365/Northwind.svc/Products</id>
  <updated>2008-05-22T16:42:14Z</updated>
  <link rel="self" title="Products" href="Products" />
  <entry m:type="NorthwindModel.Products">
    <id>http://localhost:1365/Northwind.svc/Products(1)</id>
    <title type="text"></title>
    <updated>2008-05-22T16:42:14Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Products" href="Products(1)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Categories"
       type="application/atom+xml;type=entry" title="Categories" href="Products(1)/Categories" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details" 
       type="application/atom+xml;type=feed" title="Order_Details" href="Products(1)/Order_Details" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Suppliers" 
       type="application/atom+xml;type=entry" title="Suppliers" href="Products(1)/Suppliers" />
    <content type="application/xml">
      <m:properties>
        <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
        <d:ProductID m:type="Edm.Int32">1</d:ProductID>
        <d:ProductName>Chai</d:ProductName>
        <d:QuantityPerUnit>10 boxes x 20 bags</d:QuantityPerUnit>
        <d:ReorderLevel m:type="Edm.Int16">10</d:ReorderLevel>
        <d:UnitPrice m:type="Edm.Decimal">18.0000</d:UnitPrice>
        <d:UnitsInStock m:type="Edm.Int16">36</d:UnitsInStock>
        <d:UnitsOnOrder m:type="Edm.Int16">0</d:UnitsOnOrder>
      </m:properties>
    </content>
  </entry>
  <entry m:type="NorthwindModel.Products">
    <id>http://localhost:1365/Northwind.svc/Products(2)</id>
    <title type="text"></title>
    <updated>2008-05-22T16:42:14Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Products" href="Products(2)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Categories"
       type="application/atom+xml;type=entry" title="Categories" href="Products(2)/Categories" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details" 
       type="application/atom+xml;type=feed" title="Order_Details" href="Products(2)/Order_Details" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Suppliers" 
       type="application/atom+xml;type=entry" title="Suppliers" href="Products(2)/Suppliers" />
    <content type="application/xml">
      <m:properties>
        <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
        <d:ProductID m:type="Edm.Int32">2</d:ProductID>
        <d:ProductName>Chang</d:ProductName>
        <d:QuantityPerUnit>24 - 12 oz bottles</d:QuantityPerUnit>
        <d:ReorderLevel m:type="Edm.Int16">25</d:ReorderLevel>
        <d:UnitPrice m:type="Edm.Decimal">19.0000</d:UnitPrice>
        <d:UnitsInStock m:type="Edm.Int16">28</d:UnitsInStock>
        <d:UnitsOnOrder m:type="Edm.Int16">40</d:UnitsOnOrder>
      </m:properties>
    </content>
  </entry>
  <entry m:type="NorthwindModel.Products">
    <id>http://localhost:1365/Northwind.svc/Products(3)</id>
    <title type="text"></title>
    <updated>2008-05-22T16:42:14Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Products" href="Products(3)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Categories"
       type="application/atom+xml;type=entry" title="Categories" href="Products(3)/Categories" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details" 
       type="application/atom+xml;type=feed" title="Order_Details" href="Products(3)/Order_Details" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Suppliers"
       type="application/atom+xml;type=entry" title="Suppliers" href="Products(3)/Suppliers" />
    <content type="application/xml">
      <m:properties>
        <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
        <d:ProductID m:type="Edm.Int32">3</d:ProductID>
        <d:ProductName>Aniseed Syrup</d:ProductName>
        <d:QuantityPerUnit>12 - 550 ml bottles</d:QuantityPerUnit>
        <d:ReorderLevel m:type="Edm.Int16">25</d:ReorderLevel>
        <d:UnitPrice m:type="Edm.Decimal">10.0000</d:UnitPrice>
        <d:UnitsInStock m:type="Edm.Int16">65</d:UnitsInStock>
        <d:UnitsOnOrder m:type="Edm.Int16">70</d:UnitsOnOrder>
      </m:properties>
    </content>
  </entry>
  <entry m:type="NorthwindModel.Products">
    <id>http://localhost:1365/Northwind.svc/Products(4)</id>
    <title type="text"></title>
    <updated>2008-05-22T16:42:14Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Products" href="Products(4)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Categories"
       type="application/atom+xml;type=entry" title="Categories" href="Products(4)/Categories" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details" 
       type="application/atom+xml;type=feed" title="Order_Details" href="Products(4)/Order_Details" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Suppliers" 
       type="application/atom+xml;type=entry" title="Suppliers" href="Products(4)/Suppliers" />
    <content type="application/xml">
      <m:properties>
        <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
        <d:ProductID m:type="Edm.Int32">4</d:ProductID>
        <d:ProductName>Chef Anton's Cajun Seasoning</d:ProductName>
        <d:QuantityPerUnit>48 - 6 oz jars</d:QuantityPerUnit>
        <d:ReorderLevel m:type="Edm.Int16">0</d:ReorderLevel>
        <d:UnitPrice m:type="Edm.Decimal">22.0000</d:UnitPrice>
        <d:UnitsInStock m:type="Edm.Int16">6</d:UnitsInStock>
        <d:UnitsOnOrder m:type="Edm.Int16">0</d:UnitsOnOrder>
      </m:properties>
    </content>
  </entry>
  
</feed>

Retrieve a Single Entity

Not only can you return a list of entities in an entity set, you can also request a particular entity. The URI of an individual entity consists of the base URI of the service followed by the name of the entity set and then the final ID of the entity. The ID of the entity is a key value in parentheses.

To request the product whose ID is 1:

In the Web browser, enter the following URI:

http://host/vdir/northwind.svc/Products(1)

The URI that you just entered into the browser retrieves the product with an ID of 1. The following XML shows the results of this request:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://localhost:1365/Northwind.svc/" 
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
m:type="NorthwindModel.Products" xmlns="http://www.w3.org/2005/Atom">
  <id>http://localhost:1365/Northwind.svc/Products(1)</id>
  <title type="text"></title>
  <updated>2008-05-22T16:47:12Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Products" href="Products(1)" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Categories"
     type="application/atom+xml;type=entry" title="Categories" href="Products(1)/Categories" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details"
     type="application/atom+xml;type=feed" title="Order_Details" href="Products(1)/Order_Details" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Suppliers" 
     type="application/atom+xml;type=entry" title="Suppliers" href="Products(1)/Suppliers" />
  <content type="application/xml">
    <m:properties>
      <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
      <d:ProductID m:type="Edm.Int32">1</d:ProductID>
      <d:ProductName>Chai</d:ProductName>
      <d:QuantityPerUnit>10 boxes x 20 bags</d:QuantityPerUnit>
      <d:ReorderLevel m:type="Edm.Int16">10</d:ReorderLevel>
      <d:UnitPrice m:type="Edm.Decimal">18.0000</d:UnitPrice>
      <d:UnitsInStock m:type="Edm.Int16">36</d:UnitsInStock>
      <d:UnitsOnOrder m:type="Edm.Int16">0</d:UnitsOnOrder>
    </m:properties>
  </content>
</entry>

Traverse an Entity Relationship

In this sample data service, some of the values are scalar, such as ProductName and UnitPrice. Other values, such as Categories and Suppliers, represent the ends of navigation properties. Navigation properties are shortcut properties that locate entities related by an EDM association.

For example, the Products entity includes associations to entities that represent both Suppliers and Categories. You can create a URI that traverses these relationships.

To request the supplier of the product whose ID is 2:

In the Web browser, enter the following URI:

http://host/vdir/northwind.svc/Products(2)/Suppliers

The following XML shows the results of this request:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://localhost:1365/Northwind.svc/" 
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
m:type="NorthwindModel.Suppliers" xmlns="http://www.w3.org/2005/Atom">
  <id>http://localhost:1365/Northwind.svc/Suppliers(1)</id>
  <title type="text"></title>
  <updated>2008-05-22T16:50:11Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Suppliers" href="Suppliers(1)" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products" 
     type="application/atom+xml;type=feed" title="Products" href="Suppliers(1)/Products" />
  <content type="application/xml">
    <m:properties>
      <d:Address>49 Gilbert St.</d:Address>
      <d:City>London</d:City>
      <d:CompanyName>Exotic Liquids</d:CompanyName>
      <d:ContactName>Charlotte Cooper</d:ContactName>
      <d:ContactTitle>Purchasing Manager</d:ContactTitle>
      <d:Country>UK</d:Country>
      <d:Fax m:null="true" />
      <d:HomePage m:null="true" />
      <d:Phone>(171) 555-2222</d:Phone>
      <d:PostalCode>EC1 4SD</d:PostalCode>
      <d:Region m:null="true" />
      <d:SupplierID m:type="Edm.Int32">1</d:SupplierID>
    </m:properties>
  </content>
</entry>