包安装

要在应用中启用 JSON Patch 支持，请完成以下步骤：

安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet 包。
更新项目的 Startup.ConfigureServices 方法以调用 AddNewtonsoftJson。例如：
C#复制
services .AddControllersWithViews() .AddNewtonsoftJson();

AddNewtonsoftJson 与 MVC 服务注册方法兼容：

AddRazorPages
AddControllersWithViews
AddControllers

JSON Patch、AddNewtonsoftJson 和 System.Text.Json

AddNewtonsoftJson 替换了用于格式化所有 JSON 内容的基于 System.Text.Json 的输入和输出格式化程序。要使用 Newtonsoft.Json 添加对 JSON Patch 的支持，同时使其他格式化程序保持不变，请按如下所示更新项目的 Startup.ConfigureServices 方法：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews(options =>
    {
        options.InputFormatters.Insert(0, GetJsonPatchInputFormatter());
    });
}

private static NewtonsoftJsonPatchInputFormatter GetJsonPatchInputFormatter()
{
    var builder = new ServiceCollection()
        .AddLogging()
        .AddMvc()
        .AddNewtonsoftJson()
        .Services.BuildServiceProvider();

    return builder
        .GetRequiredService<IOptions<MvcOptions>>()
        .Value
        .InputFormatters
        .OfType<NewtonsoftJsonPatchInputFormatter>()
        .First();
}

上述代码需要 Microsoft.AspNetCore.Mvc.NewtonsoftJson 包和以下 using 语句：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using System.Linq;

使用 Newtonsoft.Json.JsonConvert.SerializeObject 方法可序列化 JsonPatchDocument。

PATCH HTTP 请求方法

PUT 和 PATCH 方法用于更新现有资源。它们之间的区别是，PUT 会替换整个资源，而PATCH 仅指定更改。

JSON 修补程序

JSON 修补程序是一种格式，用于指定要应用于资源的更新。 JSON 修补程序文档有一个操作数组。每个操作都标识一种特定类型的更改。此类更改的示例包括添加数组元素或替换属性值。

例如，以下 JSON 文档表示资源、资源的 JSON Patch 文档和应用 Patch 操作的结果。

资源示例

JSON

{
  "customerName": "John",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    }
  ]
}

JSON 修补程序示例

JSON

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

在上述 JSON 中：

op 属性指示操作的类型。
path 属性指示要更新的元素。
value 属性提供新值。

修补程序之后的资源

下面是应用上述 JSON 修补程序文档后的资源：

JSON

{
  "customerName": "Barry",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    },
    {
      "orderName": "Order2",
      "orderType": null
    }
  ]
}

通过将 JSON Patch 文档应用于资源所做的更改是原子操作。如果列表中的任何操作失败，则不会应用列表中的任何操作。

路径语法

操作对象的路径属性的级别之间有斜杠。例如，"/address/zipCode"。

使用从零开始的索引来指定数组元素。 addresses 数组的第一个元素将位于 /addresses/0。若要将 add 置于数组末尾，请使用连字符 (-)，而不是索引号：/addresses/-。

ASP.NET Core 中的 JSON Patch

Microsoft.AspNetCore.JsonPatch NuGet 包中提供了 JSON 修补程序的 ASP.NET Core 实现。

操作方法代码

在 API 控制器中，JSON 修补程序的操作方法：

使用 HttpPatch 属性进行批注。
接受 JsonPatchDocument<T>，通常带有 [FromBody]。
在修补程序文档上调用 ApplyTo 以应用更改。

下面是一个示例：

[HttpPatch]
public IActionResult JsonPatchWithModelState(
    [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    if (patchDoc != null)
    {
        var customer = CreateCustomer();

        patchDoc.ApplyTo(customer, ModelState);

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        return new ObjectResult(customer);
    }
    else
    {
        return BadRequest(ModelState);
    }
}

示例应用中的此代码适用于以下 Customer 模型：

public class Customer
{
    public string CustomerName { get; set; }
    public List<Order> Orders { get; set; }
}

C#复制

public class Order
{
    public string OrderName { get; set; }
    public string OrderType { get; set; }
}

示例操作方法：

构造一个 Customer。
应用修补程序。
在响应的正文中返回结果。

在实际应用中，该代码将从存储（如数据库）中检索数据并在应用修补程序后更新数据库。

模型状态

上述操作方法示例调用将模型状态用作其参数之一的 ApplyTo 的重载。使用此选项，可以在响应中收到错误消息。以下示例显示了 test 操作的“400 错误请求”响应的正文：

JSON

{
    "Customer": [
        "The current value 'John' at path 'customerName' is not equal to the test value 'Nancy'."
    ]
}

动态对象

以下操作方法示例演示如何将修补程序应用于动态对象：

[HttpPatch]
public IActionResult JsonPatchForDynamic([FromBody]JsonPatchDocument patch)
{
    dynamic obj = new ExpandoObject();
    patch.ApplyTo(obj);

    return Ok(obj);
}

添加操作

如果 path 指向数组元素：将新元素插入到 path 指定的元素之前。
如果 path 指向属性：设置属性值。
如果 path 指向不存在的位置：如果要修补的资源是一个动态对象：添加属性。如果要修补的资源是一个静态对象：请求失败。

以下示例修补程序文档设置 CustomerName 的值，并将 Order 对象添加到 Orders 数组末尾。

JSON

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

删除操作

如果 path 指向数组元素：删除元素。
如果 path 指向属性：如果要修补的资源是一个动态对象：删除属性。如果要修补的资源是一个静态对象：如果属性可以为 Null：将其设置为 null。如果属性不可以为 Null，将其设置为 default<T>。

以下示例修补程序文档将 CustomerName 设置为 null 并删除 Orders[0]：

JSON

[
  {
    "op": "remove",
    "path": "/customerName"
  },
  {
    "op": "remove",
    "path": "/orders/0"
  }
]

替换操作

此操作在功能上与后跟 add 的 remove 相同。

以下示例修补程序文档设置 CustomerName 的值，并将 Orders[0] 替换为新的 Order 对象：

JSON

[
  {
    "op": "replace",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "replace",
    "path": "/orders/0",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

移动操作

如果 path 指向数组元素：将 from 元素复制到 path 元素的位置，然后对 from 元素运行 remove 操作。
如果 path 指向属性：将 from 属性的值复制到 path 属性，然后对 from 属性运行 remove 操作。
如果 path 指向不存在的属性：如果要修补的资源是一个静态对象：请求失败。如果要修补的资源是一个动态对象：将 from 属性复制到 path 指示的位置，然后对 from 属性运行 remove 操作。

以下示例修补程序文档：

将 Orders[0].OrderName 的值复制到 CustomerName。
将 Orders[0].OrderName 设置为 null。
将 Orders[1] 移动到 Orders[0] 之前。

JSON

[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

复制操作

此操作在功能上与不包含最后 remove 步骤的 move 操作相同。

以下示例修补程序文档：

将 Orders[0].OrderName 的值复制到 CustomerName。
将 Orders[1] 的副本插入到 Orders[0] 之前。

JSON

[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

测试操作

如果 path 指示的位置处的值与 value 中提供的值不同，则请求会失败。在这种情况下，整个 PATCH 请求会失败，即使修补程序文档中的所有其他操作均成功也是如此。

test 操作通常用于在发生并发冲突时阻止更新。

如果 CustomerName 的初始值是“John”，则以下示例修补程序文档不起任何作用，因为测试失败：

JSON

[
  {
    "op": "test",
    "path": "/customerName",
    "value": "Nancy"
  },
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  }
]

里克资源网

ASP.NET Core Web API 中的 JSON 修补程序

包安装

JSON Patch、AddNewtonsoftJson 和 System.Text.Json

PATCH HTTP 请求方法

JSON 修补程序

资源示例

JSON 修补程序示例

修补程序之后的资源

路径语法

ASP.NET Core 中的 JSON Patch

操作方法代码

模型状态

动态对象

添加操作

删除操作

替换操作

移动操作

复制操作

测试操作