本文转自：http://www.drdobbs.com/windows/using-odata-from-aspnet/240168672
By Gastón Hillar, July 01, 2014
Take advantage of your knowledge of both ASP.NET MVC and the ASP.NET Web API to easily create OData endpoints.
OData (Open Data Protocol) is a standardized protocol for creating and consuming data APIs through regular HTTP requests and REST. It is the “ODBC of the Web” and provides a standard solution for very common Web API patterns. For example, OData includes support for queries, paging, and batching, among many other typical requirements.
Creating an OData Endpoint
Microsoft ASP.NET Web API OData adds most of the things necessary to create OData endpoints and easily provide OData query syntax using the ASP.NET Web API (initially introduced in .NET Framework 4.5). ASP.NET Web API 2.2 added many improvements that make it easier to work with OData, including support for OData 4.0. In this article, I provide an example that uses the features provided in Microsoft ASP.NET Web API 2.2 OData.
Creating an OData Endpoint
OData is a standardized protocol for creating and consuming data APIs through regular HTTP requests and REST. One of the most interesting things about OData is that it provides a standard solution for very common Web API patterns. For example, OData includes support for queries, paging, and batching, among many other typical requirements. ASP.NET Web API OData provides many components to make it easy to implement OData services.
ASP.NET Web API 2 was included in Visual Studio 2013 and provided support for OData 3.0. The recently launched ASP.NET Web API 2.2 added support for the newest version of the standardized protocol: OData 4.0. In addition, the newest ASP.NET Web API version includes many interesting improvements related to OData, such as attribute routing, model aliasing, support for Enums, ETags, the $format query option, and the ability to specify which properties can be sorted, expanded, filtered, or navigated.
I want to work with ASP.NET Web API 2.2 in Visual Studio 2013, so I have to run a few NuGet Package Manager Console commands. I‘ll explain the steps to create a project that generates an OData endpoint and allows you to run OData queries on a simple Games entity with support provided by Entity Framework, but you don‘t have to use Entity Framework to take advantage of ASP.NET Web API OData. You can use a similar structure with other data sources.
Create a new ASP.NET Web Application project in Visual Studio 2013. I‘ll use Games for both the project and solution names.
Select the Empty template and check the Web API checkbox in the New ASP.NET Project dialog box. Then, click OK. Visual Studio 2013 will add the folders and core references for the ASP.NET Web API.
Execute the following commands in the NuGet Package Manager Console to access the latest ASP.NET Web API 2.2. The package follows the Semantic Versioning specification, so it has version 5.2.0. After executing this command, the project will be working with ASP.NET Web API 2.2:
|
1 2 |
|
I‘ll use a simple Game entity model to represent the data for the OData service. Add a Gameclass to the Models folder. The following lines show the code for this new class. Notice that I use an int for the key (GameId). I don‘t use a Guid to keep the HTTP requests easier to understand.
|
1 2 3 4 5 6 7 8 9 10 |
|
Now, it is necessary to build the project because I can take advantage of the Visual Studio 2013 scaffolding, which will use reflection to gather information about the Game class.
I want to add a Web API 2 OData controller with CRUD actions to allow me to create, read, update, delete, and list entities from an Entity Framework data context. Visual Studio 2013 will generate the class that handles HTTP requests to perform these actions. Right-click on the Controllers folder within Solution Explorer and select Add | Controller…. Select Web API 2 OData Controller with actions, using Entity Framework, and click Add. Enter GamesControllerfor the controller name and check the Use Async Controller Actions checkbox in the Add Controller dialog box. Select Game (Games.Models) in the Model class dropdown list, and click on the New Data Context… button. Visual Studio will specify Games.Models.GamesContext as the default new data context type name in a new dialog box. Leave the default name and click Add. Finally, click Add when you are back in the Add Controller dialog box.
Visual Studio will create the following GamesContext class in Models/GamesContext.cs:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
The following lines show the generated code for the GamesController class in Controllers/GamesController.cs. GamesController implements the abstract class System.Web.Http.OData.ODataController. ODataController is the base class for OData controllers that supports writing and reading data using the OData formats. I‘ve replaced the deprecated [Queryable] attribute with [EnableQuery]. Sadly, the scaffolding still works with the previous ASP.NET Web API OData version and generates code that includes the deprecated attribute. In fact, in some cases, you might have problems with scaffolding and the newest ASP.NET Web API OData-related libraries. If you notice mixed versions in the packages, you can copy and paste the code to your project instead of following the steps I mentioned before.
The [EnableQuery] attribute enables a controller action to support OData query parameters. The controller uses the async modifier to define asynchronous methods for the POST, PUT, PATCH/MERGE, and DELETE verbs. In addition, you will notice the use of the await keyword and many calls to methods that end with the Async suffix. Microsoft .NET Framework 4.5 introduced asynchronous methods. If you haven‘t worked with the async modified in ASP.NET MVC controllers, you can read Using Asynchronous Methods in ASP.NET 4.5 and in MVC 4 to get a feel for it.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 |
|
Notice the use of the System.Web.Http.AcceptVerbs attribute in the Patch method to make the action method respond to both the PATCH and MERGE HTTP verbs.
|
1 2 |
|
The parameterless GetGames method returns the entire Games collection. The GetGame method with a key parameter looks up a Game by its key (the GameId property). Both methods respond to HTTP GET; and the final method call will depend on the OData query. I‘ll discuss the effects of the [EnableQuery] attribute later.
The rest of the supported HTTP verbs use a single method for each verb: PUT (Put), POST(Post), and DELETE (Delete). Thus, you can query the entity set (GET), add a new game to the entity set (POST), perform a partial update to a game (PATCH/MERGE), replace an entire game (PUT), and delete a game (DELETE).
Take advantage of your knowledge of both ASP.NET MVC and the ASP.NET Web API to easily create OData endpoints.
The generated controller code includes commented code that allows you to add a route for the controller. Change the code in App_Start/WebApiConfig.cs with the following lines that create an entity data model, also known as EDM, for the OData endpoint and add a route to this OData endpoint.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
The System.Web.Http.OData.Builder.ODataConventionModelBuilder class allows you to automatically map CLR classes to an EDM model based on a set of default naming conventions. You can have more control over the generating process by calling ODataModelBuilder methods to create the EDM. The call to the EntitySet method registers an entity set as part of the model. In this case, the name of the entity set is specified as Games in the single argument, and the conventions assume the controller is named GamesController. You can make additional calls to EntitySet to create the EMD model for each entity set you want to make available in a single endpoint.
Finally, the call to config.Routes.MapODataRoute maps the specified OData route and adds it to the OData endpoint. The first parameter specifies a friendly name for the route, and the second parameter sets the URI prefix for the endpoint. Thus, the URI for the Games entity set is /odata/Games. Obviously, it is necessary to add the hostname and port to the URI. For example, if the project URL is http://localhost:50723/, the URI for the Games entity set will be http://localhost:50723/odata/Games. The third parameter is the pre-built Microsoft.Data.Edm.IEdmModel that is retrieved from the builder with a call to the GetEdmModelmethod. In order to check the project URL, right-click on the project name (Games) in Solution Explorer, select Properties, click on Web, and read the configuration in the Project URL textbox.
Working with the OData Endpoint
You can press F5 to start debugging, and the OData endpoint will be ready to process requests. You can use either Telerik Fiddler or the curl utility to compose and send requests to the endpoint with different headers and check the results returned by the OData endpoint. Telerik Fiddler is a free Web debugging proxy with a GUI. The curl utility is a free and open source command line tool to transfer data to/from a server and it supports a large number of protocols. You can easily install curl in any Windows version from the Cygwin package installation option, and execute it from the Cygwin Terminal. I‘ll provide examples for both Fiddler and curl. I‘ll always use http://localhost:50723/ as my project URL in the samples (don‘t forget to replace it with your project URL in your own code).
If you send an HTTP GET request to http://localhost:50723/odata, you will receive the service document with the list of entity sets for the OData endpoint. In this case, the only entity set is Games. You can execute the following line in a Cygwin terminal to retrieve the service document with curl.
|
1 |
|
The following lines show the raw HTTP response:
|
1 2 3 4 5 6 7 8 9 |
|
In Fiddler, click Composer or press F9, select GET in the dropdown menu in the Parsed tab, and enter http://localhost:50723/odata/ in the textbox at the right-hand side of the dropdown (see Figure 1). Then, click Execute and double click on the 200 result that appears on the capture log. If you want to see the raw response, just click on the Raw button below the Request Headers panel (see Figure 2).
Figure 1: Composing a request in Fiddler.
Figure 2: Reading the raw response for the request in Fiddler.
If you add $metadata to the previous URI, the OData endpoint will return the service metadata document that describes the data model of the service with the Conceptual Schema Definition Language (CSDL) XML language. You can execute the following line in a Cygwin terminal to retrieve the service metadata document with curl. In Fiddler, you don‘t need to add a backslash (\) before the dollar sign ($); you can enter the raw URI: http://localhost:50723/odata/$metadata.
|
1 |
|
The following lines show the raw HTTP response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
Establish a breakpoint at the first line of the Post method within the GamesController class to see all the work done under the hood by ASP.NET Web API OData. Then, compose and execute an HTTP POST request to http://localhost:50723/odata/Games in Fiddler with the following values in the request headers and request body:
- Request headers:
Content-Type: application/json - Request body:
{ "Name":"Tetris 2014","Category":"Puzzle","ReleaseYear":2014 }
You can achieve the same effect with the following curl command:
|
1 |
|
The request specifies that the body will use JSON and the Post method in C# receives a Gameinstance. This method works the same way as an ASP.NET MVC controller Post method, in which you check the ModelState.IsValid property value.
|
1 |
|
In this case, the model is valid, and when you continue with the execution, either Fiddler or curl will display the following HTTP 201 Created response with the URI for the recently generated element: http://localhost:50723/odata/Games(1):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
If you send an HTTP GET request to http://localhost:50723/odata/Games(1), you will receive the details for the recently saved element in the default JSON light serialization format. OData 3.0 introduced the JSON light serialization format to reduce footprint. The following two curl commands will produce the same result and will end in a call to the GetGame method with the key parameter that retrieves the Game from the database based on the received key value. (In Fiddler, you just need to add Accept: application/json to Request headers.)
|
1 2 |
|
With or without the Accept: application/json line added to the request headers, the result will use the JSON light serialization format:
|
1 2 3 |
|
If you want to receive the response with the older OData v2 JSON "verbose" serialization format, you just need to add the Accept: application/json;odata=verbose line to the request headers. For example, the following curl command retrieves the same game with the verbose JSON format:
|
1 |
|
The third option is to use the Atom Pub XML serialization format. If you want this format, you just need to add the Accept: application/atom+xml line to the request headers. The following curl command retrieves the same game with the Atom Pub XML format:
|
1 |
|
The GetGame method is decorated with the [EnableQuery] attribute; hence, you can use OData query parameters. For example, the following HTTP GET request uses the $select option to specify that it just wants the Name property to be included in the response body: http://localhost:50723/odata/Games(1)?$select=Name. In curl, you need to add a backslash (\) before the dollar sign ($):
|
1 |
|
The following lines show the raw HTTP response that only includes the requested property value:
|
1 2 3 |
|
The GetGames method is also decorated with the [EnableQuery] attribute. Thus, you can use the $filter query option to select the games that satisfy a specific predicate expression. For example, the following HTTP GET request uses the $filter option with the eq (equal) operator to retrieve the game whose name is equal to Tetris 2014:
|
1 |
|
In curl, you need to add a backslash (\) before the dollar sign ($):
|
1 |
|
The following lines show the raw HTTP response:
|
1 2 3 4 5 6 7 |
|
The code for the GetGames method simply includes the [EnableQuery] attribute and is just one line that returns an IQueryable<Game>. As you can see, ASP.NET Web API OData performs a lot of work under the hood to parse and translate the OData query options and operators to a Linqquery.
Conclusion
As you have learned from this simple example, ASP.NET Web API OData allows you to take advantage of your existing knowledge of both APS.NET MVC and the ASP.NET Web API to easily create OData endpoints. The good news is that you can customize all the components and easily add features, such as complex server-side behavior modification via the addition of OData actions. Enjoy!
Gastón Hillar is a senior contributing editor at Dr. Dobb‘s.