Skip to content

Commit 45e4920

Browse files
MackinnonBuckcaptainsafia
authored andcommitted
Provide Microsoft.AspNetCore.JsonPatch package README (#57792)
1 parent 901774f commit 45e4920

File tree

1 file changed

+100
-0
lines changed

1 file changed

+100
-0
lines changed

src/Features/JsonPatch/src/PACKAGE.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
## About
2+
3+
`Microsoft.AspNetCore.JsonPatch` provides ASP.NET Core support for JSON PATCH requests.
4+
5+
## How to Use
6+
7+
To use `Microsoft.AspNetCore.JsonPatch`, follow these steps:
8+
9+
### Installation
10+
11+
```shell
12+
dotnet add package Microsoft.AspNetCore.JsonPatch
13+
dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson
14+
```
15+
16+
### Configuration
17+
18+
To enable JSON Patch support, call `AddNewtonsoftJson` in your ASP.NET Core app's `Program.cs`:
19+
```csharp
20+
var builder = WebApplication.CreateBuilder(args);
21+
22+
builder.Services.AddControllers()
23+
.AddNewtonsoftJson();
24+
```
25+
26+
#### Configure when using `System.Text.Json`
27+
28+
To add support for JSON Patch using `Newtonsoft.Json` while continuing to use `System.Text.Json` for other input and output formatters:
29+
30+
1. Update your `Program.cs` with logic to construct a `NewtonsoftJsonPatchInputFormatter`:
31+
```csharp
32+
static NewtonsoftJsonPatchInputFormatter GetJsonPatchInputFormatter()
33+
{
34+
var builder = new ServiceCollection()
35+
.AddLogging()
36+
.AddMvc()
37+
.AddNewtonsoftJson()
38+
.Services.BuildServiceProvider();
39+
40+
return builder
41+
.GetRequiredService<IOptions<MvcOptions>>()
42+
.Value
43+
.InputFormatters
44+
.OfType<NewtonsoftJsonPatchInputFormatter>()
45+
.First();
46+
}
47+
```
48+
2. Configure the input formatter:
49+
```csharp
50+
var builder = WebApplication.CreateBuilder(args);
51+
52+
builder.Services.AddControllers(options =>
53+
{
54+
options.InputFormatters.Insert(0, GetJsonPatchInputFormatter());
55+
});
56+
```
57+
58+
### Usage
59+
60+
To define an action method for a JSON Patch in an API controller:
61+
1. Annotate it with the `HttpPatch` attribute
62+
2. Accept a `JsonPatchDocument<TModel>`
63+
3. Call `ApplyTo` on the patch document to apply changes
64+
65+
For example:
66+
67+
```csharp
68+
[HttpPatch]
69+
public IActionResult JsonPatchWithModelState(
70+
[FromBody] JsonPatchDocument<Customer> patchDoc)
71+
{
72+
if (patchDoc is not null)
73+
{
74+
var customer = CreateCustomer();
75+
76+
patchDoc.ApplyTo(customer, ModelState);
77+
78+
if (!ModelState.IsValid)
79+
{
80+
return BadRequest(ModelState);
81+
}
82+
83+
return new ObjectResult(customer);
84+
}
85+
else
86+
{
87+
return BadRequest(ModelState);
88+
}
89+
}
90+
```
91+
92+
In a real app, the code would retrieve the data from a store such as a database and update the database after applying the patch.
93+
94+
## Additional Documentation
95+
96+
For additional documentation and examples, refer to the [official documentation](https://learn.microsoft.com/aspnet/core/web-api/jsonpatch) on JSON Patch in ASP.NET Core.
97+
98+
## Feedback &amp; Contributing
99+
100+
`Microsoft.AspNetCore.JsonPatch` is released as open-source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/aspnetcore).

0 commit comments

Comments
 (0)