JSON Patch nell'API Web ASP.NET Core

  • Articolo

Questo articolo descrive come gestire le richieste JSON Patch in un'API Web ASP.NET Core.

Installazione del pacchetto

Il supporto delle patch JSON nell'API Web di ASP.NET Core si basa su Newtonsoft.Json e richiede il Microsoft.AspNetCore.Mvc.NewtonsoftJson pacchetto NuGet. Per abilitare il supporto di patch JSON:

  • Installare il pacchetto NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson.

  • Chiamare AddNewtonsoftJson. Ad esempio:

    var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddNewtonsoftJson();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

AddNewtonsoftJson sostituisce i formattatori di input e output predefiniti System.Text.Jsonusati per la formattazione di tutto il contenuto JSON. Questo metodo di estensione è compatibile con i metodi di registrazione del servizio MVC seguenti:

JsonPatch richiede l'impostazione dell'intestazione Content-Type su application/json-patch+json.

Aggiunta del supporto per patch JSON quando si usa System.Text.Json

Il System.Text.Jsonformattatore di input basato su non supporta la patch JSON. Per aggiungere il supporto per patch JSON usando Newtonsoft.Json, lasciando invariati gli altri formattatori di input e output:

  • Installare il pacchetto NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson.

  • AggiornamentoProgram.cs:

    using JsonPatchSample;
using Microsoft.AspNetCore.Mvc.Formatters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    options.InputFormatters.Insert(0, MyJPIF.GetJsonPatchInputFormatter());
});

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

    using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.Extensions.Options;

namespace JsonPatchSample;

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

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

Il codice precedente crea un'istanza di NewtonsoftJsonPatchInputFormatter e lo inserisce come prima voce nella MvcOptions.InputFormatters raccolta. Questo ordine di registrazione garantisce che:

  • NewtonsoftJsonPatchInputFormatter elabora le richieste patch JSON.
  • L'input e i formattatori esistenti System.Text.Jsonelaborano tutte le altre richieste e risposte JSON.

Utilizzare il Newtonsoft.Json.JsonConvert.SerializeObject metodo per serializzare un oggetto JsonPatchDocument.

Metodo di richiesta HTTP PATCH

I metodi PUT e PATCH vengono usati per aggiornare una risorsa esistente. La differenza tra i due metodi è che PUT sostituisce l'intera risorsa, mentre PATCH specifica solo le modifiche.

Patch JSON

JSON Patch è un formato per specificare gli aggiornamenti da applicare a una risorsa. Un documento JSON Patch è una matrice di operazioni. Ogni operazione identifica un particolare tipo di modifica. Esempi di tali modifiche includono l'aggiunta di un elemento matrice o la sostituzione di un valore della proprietà.

Ad esempio, i documenti JSON seguenti rappresentano una risorsa, un documento json patch per la risorsa e il risultato dell'applicazione delle operazioni patch.

Esempio di risorsa

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

Esempio di patch JSON

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

Nel codice JSON precedente:

  • La proprietà op indica il tipo di operazione.
  • La proprietà path indica l'elemento da aggiornare.
  • La proprietà value fornisce il nuovo valore.

Risorsa dopo la patch

Ecco la risorsa dopo aver applicato il documento JSON Patch precedente:

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

Le modifiche apportate applicando un documento patch JSON a una risorsa sono atomiche. Se un'operazione nell'elenco ha esito negativo, non viene applicata alcuna operazione nell'elenco.

Sintassi di path

La proprietà path di un oggetto operazione include barre tra livelli. Ad esempio: "/address/zipCode".

Vengono usati indici in base zero per specificare gli elementi della matrice. Il primo elemento della matrice addresses è in corrispondenza di /addresses/0. Per add terminare una matrice, usare un trattino (-) anziché un numero di indice: /addresses/-.

Operazioni

La tabella seguente mostra le operazioni supportate in base a quanto definito nella specifica JSON Patch:

Operazione Note
add Aggiunge una proprietà o un elemento della matrice. Per la proprietà esistente: impostare il valore.
remove Rimuove una proprietà o un elemento della matrice.
replace Uguale a remove seguita da add nella stessa posizione.
move Uguale a remove dall'origine seguita da add alla destinazione usando il valore dell'origine.
copy Uguale a add alla destinazione usando il valore dell'origine.
test Restituisce il codice di stato di richiesta riuscita se il valore in path = value fornito.

JSON Patch in ASP.NET Core

L'implementazione ASP.NET Core di JSON Patch viene fornita nel pacchetto NuGet Microsoft.AspNetCore.JsonPatch.

Codice del metodo di azione

In un controller API un metodo di azione per JSON Patch:

Ecco un esempio:

[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);
    }
}

Questo codice dell'app di esempio funziona con il modello seguente Customer :

namespace JsonPatchSample.Models;

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

namespace JsonPatchSample.Models;

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

Il metodo di azione di esempio:

  • Costruisce un oggetto Customer.
  • Applica la patch.
  • Restituisce il risultato nel corpo della risposta.

In un'app reale il codice recupererebbe i dati da un archivio, ad esempio un database, e aggiornerebbe il database dopo aver applicato la patch.

Stato del modello

L'esempio di metodo di azione precedente chiama un overload di ApplyTo che accetta lo stato del modello come uno dei propri parametri. Con questa opzione, è possibile ottenere messaggi di errore nelle risposte. L'esempio seguente mostra il corpo di una risposta 400 Richiesta non valida per un'operazione test:

{
  "Customer": [
    "The current value 'John' at path 'customerName' != test value 'Nancy'."
  ]
}

Oggetti dinamici

Nell'esempio di metodo di azione seguente viene illustrato come applicare una patch a un oggetto dinamico:

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

    return Ok(obj);
}

Operazione add

  • Se path punta a un elemento della matrice: inserisce un nuovo elemento prima di quello specificato da path.
  • Se path punta a una proprietà: imposta il valore della proprietà.
  • Se path punta a una posizione inesistente:
    • Se la risorsa cui applicare la patch è un oggetto dinamico: aggiunge una proprietà.
    • Se la risorsa cui applicare la patch è un oggetto statico: la richiesta non riesce.

Il documento di patch di esempio seguente imposta il valore di CustomerName e aggiunge un oggetto Order alla fine della matrice Orders.

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

Operazione remove

  • Se path punta a un elemento della matrice: rimuove l'elemento.
  • Se path punta a una proprietà:
    • Se la risorsa cui applicare la patch è un oggetto dinamico: rimuove la proprietà.
    • Se la risorsa per applicare patch è un oggetto statico:
      • Se la proprietà ammette valori Null: la imposta su Null.
      • Se la proprietà non ammette valori Null: la imposta su default<T>.

Il documento di patch di esempio seguente imposta CustomerName su null ed elimina Orders[0]:

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

Operazione replace

Questa operazione equivale a livello funzionale all'operazione remove seguita da un'operazione add.

Il documento di patch di esempio seguente imposta il valore di CustomerName e sostituisce Orders[0]con un nuovo Order oggetto:

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

Operazione move

  • Se path punta a un elemento della matrice: copia l'elemento from nella posizione dell'elemento path, quindi esegue un'operazione remove sull'elemento from.
  • Se path punta a una proprietà: copia il valore della proprietà from nella proprietà path, quindi esegue un'operazione remove sulla proprietà from.
  • Se path punta a una proprietà inesistente:
    • Se la risorsa cui applicare la patch è un oggetto statico: la richiesta non riesce.
    • Se la risorsa cui applicare la patch è un oggetto dinamico: copia la proprietà from nella posizione indicata da path, quindi esegue un'operazione remove sulla proprietà from.

Il documento di patch di esempio seguente:

  • Copia il valore di Orders[0].OrderName in CustomerName.
  • Imposta Orders[0].OrderName su Null.
  • Sposta Orders[1] prima di Orders[0].
[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operazione copy

Questa operazione equivale a livello funzionale all'operazione move senza il passaggio remove finale.

Il documento di patch di esempio seguente:

  • Copia il valore di Orders[0].OrderName in CustomerName.
  • Inserisce una copia di Orders[1] prima di Orders[0].
[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operazione test

Se il valore nella posizione indicata da path è diverso dal valore fornito in value, la richiesta non riesce. In questo caso, l'intera richiesta PATCH non riesce anche se tutte le altre operazioni nel documento di patch potrebbero riuscire.

L'operazione test viene usata in genere per impedire un aggiornamento in caso di conflitto di concorrenza.

Il documento di patch di esempio seguente non ha alcun effetto se il valore iniziale di CustomerName è "John", perché il test non riesce:

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

Ottenere il codice

Visualizzare o scaricare il codice di esempio. (Come scaricare un esempio).

Per testare l'esempio, eseguire l'app e inviare richieste HTTP con le impostazioni seguenti:

  • URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
  • Metodo HTTP: PATCH
  • Intestazione: Content-Type: application/json-patch+json
  • Corpo: copiare e incollare uno degli esempi di documenti patch JSON dalla cartella del progetto JSON .

Risorse aggiuntive

Questo articolo descrive come gestire le richieste JSON Patch in un'API Web ASP.NET Core.

Installazione del pacchetto

Per abilitare il supporto di patch JSON nell'app, completare la procedura seguente:

  1. Installare il pacchetto NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson.

  2. Aggiornare il metodo del Startup.ConfigureServices progetto per chiamare AddNewtonsoftJson. Ad esempio:

    services
    .AddControllersWithViews()
    .AddNewtonsoftJson();

AddNewtonsoftJson è compatibile con i metodi di registrazione del servizio MVC:

Patch JSON, AddNewtonsoftJson e System.Text.Json

AddNewtonsoftJson sostituisce i System.Text.Jsonformattatori di input e output basati su usati per la formattazione di tutto il contenuto JSON. Per aggiungere il supporto per patch JSON usando Newtonsoft.Json, lasciando invariati gli altri formattatori, aggiornare il metodo del Startup.ConfigureServices progetto come indicato di seguito:

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();
}

Il codice precedente richiede il Microsoft.AspNetCore.Mvc.NewtonsoftJson pacchetto e le istruzioni seguenti 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;

Usare il Newtonsoft.Json.JsonConvert.SerializeObject metodo per serializzare un jsonPatchDocument.

Metodo di richiesta HTTP PATCH

I metodi PUT e PATCH vengono usati per aggiornare una risorsa esistente. La differenza tra i due metodi è che PUT sostituisce l'intera risorsa, mentre PATCH specifica solo le modifiche.

Patch JSON

JSON Patch è un formato per specificare gli aggiornamenti da applicare a una risorsa. Un documento JSON Patch è una matrice di operazioni. Ogni operazione identifica un particolare tipo di modifica. Esempi di tali modifiche includono l'aggiunta di un elemento matrice o la sostituzione di un valore della proprietà.

Ad esempio, i documenti JSON seguenti rappresentano una risorsa, un documento json patch per la risorsa e il risultato dell'applicazione delle operazioni patch.

Esempio di risorsa

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

Esempio di patch JSON

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

Nel codice JSON precedente:

  • La proprietà op indica il tipo di operazione.
  • La proprietà path indica l'elemento da aggiornare.
  • La proprietà value fornisce il nuovo valore.

Risorsa dopo la patch

Ecco la risorsa dopo aver applicato il documento JSON Patch precedente:

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

Le modifiche apportate applicando un documento patch JSON a una risorsa sono atomiche. Se un'operazione nell'elenco ha esito negativo, non viene applicata alcuna operazione nell'elenco.

Sintassi di path

La proprietà path di un oggetto operazione include barre tra livelli. Ad esempio: "/address/zipCode".

Vengono usati indici in base zero per specificare gli elementi della matrice. Il primo elemento della matrice addresses è in corrispondenza di /addresses/0. Per add terminare una matrice, usare un trattino (-) anziché un numero di indice: /addresses/-.

Operazioni

La tabella seguente mostra le operazioni supportate in base a quanto definito nella specifica JSON Patch:

Operazione Note
add Aggiunge una proprietà o un elemento della matrice. Per la proprietà esistente: impostare il valore.
remove Rimuove una proprietà o un elemento della matrice.
replace Uguale a remove seguita da add nella stessa posizione.
move Uguale a remove dall'origine seguita da add alla destinazione usando il valore dell'origine.
copy Uguale a add alla destinazione usando il valore dell'origine.
test Restituisce il codice di stato di richiesta riuscita se il valore in path = value fornito.

JSON Patch in ASP.NET Core

L'implementazione ASP.NET Core di JSON Patch viene fornita nel pacchetto NuGet Microsoft.AspNetCore.JsonPatch.

Codice del metodo di azione

In un controller API un metodo di azione per JSON Patch:

  • Viene annotato con l'attributo HttpPatch.
  • Accetta un oggetto JsonPatchDocument<T>, in genere con [FromBody].
  • Chiama ApplyTo nel documento di patch per applicare le modifiche.

Ecco un esempio:

[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);
    }
}

Questo codice dell'app di esempio funziona con il modello seguente Customer :

using System.Collections.Generic;

namespace JsonPatchSample.Models
{
    public class Customer
    {
        public string CustomerName { get; set; }
        public List<Order> Orders { get; set; }
    }
}

namespace JsonPatchSample.Models
{
    public class Order
    {
        public string OrderName { get; set; }
        public string OrderType { get; set; }
    }
}

Il metodo di azione di esempio:

  • Costruisce un oggetto Customer.
  • Applica la patch.
  • Restituisce il risultato nel corpo della risposta.

In un'app reale il codice recupererebbe i dati da un archivio, ad esempio un database, e aggiornerebbe il database dopo aver applicato la patch.

Stato del modello

L'esempio di metodo di azione precedente chiama un overload di ApplyTo che accetta lo stato del modello come uno dei propri parametri. Con questa opzione, è possibile ottenere messaggi di errore nelle risposte. L'esempio seguente mostra il corpo di una risposta 400 Richiesta non valida per un'operazione test:

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

Oggetti dinamici

Nell'esempio di metodo di azione seguente viene illustrato come applicare una patch a un oggetto dinamico:

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

    return Ok(obj);
}

Operazione add

  • Se path punta a un elemento della matrice: inserisce un nuovo elemento prima di quello specificato da path.
  • Se path punta a una proprietà: imposta il valore della proprietà.
  • Se path punta a una posizione inesistente:
    • Se la risorsa cui applicare la patch è un oggetto dinamico: aggiunge una proprietà.
    • Se la risorsa cui applicare la patch è un oggetto statico: la richiesta non riesce.

Il documento di patch di esempio seguente imposta il valore di CustomerName e aggiunge un oggetto Order alla fine della matrice Orders.

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

Operazione remove

  • Se path punta a un elemento della matrice: rimuove l'elemento.
  • Se path punta a una proprietà:
    • Se la risorsa cui applicare la patch è un oggetto dinamico: rimuove la proprietà.
    • Se la risorsa per applicare patch è un oggetto statico:
      • Se la proprietà ammette valori Null: la imposta su Null.
      • Se la proprietà non ammette valori Null: la imposta su default<T>.

Il documento di patch di esempio seguente imposta CustomerName su null ed elimina Orders[0]:

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

Operazione replace

Questa operazione equivale a livello funzionale all'operazione remove seguita da un'operazione add.

Il documento di patch di esempio seguente imposta il valore di CustomerName e sostituisce Orders[0]con un nuovo Order oggetto:

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

Operazione move

  • Se path punta a un elemento della matrice: copia l'elemento from nella posizione dell'elemento path, quindi esegue un'operazione remove sull'elemento from.
  • Se path punta a una proprietà: copia il valore della proprietà from nella proprietà path, quindi esegue un'operazione remove sulla proprietà from.
  • Se path punta a una proprietà inesistente:
    • Se la risorsa cui applicare la patch è un oggetto statico: la richiesta non riesce.
    • Se la risorsa cui applicare la patch è un oggetto dinamico: copia la proprietà from nella posizione indicata da path, quindi esegue un'operazione remove sulla proprietà from.

Il documento di patch di esempio seguente:

  • Copia il valore di Orders[0].OrderName in CustomerName.
  • Imposta Orders[0].OrderName su Null.
  • Sposta Orders[1] prima di Orders[0].
[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operazione copy

Questa operazione equivale a livello funzionale all'operazione move senza il passaggio remove finale.

Il documento di patch di esempio seguente:

  • Copia il valore di Orders[0].OrderName in CustomerName.
  • Inserisce una copia di Orders[1] prima di Orders[0].
[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operazione test

Se il valore nella posizione indicata da path è diverso dal valore fornito in value, la richiesta non riesce. In questo caso, l'intera richiesta PATCH non riesce anche se tutte le altre operazioni nel documento di patch potrebbero riuscire.

L'operazione test viene usata in genere per impedire un aggiornamento in caso di conflitto di concorrenza.

Il documento di patch di esempio seguente non ha alcun effetto se il valore iniziale di CustomerName è "John", perché il test non riesce:

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

Ottenere il codice

Visualizzare o scaricare il codice di esempio. (Come scaricare un esempio).

Per testare l'esempio, eseguire l'app e inviare richieste HTTP con le impostazioni seguenti:

  • URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
  • Metodo HTTP: PATCH
  • Intestazione: Content-Type: application/json-patch+json
  • Corpo: copiare e incollare uno degli esempi di documenti patch JSON dalla cartella del progetto JSON .

Risorse aggiuntive