使用 ASP.NET Web API 在 OData v4 中打开类型

项目
06/16/2023

在 OData v4 中，除了在类型定义中声明的任何属性外， 开放类型 是包含动态属性的结构化类型。开放类型使你可以为数据模型增加灵活性。本教程演示如何在 ASP.NET Web API OData 中使用开放类型。

本教程假定你已知道如何在 ASP.NET Web API 中创建 OData 终结点。如果没有，请先阅读创建 OData v4 终结点。

本教程中使用的软件版本

Web API OData 5.3

OData v4

首先，一些 OData 术语：

实体类型：具有键的结构化类型。
复杂类型：不带键的结构化类型。
打开类型：具有动态属性的类型。可以打开实体类型和复杂类型。

动态属性的值可以是基元类型、复杂类型或枚举类型;或任何这些类型的集合。有关开放类型的详细信息，请参阅 OData v4 规范。

安装 Web OData 库

使用 NuGet 包管理器安装最新的 Web API OData 库。从“程序包管理器控制台”窗口：

Install-Package Microsoft.AspNet.OData
Install-Package Microsoft.AspNet.WebApi.OData

定义 CLR 类型

首先将 EDM 模型定义为 CLR 类型。

public enum Category
{
    Book,
    Magazine,
    EBook
}

public class Address
{
    public string City { get; set; }
    public string Street { get; set; }
}

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Address Address { get; set; }
}

public class Press
{
    public string Name { get; set; }
    public string Email { get; set; }
    public Category Category { get; set; }
    public IDictionary<string, object> DynamicProperties { get; set; }
}

public class Book
{
    [Key]
    public string ISBN { get; set; }
    public string Title { get; set; }
    public Press Press { get; set; }
    public IDictionary<string, object> Properties { get; set; }
}

创建实体数据模型 (EDM) 时，

Category 是枚举类型。
Address 是复杂类型。 (它没有键，因此它不是实体类型。)
Customer 是实体类型。 (它有一个密钥。)
Press 是一个开放复杂类型。
Book 是打开的实体类型。

若要创建开放类型，CLR 类型必须具有类型 IDictionary<string, object>为的属性，该属性保存动态属性。

生成 EDM 模型

如果使用 ODataConventionModelBuilder 创建 EDM， Press 并且 Book 会根据属性的存在 IDictionary<string, object> 自动添加为打开类型。

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
        builder.EntitySet<Book>("Books");
        builder.EntitySet<Customer>("Customers");
        var model = builder.GetEdmModel();

        config.MapODataServiceRoute(
            routeName: "ODataRoute",
            routePrefix: null,
            model: model);

    }
}

还可以使用 ODataModelBuilder 显式生成 EDM。

ODataModelBuilder builder = new ODataModelBuilder();

ComplexTypeConfiguration<Press> pressType = builder.ComplexType<Press>();
pressType.Property(c => c.Name);
// ...
pressType.HasDynamicProperties(c => c.DynamicProperties);

EntityTypeConfiguration<Book> bookType = builder.EntityType<Book>();
bookType.HasKey(c => c.ISBN);
bookType.Property(c => c.Title);
// ...
bookType.ComplexProperty(c => c.Press);
bookType.HasDynamicProperties(c => c.Properties);

// ...
builder.EntitySet<Book>("Books");
IEdmModel model = builder.GetEdmModel();

添加 OData 控制器

接下来，添加 OData 控制器。在本教程中，我们将使用仅支持 GET 和 POST 请求的简化控制器，并使用内存中列表来存储实体。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
using System.Web.OData;

namespace MyApp.Controllers
{
    public class BooksController : ODataController
    {
        private IList<Book> _books = new List<Book>
        {
            new Book
            {
                ISBN = "978-0-7356-8383-9",
                Title = "SignalR Programming in Microsoft ASP.NET",
                Press = new Press
                {
                    Name = "Microsoft Press",
                    Category = Category.Book
                }
            },

            new Book
            {
                ISBN = "978-0-7356-7942-9",
                Title = "Microsoft Azure SQL Database Step by Step",
                Press = new Press
                {
                    Name = "Microsoft Press",
                    Category = Category.EBook,
                    DynamicProperties = new Dictionary<string, object>
                    {
                        { "Blog", "https://blogs.msdn.com/b/microsoft_press/" },
                        { "Address", new Address { 
                              City = "Redmond", Street = "One Microsoft Way" }
                        }
                    }
                },
                Properties = new Dictionary<string, object>
                {
                    { "Published", new DateTimeOffset(2014, 7, 3, 0, 0, 0, 0, new TimeSpan(0))},
                    { "Authors", new [] { "Leonard G. Lobel", "Eric D. Boyd" }},
                    { "OtherCategories", new [] {Category.Book, Category.Magazine}}
                }
            }
        };

        [EnableQuery]
        public IQueryable<Book> Get()
        {
            return _books.AsQueryable();
        }

        public IHttpActionResult Get([FromODataUri]string key)
        {
            Book book = _books.FirstOrDefault(e => e.ISBN == key);
            if (book == null)
            {
                return NotFound();
            }

            return Ok(book);
        }

        public IHttpActionResult Post(Book book)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            } 
            // For this sample, we aren't enforcing unique keys.
            _books.Add(book);
            return Created(book);
        }
    }
}

请注意，第一个 Book 实例没有动态属性。第二 Book 个实例具有以下动态属性：

“已发布”：基元类型
“Authors”：基元类型的集合
“OtherCategories”：枚举类型的集合。

此外， Press 该 Book 实例的属性具有以下动态属性：

“Blog”：基元类型
“Address”：复杂类型

查询元数据

若要获取 OData 元数据文档，请向 ~/$metadata发送 GET 请求。响应正文应如下所示：

<?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="MyApp.Models" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityType Name="Book" OpenType="true">
        <Key>
          <PropertyRef Name="ISBN" />
        </Key>
        <Property Name="ISBN" Type="Edm.String" Nullable="false" />
        <Property Name="Title" Type="Edm.String" />
        <Property Name="Press" Type="MyApp.Models.Press" />
      </EntityType>
      <EntityType Name="Customer">
        <Key>
          <PropertyRef Name="Id" />
        </Key>
        <Property Name="Id" Type="Edm.Int32" Nullable="false" />
        <Property Name="Name" Type="Edm.String" />
        <Property Name="Address" Type="MyApp.Models.Address" />
      </EntityType>
      <ComplexType Name="Press" OpenType="true">
        <Property Name="Name" Type="Edm.String" />
        <Property Name="Category" Type="MyApp.Models.Category" Nullable="false" />
      </ComplexType>
      <ComplexType Name="Address">
        <Property Name="City" Type="Edm.String" />
        <Property Name="Street" Type="Edm.String" />
      </ComplexType>
      <EnumType Name="Category">
        <Member Name="Book" Value="0" />
        <Member Name="Magazine" Value="1" />
        <Member Name="EBook" Value="2" />
      </EnumType>
    </Schema>
    <Schema Namespace="Default" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityContainer Name="Container">
        <EntitySet Name="Books" EntityType="MyApp.Models.Book" />
        <EntitySet Name="Customers" EntityType="MyApp.Models.Customer" />
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

在元数据文档中，可以看到：

Book对于和 Press 类型，属性的OpenType值为 true。 Customer和 Address 类型没有此属性。
实体 Book 类型具有三个声明的属性：ISBN、Title 和 Press。 OData 元数据不包括 Book.Properties CLR 类中的属性。
同样， Press 复杂类型只有两个声明的属性：Name 和 Category。元数据不包括 Press.DynamicProperties CLR 类中的属性。

查询实体

若要获取 ISBN 等于“978-0-7356-7942-9”的书籍，请向 ~/Books('978-0-7356-7942-9')发送 GET 请求。响应正文应如下所示。 (缩进使其更易于阅读。)

{
  "@odata.context":"http://localhost:37141/$metadata#Books/$entity",
    "ISBN":"978-0-7356-7942-9",
    "Title":"Microsoft Azure SQL Database Step by Step",
    "Press":{
      "Name":"Microsoft Press",
      "Category":"EBook",
      "Blog":"https://blogs.msdn.com/b/microsoft_press/",
      "Address":{
        "@odata.type":"#MyApp.Models.Address",
        "City":"Redmond",
        "Street":"One Microsoft Way"
      }
  },
  "Published":"2014-07-03T00:00:00Z",
  "Authors@odata.type":"#Collection(String)",
  "Authors":[
    "Leonard G. Lobel","Eric D. Boyd"
  ],
  "OtherCategories@odata.type":"#Collection(MyApp.Models.Category)",
  "OtherCategories":[
    "Book","Magazine"
  ]
}

请注意，动态属性与声明的属性一起内联。

POST 实体

若要添加 Book 实体，请向 ~/Books发送 POST 请求。客户端可以在请求有效负载中设置动态属性。

下面是一个示例请求。请注意“Price”和“Published”属性。

POST http://localhost:37141/Books HTTP/1.1
User-Agent: Fiddler
Host: localhost:37141
Content-Type: application/json
Content-Length: 191

{
  "ISBN":"978-0-7356-8383-9","Title":"Programming Microsoft ASP.NET MVC","Press":{
  "Name":"Microsoft Press","Category":"Book"
   }, "Price": 49.99, "Published":"2014-02-15T00:00:00Z"
}

如果在控制器方法中设置断点，可以看到 Web API 将这些属性添加到了字典中 Properties 。

发送 POST 请求的代码的屏幕截图，其中突出显示了代码的“添加书籍”部分，以显示由 Web A P I 添加的属性。

其他资源

OData 开放类型示例

使用 ASP.NET Web API 在 OData v4 中打开类型

本教程中使用的软件版本

安装 Web OData 库

定义 CLR 类型

生成 EDM 模型

添加 OData 控制器

查询元数据

查询实体

POST 实体

其他资源

反馈

反馈

其他资源