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项目:

Install-Package Abp.AspNetCore.OData

2. 配置依赖模块

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

[DependsOn(typeof(AbpAspNetCoreODataModule))]
public class MyProjectWebCoreModule : AbpModule
{
    ...
}

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

3. 配置实体

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

public class Startup
{
    public IServiceProvider ConfigureServices(IServiceCollection services)
    {
        ...

        services.AddOData();

        // Workaround: https://github.com/OData/WebApi/issues/1177
        services.AddMvcCore(options =>
        {
            foreach (var outputFormatter in options.OutputFormatters.OfType<ODataOutputFormatter>().Where(_ => _.SupportedMediaTypes.Count == 0))
            {
                outputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/prs.odatatestxx-odata"));
            }
            foreach (var inputFormatter in options.InputFormatters.OfType<ODataInputFormatter>().Where(_ => _.SupportedMediaTypes.Count == 0))
            {
                inputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/prs.odatatestxx-odata"));
            }
        });

        return services.AddAbp<MyProjectWebHostModule>(...);
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        app.UseAbp();

        ...

        app.UseOData(builder =>
        {
            builder.EntitySet<Person>("Persons").EntityType.Expand().Filter().OrderBy().Page();
        });

        // 从控制器中返回 IQueryable
        app.UseUnitOfWork(options =>
        {
            options.Filter = httpContext =>
            {
                return httpContext.Request.Path.Value.StartsWith("/odata");
            };
        });

        app.UseMvc(routes =>
        {
            routes.MapODataServiceRoute(app);

            ...
        });
    }
}

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

4. 创建控制器

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

public class PersonsController : AbpODataEntityController<Person>, ITransientDependency 
{
    public PersonsController(IRepository<Person> repository)
        : base(repository)
    {
    }
}

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
 GET  http://localhost:21021/odata/Persons
Response
{
  "@odata.context":"http://localhost:21021/odata/$metadata#Persons","value":[
    {
      "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
    },{
      "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
    }
  ]
}

2. 获取单个实体

根据Id = 2来获取person

Request
GET http://localhost:21021/odata/Persons(2)
Response
{
  "@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. 根据导航属性获取单个实体

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

Request
GET http://localhost:21021/odata/Persons(1)?$expand=Phones
Response
{
  "@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":[
    {
      "PersonId":1,"Type":"Mobile","Number":"4242424242","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
    },{
      "PersonId":1,"Type":"Mobile","Number":"2424242424","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
    }
  ]
}

4. 查询

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

Request
GET http://localhost:21021/odata/Persons?$filter=Name eq 'Douglas Adams'&$orderby=CreationTime&$top=2
Response
{
  "@odata.context":"http://localhost:21021/odata/$metadata#Persons","value":[
    {
      "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
    }
  ]
}

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

5. 创建新实体

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

Request
POST http://localhost:21021/odata/Persons

{
    Name: "Galileo Galilei"
}

注意:"Content_Type" 头的值是 "application/json"

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

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

6. 获取元数据

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

Request
GET http://localhost:21021/odata/$metadata
Response
<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:DataServices>
        <Schema Namespace="AbpODataDemo.People" xmlns="http://docs.oasis-open.org/odata/ns/edm">

            <EntityType Name="Person">
                <Key>
                    <PropertyRef Name="Id" />
                </Key>
                <Property Name="Name" Type="Edm.String" Nullable="false" />
                <Property Name="IsDeleted" Type="Edm.Boolean" Nullable="false" />
                <Property Name="DeleterUserId" Type="Edm.Int64" />
                <Property Name="DeletionTime" Type="Edm.DateTimeOffset" />
                <Property Name="LastModificationTime" Type="Edm.DateTimeOffset" />
                <Property Name="LastModifierUserId" Type="Edm.Int64" />
                <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="CreatorUserId" Type="Edm.Int64" />
                <Property Name="Id" Type="Edm.Int32" Nullable="false" />
                <NavigationProperty Name="Phones" Type="Collection(AbpODataDemo.People.Phone)" />
            </EntityType>

            <EntityType Name="Phone">
                <Key>
                    <PropertyRef Name="Id" />
                </Key>
                <Property Name="PersonId" Type="Edm.Int32" />
                <Property Name="Type" Type="AbpODataDemo.People.PhoneType" Nullable="false" />
                <Property Name="Number" Type="Edm.String" Nullable="false" />
                <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="CreatorUserId" Type="Edm.Int64" />
                <Property Name="Id" Type="Edm.Int32" Nullable="false" />
                <NavigationProperty Name="Person" Type="AbpODataDemo.People.Person">
                    <ReferentialConstraint Property="PersonId" ReferencedProperty="Id" />
                </NavigationProperty>
            </EntityType>

            <EnumType Name="PhoneType">
                <Member Name="Unknown" Value="0" />
                <Member Name="Mobile" Value="1" />
                <Member Name="Home" Value="2" />
                <Member Name="Office" Value="3" />
            </EnumType>

        </Schema>
        <Schema Namespace="Default" xmlns="http://docs.oasis-open.org/odata/ns/edm">

            <EntityContainer Name="Container">
                <EntitySet Name="Persons" EntityType="AbpODataDemo.People.Person" />
            </EntityContainer>

        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

元数据被用来服务审查。

5.5.4 示例项目

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