技术摘录

只是一些项目相关技术的摘录

OData services入门----使用ASP.NET Web API描述

oData 是一种应用层协议,设计它的目的在于提供一组通过HTTP的交互操作。除了提供一些基本的操作(像增删改查),也提供了一些高级的操作类似过滤数据和实体的导航。

下面的文章我将用oData 提供给ASP.NET Web API 的功能来建立一个小服务。

oData

你现在可能在想为什么你的web apps需要另外的协议。JSON难道不是很简单吗?XML services 不够好?嗯,事实上,oData扩展了上述的协议但是不是取代他们。他可以被XML(ATOM)或者JSON取代但是oData的重要在于它符合REST原则。在某种意义上,它建立在'简单'的REST HTTP 服务上,并且有着清晰的目标——简化和标准化我们操作和查询数据的方式。如果你过去在给你的REST服务创建搜索、过滤、或者分页API的时候感觉很麻烦,那么oData将是一个不错的选择。

一些oData查询语法的规则:

  • Entity set – /Artists

  • Entity by id – /Artists(1)

  • Sorting – /Artists?$orderby=Name

  • Filtering – /Artists?$filter=Name eq 'Gridlock'

上面的这些只是冰山一角。

概念介绍的差不多了,让我开始项目吧。很幸运,ASP.NET Web API 可以帮我们很方便的创建oData。

创建项目

首先我们需要创建一个ASP.NET Web API项目。我们是不需要MVC的相关的东西(视图,js库,等)。

oData的功能是由一个独立的程序集提供的。请注意,现在这个程序集还是在预览版,最新的官方发布版本是0.3 RC (this blogpost 点击链接参看项目信息,这个是英文的哦)。

很不幸,使用最新的ODataLib程序集还有一些方法(例如:过滤)没有实现,不过不用担心最新的更新将会解决这个问题。因为没有必要学习过时的API,我们将使用最新的发布版本在http://www.myget.org/F/aspnetwebstacknightly/,使用nuget。如果你不会使用nuget,可以看看这里here

一旦你获取了nightly build nuget source。可以使用Manage NuGet Packages安装最新的Web API OData 包,确保你选择'Include Prerelease'在上面的下拉框中,如下图所示。

另外需要注意的是Web API OData 还在开发阶段,还有一些功能还不支持。不过基本功能已经完成。

数据模型

我们需要一些简单的模型去操作,使用Entity Framework 和 SQL CE 4,但是Web API's OData也支持其他的数据库和持久化技术。

CREATETABLE[Album](    [AlbumId]INTNOTNULLIDENTITY,    [Title]NVARCHAR(160) NOTNULL,    [ArtistId]INTNOTNULL,    [GenreId]INTNOTNULL,    [ReleaseDate]DATETIME,    CONSTRAINT[PK_Album]PRIMARYKEY  ([AlbumId])); CREATETABLE[Artist](    [ArtistId]INTNOTNULLIDENTITY,    [Name]NVARCHAR(120),    CONSTRAINT[PK_Artist]PRIMARYKEY  ([ArtistId])); CREATETABLE[Genre](    [GenreId]INTNOTNULLIDENTITY,    [Name]NVARCHAR(120),    [Description]NVARCHAR(1020),    CONSTRAINT[PK_Genre]PRIMARYKEY  ([GenreId])); ALTERTABLE[Album]ADDCONSTRAINT[FK_AlbumArtistId]FOREIGNKEY ([ArtistId]) REFERENCES[Artist] ([ArtistId])      ONDELETE NO ACTION ONUPDATE NO ACTION; CREATEINDEX[IFK_AlbumArtistId]ON[Album] ([ArtistId]); ALTERTABLE[Album]ADDCONSTRAINT[FK_AlbumGenreId]FOREIGNKEY ([GenreId]) REFERENCES[Genre] ([GenreId])      ONDELETE NO ACTION ONUPDATE NO ACTION; CREATEINDEX[IFK_AlbumGenreId]ON[Album] ([GenreId]); 

 

你可以创建一个新的SQL CE数据库在App_Data文件夹下面,使用内置的环境去执行SQL代码。请注意执行SQL只能一行一行执行,不支持一下子执行多次语句。一旦数据库表结构完成了我们可以用VS2012向导生成Entity Data Model。

最后我们将得到一个DbContext类去进行数据操作。

$metadata endpoint 和 IEdmModel

正如我之前提到的,oData标准定义了一个特别的metadata endpoint,它包含一个定义了实体集,关系,实体类型和操作的文档。这些保证了oData是自描述的,能够让客户端去生成表示服务端类型的客户端代码,简化了服务的访问方式。Metadata endpoint应该在/$metadata下可用。如果你熟悉SOAP服务,你可以把oData和它类比一下。

GET http://services.odata.org/Northwind/Northwind.svc/$metadata

Metadata文档使用oData通用架构定义(OData Common Schema Definition Language (CSDL))。很幸运,ASP.NET Web API可以把$metadata endpoint直接暴露给我们,只要我们的模型继承IEdmModel

 

publicclass ModelBuilder{    public IEdmModel Build()    {        ODataModelBuilder modelBuilder = new ODataConventionModelBuilder();        modelBuilder.EntitySet<Album>("Albums");        modelBuilder.EntitySet<Artist>("Artists");        modelBuilder.EntitySet<Genre>("Genres");         return modelBuilder.GetEdmModel();    }} 

 

public IEdmModel BuildExplicitly(){    ODataModelBuilder modelBuilder = new ODataModelBuilder();    EntitySetConfiguration<Genre> genres = modelBuilder.EntitySet<Genre>("Genres");    EntityTypeConfiguration<Genre> genre = genres.EntityType;    genre.HasKey(g => g.GenreId);    genre.Property(g => g.Name);    genre.Property(g => g.Description);     //(...)return modelBuilder.GetEdmModel();} 

 

 

 

使用oData

Microsoft.AspNet.WebApi.OData提供可一系列的类扩展了Web API

publicstaticclass WebApiConfig{    publicstaticvoid Register(HttpConfiguration config)    {        var modelBuilder = new ModelBuilder();        IEdmModel model = modelBuilder.Build();        config.Routes.MapODataRoute("OData", null, model);        config.EnableQuerySupport();    }} 

 

这些代码(Global.asax.cs)做了两件事情:

  1. 通过路由注册我们的模型表示方法-

  2. 使查询可用

现在我们的服务应该自动知道怎么去处理OData ~/$metadata 请求。很酷,不是吗? 

 <edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0"><edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="1.0"><Schema xmlns="http://schemas.microsoft.com/ado/2009/11/edm" Namespace="Piotr.ODataWebApiService.Service.Models"><EntityType Name="Album">...</EntityType><EntityType Name="Artist">...</EntityType><EntityType Name="Genre">...</EntityType><Association        Name="Piotr_ODataWebApiService_Service_Models_Album_Artist_Piotr_ODataWebApiService_Service_Models_Artist_ArtistPartner">...</Association><Association Name="Piotr_ODataWebApiService_Service_Models_Album_Genre_Piotr_ODataWebApiService_Service_Models_Genre_GenrePartner">...</Association><Association Name="Piotr_ODataWebApiService_Service_Models_Artist_Albums_Piotr_ODataWebApiService_Service_Models_Album_AlbumsPartner">...</Association><Association Name="Piotr_ODataWebApiService_Service_Models_Genre_Albums_Piotr_ODataWebApiService_Service_Models_Album_AlbumsPartner">...</Association></Schema><Schema xmlns="http://schemas.microsoft.com/ado/2009/11/edm" Namespace="Default">...</Schema></edmx:DataServices></edmx:Edmx> 

 

控制器

现在是时候去检测一下我们的成果了。我们应该添加一个暴露oData资源的控制器。正如你将看到的,这和一个平常的CRUD控制器很不一样。暴露一个oData实体非常容易。

 

 [ODataRouting][ODataFormatting]publicclass ArtistsController : ApiController{    private AlbumsContext db = new AlbumsContext();     // GET /Artists    // GET /Artists?$filter=startswith(Name,'Grid')    [Queryable]    public IQueryable<Artist> Get()    {        return db.Artists;    }             protectedoverridevoid Dispose(bool disposing)    {        db.Dispose();        base.Dispose(disposing);    }} 

 [ODataRouting][ODataFormatting]publicclass ArtistsController : ApiController{    private AlbumsContext _db = new AlbumsContext();     // GET /Artists    // GET /Artists?$filter=startswith(Name,'Grid')    [Queryable]    public IQueryable<Artist> Get()    {        return _db.Artists;    }     // GET /Artists(2)public HttpResponseMessage Get([FromODataUri]int id)    {        Artist artist = _db.Artists.SingleOrDefault(b => b.ArtistId == id);        if (artist == null)        {            return Request.CreateResponse(HttpStatusCode.NotFound);        }         return Request.CreateResponse(HttpStatusCode.OK, artist);    }     public HttpResponseMessage Put([FromODataUri] int id, Artist artist)    {        if (!_db.Artists.Any(a => a.ArtistId == id))        {            return Request.CreateResponse(HttpStatusCode.NotFound);        }        //overwrite any existing id, as url is more explicit         artist.ArtistId = id;        _db.Entry(artist).State = EntityState.Modified;         try        {            _db.SaveChanges();        }        catch (DbUpdateConcurrencyException)        {            return Request.CreateResponse(HttpStatusCode.NotFound);        }         return Request.CreateResponse(HttpStatusCode.NoContent);    }     public HttpResponseMessage Post(Artist artist)    {        var odataPath = Request.GetODataPath();        if (odataPath == null)        {            return Request.CreateErrorResponse(HttpStatusCode.BadRequest,                "ODataPath not present in the request.");        }         var entitySetPathSegment            = odataPath.Segments.FirstOrDefault() as EntitySetPathSegment;         if (entitySetPathSegment == null)        {            return Request.CreateErrorResponse(HttpStatusCode.BadRequest,                "ODataPath does not start with entity set path segment");        }         Artist addedArtist = _db.Artists.Add(artist);        _db.SaveChanges();        var response = Request            .CreateResponse(HttpStatusCode.Created, addedArtist);         response.Headers.Location = new Uri(Url.ODataLink(                              entitySetPathSegment,                              new KeyValuePathSegment(ODataUriUtils                            .ConvertToUriLiteral(addedArtist.ArtistId                            , ODataVersion.V3))));        return response;    }     public HttpResponseMessage Patch([FromODataUri] int id,        Delta<Artist> artistPatch)    {        Artist artist = _db.Artists            .SingleOrDefault(p => p.ArtistId == id);        if (artist == null)        {            thrownew HttpResponseException(HttpStatusCode.NotFound);        }         artistPatch.Patch(artist);        _db.SaveChanges();         return Request.CreateResponse(HttpStatusCode.NoContent);    }     public HttpResponseMessage Delete([FromODataUri] int id)    {        Artist artist = _db.Artists.Find(id);        if (artist == null)        {            return Request.CreateResponse(HttpStatusCode.NotFound);        }         _db.Artists.Remove(artist);         _db.SaveChanges();        return Request.CreateResponse(HttpStatusCode.Accepted);    }     protectedoverridevoid Dispose(bool disposing)    {        _db.Dispose();        base.Dispose(disposing);    }} 

 

 

测试这个服务

我将使用Fiddler去测试这个服务。

注意 Content-Type: application/json这个头。应该加一个新的类型。如果我们想要更新实体的一部分,如下图

现在这个类别为id=3将更新描述。

最后,我们进行一个文章实体排序操作如下图,http://localhost:2537/Artists?$orderby=Name&$inlinecount=allpages

正如你以上看到的,我们没有写任何一个特别的逻辑去支持这些功能,全部都由框架来提供的,当然如果你愿意,也可以自己写控制器不限于oData指定的CRUD操作。

oData毫无疑问是一个有趣的协议。我感觉它更像一个加强的REST服务。

本文的源代码在bitbucket

 

译后语:

原文地址:http://www.piotrwalat.net/getting-started-with-odata-services-in-asp-net-web-api/


评论

© 技术摘录 | Powered by LOFTER