OData Programming Cookbook for .NET Developers

As we will use ADO.NET Entity Framework as the data source of our OData service, make sure you have a sample database, such as Northwind, installed in a local SQL Server instance. You can use SQL Express instance (the free version of SQL Server) for convenience.

The source code for this recipe can be found in the \ch01\ODataEFServiceSln\ directory.

To concentrate on the OData service generation and make the progress simple and clear, we will use an empty ASP.NET web application with a single OData service for demonstration. The detailed steps are as follows:

In our sample web project, there are only two items. One is the ADO.NET Entity Framework data model and the other is the WCF Data Service item (as shown in the following project structure screenshot).

WCF Data Service has helped encapsulate all the underlying details of implementing an OData service. When using WCF Data Service to generate OData service, what we need to do is:

Also, as the name indicates, WCF Data Service is a special implementation of WCF service. And more specifically, WCF Data Service is a specially implemented WCF service over the REST HTTP endpoint (by using the WebHttpBinding binding type). In most cases, we do not need to take care of those WCF service-specific configuration details (in web.config file). If we open the web.config file of our sample service, we can find that there is almost nothing defined within the<system.serviceModel> element for the WCF configuration (see the following screenshot).

Make sure you have a sample database, such as Northwind, installed in a local SQL Server instance. You can use an SQL Express instance (the free version of SQL Server) for convenience.

The source code for this recipe can be found in the \ch01\ODataLINQ2SQLServiceSln\ directory.

You can follow the steps given for creating an OData service from LINQ to SQL data entities:

Although we directly use the LINQ to SQL data model class as the data source, the WCF Data Service runtime actually treats the LINQ to SQL data model class like a custom data source type. Therefore, any public member (of the data model class) who implements the IQueryable interface will be exposed as an entity set in the generated service. We will talk more about using custom data source type for WCF Data Service within the Using custom data objects as the data source of WCF Data Service recipe of this chapter.

By default, the WCF Data Service, which uses the LINQ to SQL data model class, does not support editing/updating operations. In order to make the LINQ to SQL based WCF Data Service support editing/updating, we need to implement the IUpdatable interface (under System.Data.Services namespace) on the LINQ to SQL data model class (see the following code snippet).

partial class NorthwindDataContext: IUpdatable
{
......
}

For detailed information about implementing IUpdatable interface for LINQ to SQL data model class, you can refer to the following MSDN reference:

How to: Create a Data Service Using a LINQ to SQL Data Source (WCF Data Services) available at http://msdn.microsoft.com/en-us/library/ee373841.aspx

To play with WCF RIA Service, we need to install Visual Studio 2010 Service Pack 1, which includes the runtime and development tools for WCF RIA Service V1 SP1.

Visual Studio 2010 Service Pack 1 is available at http://support.microsoft.com/kb/983509.

The source code for this recipe can be found in the \ch01\ODataRIAServiceSln\ directory.

When creating the sample WCF RIA Service, we enable the OData endpoint on it by selecting the Expose OData endpoint option in the Add New Domain Service Class dialog. Actually, we can find the magic behind the dialog within the web.config file (see the following configuration fragment).

The dialog adds a domainServices/endpoints/add element in the<system.serviceModel> section. This element tells the runtime to add a new endpoint for each WCF RIA Service and this endpoint will generate an OData format response (by using the System.ServiceModel.DomainServices.Hosting.ODataEndpointFactory type).

Likewise, if you have some existing WCF RIA Services, which were created without the OData endpoints enabled, we can simply make them OData enabled by adding the previous configuration settings manually in the web.config file.

This sample case still uses the same ADO.NET Entity Framework based WCF Data Service like what we've discussed in the previous recipes. We will add some custom operations to it so as to expose additional data to client.

The source code for this recipe can be found in the \ch01\CustomOperationServiceSln\ directory.

As shown in the previous sample code, we can add custom operations to WCF Data Service in the same way as we add service operations to a standard WCF REST service. Also, the WebGetAttribute attribute over each sample operation indicates that the operation can be accessed through the HTTP GET method (the expected method for operations that return data). We can also apply the WebInvokeAttribute attribute so as to make the operation support other HTTP methods.

Also, in order to allow clients to invoke custom operations, we need to grant the access rules in the InitializeService function just like we do for entity sets exposed in WCF Data Service.

For more information about access rules and permission configuration on WCF Data Service, see Chapter 7, Working with Security.

The service here will expose two stored procedures from the Northwind database. They are the CustOrdersOrders procedure (return Order list of a given customer) and the Ten Most Expensive Products procedure. The following are the raw signatures of these two stored procedures:

ALTER PROCEDURE [dbo].[Ten Most Expensive Products] AS ...
ALTER PROCEDURE [dbo].[CustOrdersOrders] @CustomerID nchar(5)
AS ...

The source code for this recipe can be found in the \ch01\ODataSPServiceSln\ directory.

To use stored procedures in WCF Data Service (using the ADO.NET Entity Framework data model as data source), we need to import stored procedures as functions in the generated EF data model class. In this sample, we create some custom data types for the return value of each stored procedure mapping function. This is because in most cases, the returned data columns from a given stored procedure don't exactly match a complete data entity type (corresponding to the target database table).

In addition to the imported functions on EF data model class, we also need to add custom operations within the WCF Data Service class. These operations simply delegate the operation call to the corresponding stored procedure mapping functions.

When calling a service operation mapping to a void stored procedure (which does not return any value), we can simply use the URL address of the operation (relative from the service base address). For stored procedures that take some input parameters, we can supply the parameters by using query strings in the operation URL (as shown in the previous GetOrdersByCustomer operation sample).

In this recipe, we will create a WCF Data Service for exposing some books and book categories information to clients. Instead of using ADO.NET Entity Framework or LINQ to SQL, we will define some custom CLR types to represent the data model of the sample service.

The source code for this recipe can be found in the \ch01\CLRObjDataServiceSln\ directory.

Now, let's take a look at what makes these things work. As we can see, each entity set we expose in the sample service is coming from its corresponding member property defined in the data context type. Such member properties should be declared as IQueryable<Entity Type> type so that the WCF Data Service runtime can correctly locate them and expose them as entity sets in the service.

For each custom entity type, we must specify a key property by using the DataServiceKeyAttribute attribute. This key property is used for identifying entity instances in a given entity set (just like the primary key for the relational table).

The BookCategory entity type has a Books property of the List<BookInfo> type. Such kind of entity collection properties will be automatically treated as Navigation properties on the target entity type. For OData clients, they can use these Navigation properties (by using relative URI address) to retrieve the associated subentities from the primary entity instance (see the previous sample code).

We have discussed LINQ to SQL based data sources in the previous recipe. Actually, LINQ to SQL is a special case of a custom data object based data source, since the LINQ to SQL data model has already done most of the work for us. If you are interested in finding out more about building WCF Data Service data source with a custom CLR type, you can refer to the following MSDN reference:

Reflection Provider (WCF Data Services) available at http://msdn.microsoft.com/en-us/library/dd723653.aspx

In this recipe we will build a WCF Data Service based on the Northwind EF data model. The service will expose two data entity sets, one is from the Categories table, and the other is from the Products table. For demonstration, we will add two custom Interceptors against these two entity sets so as to change their query and delete behavior.

The source code for this recipe can be found in the \ch01\QIDataServiceSln\ directory.

In the sample service, we have applied a QueryInterceptor on the Products entity set. Actually, a QueryInterceptor is just a function, which returns a Lambda expression with the following signature:

Func<[Entity Type], bool>

Then, why does it use an expression instead of a delegate function directly? The reason is that by using an expression, it is more convenient for the underlying WCF Data Service runtime to forward such QueryInterceptor injected code logic to the actual query provider (such as the ADO.NET Entity Framework provider, which will generate T-SQL based on the query) that will fetch the data from the backend data source.

QueryInterceptor will be invoked when HTTP GET based query requests are received against the target entity set; while ChangeInterceptor will be invoked when update/modify operations are called. In this sample, our onChangeCategories Interceptor will check the incoming request to see if it is a delete operation against the Categories entity set. If the checking result is true, a DataServiceException will be thrown out. In a real-world case, we can apply more complicated code logic to change the default update/modify behavior against the target entity sets.

For more information about using Interceptors in WCF Data Service, you can read the following MSDN reference:

Interceptors (WCF Data Services) available at http://msdn.microsoft.com/en-us/library/dd744842.aspx

In this recipe, we will create a WCF Data Service, which will expose the session states and HTTP client user headers (of the ASP.NET host web application) as entity sets to the service callers. Also, to make the service code simple and clear, we will use custom CLR types instead of a ADO.NET Entity Framework data model as the service data source.

The source code for this recipe can be found in the \ch01\WebContextDataServiceSln\ directory.

The WCF Service programming model provides built-in support for service code to access ASP.NET context data in case the service is hosted in an ASP.NET web application. Since WCF Data Service is a special implementation of WCF Service, accessing ASP.NET context data in WCF Data Service code is naturally supported too. Actually, whenever a new WCF Data Service is created in Visual Studio (within an ASP.NET web project), the IDE will automatically enable the ASP.NET Compatibility mode (see the following screenshot) in the web.config file, which is necessary for WCF Service (also WCF Data Service) to access ASP.NET context data of the hosting web application.

For demonstration purposes, our sample ASP.NET web application also contains a simple ASP.NET web page, which will help in generating some test session states data (see the following InitSession page class).

public partial class InitSession : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
if (Session.Count == 0)
{
Session.Add("string item", "some text");
Session.Add("int item", 120);
Session.Add("boolean item", true);
Session.Add("date item", DateTime.Now);
Session.Add("array item", new int[]{1,2,3});
}
}
}

In this recipe, we will choose filesystem as an example and build a WCF Data Service, which exposes the information of all files within a given directory. Also, we will create several custom classes in order to implement the custom WCF Data Service provider. The following class diagram (generated via Visual Studio Architecture Modeling tools) can help you get an overview of these custom types and their dependency relationships:

The source code for this recipe can be found in the \ch01\FileDataServiceSln\ directory.

In the previous steps, we created all the custom provider classes from bottom to top according to the class structure diagram shown earlier. Now, let's have a look at how they work together in a top-to-bottom approach.

The DirectoryFileDataService<T> class is the top most type among all the custom provider classes. This class is derived from the DataService<T> base class so that it can be directly used by WCF Data Service as service class. The DirectoryFileDataService<T> class also implements the IServiceProvider interface because it will be asked to provide certain implementations of various kind of custom service providers. In this case, we have implemented the metadata provider (IDataServiceMetadataProvider interface) and the query provider (IDataServiceMetadataProvider interface), which are used for publishing service metadata and exposing entity sets. In addition, there are other providers used for implementing more advanced features, for example, the IDataServiceUpdateProvider interface for implementing update functions, the IDataServicePagingProvider interface for implementing paging functions, and the IDataServiceStreamsProvider interface for implementing data streaming functions. The following diagram shows the calling pipeline from WCF Data Service class to custom service providers and the backend data source objects:

The DirectoryFileDataService type uses instances of the DirectoryFileDataServiceQueryProvider and DirectoryFileDataServiceMetadata types to serve the metadata and query service requests. These two provider instances also use the DirectoryFileDataContext type instance for retrieving the underlying data entity sets' type information and query root object.

Finally, we come to the FileEntity class. You might think it is quite similar to the custom entity types we defined in the Using custom data objects as the data source of WCF Data Service recipe. The important difference is that we do not have to apply any additional attributes (such as the DataServiceKey and DataServiceEntity attributes) on the FileEntity class (compared to those entity types used by a custom CLR objects based data source). In other words, by using a custom WCF Data Service provider, we can make use of existing predefined custom data types (whether they have applied those special attributes under System.Data.Services namespace or not) as OData service entities.

WCF Data Service providers have opened the door for developers to extend an OData service to their own data sources in a very flexible way. By using the provider-based model, we can control almost every aspect of WCF Data Service customization (such as the querying and updating processes). Whenever you want to customize a certain part of a WCF Data Service, just find the corresponding provider interface and implement it.

For more information about building custom WCF Data Service providers, you can refer to the following MSDN reference:

Custom Data Service Providers available at http://msdn.microsoft.com/en-us/data/gg191846