A Beginner's Tutorial for Creating WCF Data Services

• Download sample - 419.6 KB

Introduction

In this article we will see how we can use WCF data services to create ODATA complaint RESTful services. We will see how we can use visual studio provided template to create the WCF data services, how we can use them using ODATA protocol and how to consume them from a .Net client application.

Background

What is ODATA

ODATA is a protocol using which we can share and access the data using AtomPub protocol. This AtomPub protocol is mainly used in creating feeds from websites. It is built on of the REST architecture philosophy where the CRUD operations in the remote data resource can be pefromed using HTTP protocols like GET, PUT, POST and DELETE. (For more details on this refer: A Beginner's Tutorial on Creating WCF REST Services[^]).

What is WCF Data Service

WCF data service is a ready made templates available with Visual studio that gives us the possibility for creating ODATA complaint WCF services easily. It is built on top of WCF REST Services.

WCF Data services were earlier known as ADO.NET data services. This templates gives us the possibility of exposing any kind of data from the service using ODATA protocol. It is implemented on top of WCF REST services to provide ODATA complaint data access and it has most of the boilerplate functionality already in place. The developer just need to configure the data source and let the service template know what data needs to exposed and with what permissions.

Using the code

Creating WCF Data Service

Let us now see how we can create a simple WCF data service that will expose a simple database over ODATA protocol.

Creating the Service

Now to create the service, we first need to create a simple ASP.NET Web Application which will provide the hosting environment for this service. So let us first create a simple ASP.NET Web application.

Once we have ASP.NET web application ready, the next thing would be to add a database in the App_data folder. We will create Books table and will try to perform CRUD operations on this table.

To perform the Database operations within the service lets use Entity framework. (to know about entity framework refer: An Introduction to Entity Framework for Absolute Beginners[^]). The generated Entity will look like following.

Let us also add some sample data in the table so that we should be able to test the service.

Now we have the database and the data access logic in place. Let us now Add a WCF Data service to this project.

Once we add this service template all the required reference will be added in the project and the service template will give us a Service class implementation template like this:

Now in this template we will have to specify(1 in above image) the data source class name in the service implementation class' base class i.e. DataService<T>. In our case this class is SampleDbEntities. In second place(2 in image), we need to specify the entities that we want to expose via this service and the access rule for these entities. Let us simply give All permissions to all entities by putting a *.

The resulting code will look like:

public class BooksWcfDataService : DataService<SampleDbEntities>
{
    // This method is called only once to initialize service-wide policies.
    public static void InitializeService(DataServiceConfiguration config)
    {
        config.SetEntitySetAccessRule("*", EntitySetRights.All);
        config.SetServiceOperationAccessRule("*", ServiceOperationRights.All);
        config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V2;
    }
}

Note: The EntitySetRights and ServiceOperationRights enumeration values is an important thing to look into to take finer control over the permissions.

Now let us run the service and try to see the results in the browser by writing ODATA complaint URL queries.

http://localhost/BooksWcfDataService.svc/Books

http://localhost/BooksWcfDataService.svc/Books(3)

Supporting JSON Format

The ODATA protocol also specifies that any query with $format=json parameter should return the same result in JSON format. WCF REST services provide support for JSON output but the WCF data services by default don't support this. To enable this support we need to check the incoming request and if it contains $format=json in the parameter list we need to set the header to accept the application/json requests.

The easiest way to do this is to have a custom attribute which can monitor the request and apply the required headers before this request is processed. There is a ready made class available in MSDN code gallery that does the exact same thing [http://archive.msdn.microsoft.com/DataServicesJSONP[^]]

From the above link we need to use the JSONPSupportBehaviorAttribute class and decorate the service implementation class with it. This class will internally use its custom message dispatch behavior to take care of the header information. The resulting implementation of the class looks like:

[JSONPSupportBehavior]
public class BooksWcfDataService : DataService<SampleDbEntities>
{
    // This method is called only once to initialize service-wide policies.
    public static void InitializeService(DataServiceConfiguration config)
    {
        config.SetEntitySetAccessRule("*", EntitySetRights.All);
        config.SetServiceOperationAccessRule("*", ServiceOperationRights.All);
        config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V2;
    }
}

Note: Looking at the implementation will make the internal processing of this component very clear. Although, it might be little complicated and confusing for the beginner's to get the full understanding of these classes.

Now since we have the json support enabled for our service let us try to see the json response.

http://localhost/BooksWcfDataService.svc/Books?$format=json 

Consuming WCF Data service

Now we have seen that how we can create a WCF data service and how we can get the result back simply by using HTTP protocols and writing ODATA complaint urls. Now if we need to access this WCF data service via a .NET client application, how can we do that. So let us create a simple website to see how we can consume this WCF data service in a step by step fashion.

1. Add a simple GridView on the web page
2. Add the service reference of the WCF data service.
3. Create the SampleDbEntities in the client application using service reference.
4. Pass the Uri of the service i.e. svc file in the constructor of the SampleDbEntities.
5. Now use the object of SampleDbEntities as as normal Entity framework entities.

Following code shows the resulting code in our code behind file.

protected void Page_Load(object sender, EventArgs e)
{
    ServiceReference1.SampleDbEntities entities = 
        new ServiceReference1.SampleDbEntities
            (
                new Uri("http://localhost:51039/BooksWcfDataService.svc")
            );

    GridView1.DataSource = entities.Books;
    GridView1.DataBind();
}

And now running the client application will give us the result in a gridview as:

Point of interest

In this article we saw how we can easily create WCF Data services. We also saw how we can configure the response format to either XML or json. We developed a client application to consume this WCF Data service. This article is meant to be the starting point for creating data services and it doesn't talk about various configurations related to permissions etc. Reading about these is highly recommended. I hope this article is somewhat informative.

History

• 04 April 2013: First version.