5.5 ABP分布式服务 - ASPNET Core 集成OData

5.5.1 简介

开放数据协议(Open Data Protocol,缩写OData)是一种描述如何创建和访问Restful服务。你可以在Abp中使用OData,只需要通过Nuget来安装Abp.AspNetCore.OData.

5.5.2 安装

1. 使用Nuget安装

首先应该使用Nuget安装Abp.AspNetCore.OData到Web.Core项目:

  1. Install-Package Abp.AspNetCore.OData

2. 配置依赖模块

将AbpWebApiODataModule添加到被依赖的模块上,如下所示:

  1. [DependsOn(typeof(AbpAspNetCoreODataModule))]
  2. public class MyProjectWebCoreModule : AbpModule
  3. {
  4. ...
  5. }

了解模块依赖请参考模块系统

3. 配置实体

为了使实体能够作为一个OData源,我们应该在Startup类中对实体进行OData配置。如下所示:

  1. public class Startup
  2. {
  3. public IServiceProvider ConfigureServices(IServiceCollection services)
  4. {
  5. ...
  6. services.AddOData();
  7. // Workaround: https://github.com/OData/WebApi/issues/1177
  8. services.AddMvcCore(options =>
  9. {
  10. foreach (var outputFormatter in options.OutputFormatters.OfType<ODataOutputFormatter>().Where(_ => _.SupportedMediaTypes.Count == 0))
  11. {
  12. outputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/prs.odatatestxx-odata"));
  13. }
  14. foreach (var inputFormatter in options.InputFormatters.OfType<ODataInputFormatter>().Where(_ => _.SupportedMediaTypes.Count == 0))
  15. {
  16. inputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/prs.odatatestxx-odata"));
  17. }
  18. });
  19. return services.AddAbp<MyProjectWebHostModule>(...);
  20. }
  21. public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
  22. {
  23. app.UseAbp();
  24. ...
  25. app.UseOData(builder =>
  26. {
  27. builder.EntitySet<Person>("Persons").EntityType.Expand().Filter().OrderBy().Page();
  28. });
  29. // 从控制器中返回 IQueryable
  30. app.UseUnitOfWork(options =>
  31. {
  32. options.Filter = httpContext =>
  33. {
  34. return httpContext.Request.Path.Value.StartsWith("/odata");
  35. };
  36. });
  37. app.UseMvc(routes =>
  38. {
  39. routes.MapODataServiceRoute(app);
  40. ...
  41. });
  42. }
  43. }

在这里,我们得到了ODataModelBuilder的引用并且配置了Person实体。你可以使用 EntitySet 方法,以类似的方式添加其他实体。更多信息请参考OData文档

4. 创建控制器

Abp.AspNetCore.OData 中包含了基类:AbpODataEntityController(扩展自标准的ODataController),为了能够更容易的创建你自己的控制器,你应该继承该基类。如下所示:

  1. public class PersonsController : AbpODataEntityController<Person>, ITransientDependency
  2. {
  3. public PersonsController(IRepository<Person> repository)
  4. : base(repository)
  5. {
  6. }
  7. }

AbpODataEntityController 中的所有方法都是virtual,所以你可以重写 Get, Post, Put, Patch, Delete 和其它的Actions来实现你自己的逻辑。

6. 配置

Abp.AspNetCore.OData 使用约定的配置自动的调用IRouteBuilder.MapODataServiceRoute方法。如果你需要,你可以设置Configuration.Modules.AbpAspNetCoreOData().MapAction 来映射你自己的OData路由。

5.5.3 示例

这里有一些请求上面已定义的Controller的示例。假设你的应用的URL是:http://localhost:21021。下面将展示一些基础的例子。

1. 获取实体列表

取得所有的people。

Request
  1. GET http://localhost:21021/odata/Persons
Response
  1. {
  2. "@odata.context":"http://localhost:21021/odata/$metadata#Persons","value":[
  3. {
  4. "Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
  5. },{
  6. "Name":"John Nash","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
  7. }
  8. ]
  9. }

2. 获取单个实体

根据Id = 2来获取person

Request
  1. GET http://localhost:21021/odata/Persons(2)
Response
  1. {
  2. "@odata.context":"http://localhost:21021/odata/$metadata#Persons/$entity","Name":"John Nash","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
  3. }

3. 根据导航属性获取单个实体

根据Id = 1来获取person并且包括他的电话信息

Request
  1. GET http://localhost:21021/odata/Persons(1)?$expand=Phones
Response
  1. {
  2. "@odata.context":"http://localhost:21021/odata/$metadata#Persons/$entity","Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1,"Phones":[
  3. {
  4. "PersonId":1,"Type":"Mobile","Number":"4242424242","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
  5. },{
  6. "PersonId":1,"Type":"Mobile","Number":"2424242424","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
  7. }
  8. ]
  9. }

4. 查询

在这里我们将使用一个高级查询,在过滤,排序后取得排在最前面的2条数据。

Request
  1. GET http://localhost:21021/odata/Persons?$filter=Name eq 'Douglas Adams'&$orderby=CreationTime&$top=2
Response
  1. {
  2. "@odata.context":"http://localhost:21021/odata/$metadata#Persons","value":[
  3. {
  4. "Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
  5. }
  6. ]
  7. }

OData支持分页,排序,过滤,投影功能等等;详细请查看OData网站

5. 创建新实体

我们会创建一个新的person实体,示例如下:

Request
  1. POST http://localhost:21021/odata/Persons
  2. {
  3. Name: "Galileo Galilei"
  4. }

注意:”Content_Type” 头的值是 “application/json”

Response
  1. {
  2. "@odata.context": "http://localhost:21021/odata/$metadata#Persons/$entity",
  3. "Name": "Galileo Galilei",
  4. "IsDeleted": false,
  5. "DeleterUserId": null,
  6. "DeletionTime": null,
  7. "LastModificationTime": null,
  8. "LastModifierUserId": null,
  9. "CreationTime": "2016-01-12T20:36:04.1628263+02:00",
  10. "CreatorUserId": null,
  11. "Id": 4
  12. }

如果我们再次获取一次实体列表,我们会看到新增的person;我们也可以更新或者删除一个已经存在的实体,这正是OData协议所支持的。

6. 获取元数据

我们可以获取一个实体的元数据,如下所示:

Request
  1. GET http://localhost:21021/odata/$metadata
Response
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  3. <edmx:DataServices>
  4. <Schema Namespace="AbpODataDemo.People" xmlns="http://docs.oasis-open.org/odata/ns/edm">
  5. <EntityType Name="Person">
  6. <Key>
  7. <PropertyRef Name="Id" />
  8. </Key>
  9. <Property Name="Name" Type="Edm.String" Nullable="false" />
  10. <Property Name="IsDeleted" Type="Edm.Boolean" Nullable="false" />
  11. <Property Name="DeleterUserId" Type="Edm.Int64" />
  12. <Property Name="DeletionTime" Type="Edm.DateTimeOffset" />
  13. <Property Name="LastModificationTime" Type="Edm.DateTimeOffset" />
  14. <Property Name="LastModifierUserId" Type="Edm.Int64" />
  15. <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
  16. <Property Name="CreatorUserId" Type="Edm.Int64" />
  17. <Property Name="Id" Type="Edm.Int32" Nullable="false" />
  18. <NavigationProperty Name="Phones" Type="Collection(AbpODataDemo.People.Phone)" />
  19. </EntityType>
  20. <EntityType Name="Phone">
  21. <Key>
  22. <PropertyRef Name="Id" />
  23. </Key>
  24. <Property Name="PersonId" Type="Edm.Int32" />
  25. <Property Name="Type" Type="AbpODataDemo.People.PhoneType" Nullable="false" />
  26. <Property Name="Number" Type="Edm.String" Nullable="false" />
  27. <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
  28. <Property Name="CreatorUserId" Type="Edm.Int64" />
  29. <Property Name="Id" Type="Edm.Int32" Nullable="false" />
  30. <NavigationProperty Name="Person" Type="AbpODataDemo.People.Person">
  31. <ReferentialConstraint Property="PersonId" ReferencedProperty="Id" />
  32. </NavigationProperty>
  33. </EntityType>
  34. <EnumType Name="PhoneType">
  35. <Member Name="Unknown" Value="0" />
  36. <Member Name="Mobile" Value="1" />
  37. <Member Name="Home" Value="2" />
  38. <Member Name="Office" Value="3" />
  39. </EnumType>
  40. </Schema>
  41. <Schema Namespace="Default" xmlns="http://docs.oasis-open.org/odata/ns/edm">
  42. <EntityContainer Name="Container">
  43. <EntitySet Name="Persons" EntityType="AbpODataDemo.People.Person" />
  44. </EntityContainer>
  45. </Schema>
  46. </edmx:DataServices>
  47. </edmx:Edmx>

元数据被用来服务审查。

5.5.4 示例项目

你可以从这里获得示例项目的代码:: https://github.com/aspnetboilerplate/sample-odata