Summary: This document describes how to create and use Microsoft® ADO.NET Data Services, and discusses various details around the URI and payload formats. This document is meant as an introduction to ADO.NET Data Services and thus covers the core aspects of the technology, defering discussion of more advanced topics to companion documents.
The goal of Microsoft® ADO.NET Data Services is to enable applications to expose data as a data service that can be consumed by web clients within corporate networks and across the internet. A data service is reachable via regular HTTP requests, using standard HTTP verbs such as GET, POST, PUT and DELETE to perform CRUD operations against the service. The payload format used by the service is controllable by the application, but all options are simple, open formats such as JSON and Atom/APP.
The use of web-friendly technologies make ADO.NET Data Services ideal as a data back-end for AJAX-style applications, Rich Interactive Applications and other applications that need to operate against data that is stored across the web.
In order to create a data service using ADO.NET Data Services in your own environment you will need Microsoft Visual Studio 2008 SP1. If you will be using your data service to access data stored in a relational database, you will also need a database with updated data-access providers, such as Microsoft SQL Server 2005 or 2008 (any edition, including SQL Server Express, will work). Updated providers are also available for third party database such as Oracle and DB2. For more information on third party providers see http://msdn.microsoft.com/data.
The ADO.NET Entity Framework runtime and associated tools are included in Visual Studio 2008 SP1.
The ADO.NET Data Service server framework is comprised of two halves. The top-half is the runtime itself; this part is “fixed”, and it implements URI translation, the Atom/JSON wire formats, the interaction protocol, etc. This is what makes an ADO.NET Data Service look like an ADO.NET Data Service. The bottom half is the data-access layer and is pluggable. Communication between layers happens in terms of the IQueryable interface plus a set of conventions to map CLR graphs into the URI/payload patterns of ADO.NET Data Services.
The first step in creating an ADO.NET Data Service is to determine the data source that is to be exposed as a set of REST-based endpoints (ie. select or create a data access layer). For relational data stored in Microsoft SQL Server or other 3rd Party databases, ADO.NET Data Services currently enables easily exposing a conceptual model created using the ADO.NET Entity Framework (EF). For all other data sources (XML document, web service, application logic layer, etc) or to use additional database access technologies (ex. LINQ to SQL), a mechanism is provided which enables any data source, as per the plug-in model described above, to be exposed as an ADO.NET Data Service.
To create a data service which exposes a relational database through an Entity Framework conceptual model see “Creating a Data Service using the ADO.NET Entity Framework”. To create a data service which exposes another data source see “Creating a Data Service from any Data Source”.
ADO.NET Data Services are a specialized form of Windows Communication Foundation services, and thus can be hosted in various environments. The below example will create an ADO.NET Data Service which is hosted inside an ASP.NET site. In order to create a data service, you must first create a web project; you will then need to establish a connection with the database that will be exposed by the service, and then create the data service itself within the web application. Below is a step-by-step description of this process.
NOTE: These steps are for Visual Studio Standard, Professional and Team System editions. If using Visual Studio Web Developer, create a new “Web Site” rather than a “Web Application”. The remaining workflow does not change. While this example uses a web application, other project types (websites) and hosting mechanisms are also supported.
- Create the project
- Create a “Web Application” project by going to the File menu in Visual Studio and choosing New Project. When the New Project window appears, choose either Visual Basic or Visual C# as the programming language. Within the language category click on “Web”, and select “ASP.NET Web Application” from the right-hand panel. Choose a name for the project, for example SimpleDataService, and click OK. NOTE: If you already have a web application and you’d like to add a new data service to it, you can skip step 1 and go directly to step 2.
- Create an Entity Data Model representation of your database using the ADO.NET Entity Framework
- Assuming that you already have a database that you want to expose as a data service, we will create an Entity Data Model schema that maps 1:1 with your database. Select SimpleDataService Add New Item in Visual Studio. The Add New Item window will appear, choose “ADO.NET Entity Data Model”, give it a name and click Add. We will use the Northwind sample database throughout this example, so we will use “Northwind” as our name (Northwind.edmx being the generated file name).
- In the rest of the step-by-step guide we will assume you are using the Northwind sample database, so the database connection created here should point to Northwind.NOTE:
- Create a data service
- To create the data service itself, select SimpleDataService Add New Item in Visual Studio. Choose “ADO.NET Data Service” from the list of item templates, give it a name (e.g. Northwind) and click add. NOTE: The template wizard offers both an ADO.NET Data Services option as well as a Web Service option.Select “ADO.NET Data Service”.
- Visual Studio will open the code file for the new service by default. You can also find the file in the Solution Explorer; it will have the name you indicated, with a “.svc.cs” or “.svc.vb” extension. In C# add a “using” clause at the beginning of the file to include the namespace of the model. In Visual Basic, this namespace is already imported at the project level automatically along with the project namespace. By default the model namespace is derived from the database that was used for the data service, unless changed when the EDM is created, for example if the database was called Northwind the namespace will be NorthwindModel.
- Locate the “TODO: put your data source class name here” comment that indicates to put in the class name that represents the database, and replace it with the name of the class that was generated by the Entity Data Model Wizard in step 2.b. Again, the name is derived from the database name, unless changed, so for example if the database is called “Northwind” the class will be “NorthwindEntities”.
- Enable access to the data service
- By default a data service does not expose any resources.For security purposes, access to resources needs to be explicitly enabled before any resources or associations are accessible. To enable read and write access to all resources in the Entity Data Model associated with the service; locate the InitializeService method as shown in Example 1 below.