JSON Patch nell'API Web ASP.NET Core

Questo articolo illustra come gestire JSle richieste on patch in un'API Web di ASP.NET Core.

Installazione del pacchetto

JSIl supporto delle patch ON nell'API Web di ASP.NET Core è basato su Newtonsoft.Json e richiede il Microsoft.AspNetCore.Mvc.NewtonsoftJson pacchetto NuGet. Per abilitare il JSsupporto di ON Patch:

• 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 ilJScontenuto ON. Questo metodo di estensione è compatibile con i metodi di registrazione del servizio MVC seguenti:

• AddRazorPages
• AddControllersWithViews
• AddControllers

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

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

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

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

• Aggiornare Program.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 JSle richieste ON Patch.
• System.Text.JsonL'input e i formattatori esistenti elaborano tutte le altre JSrichieste e risposte ON.

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.

JSON Patch

JSON Patch è un formato per specificare gli aggiornamenti da applicare a una risorsa. Un JSdocumento ON Patch include 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 ON seguenti JSrappresentano una risorsa, un JSdocumento ON 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
    }
  ]
}

JSEsempio di patch ON

[
  {
    "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 ON Patch precedente JS:

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

Le modifiche apportate applicando un JSdocumento ON Patch 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/-.

Gestione operativa

La tabella seguente illustra le operazioni supportate come definito nella JSspecifica ON 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 è disponibile 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<TModel>, in genere con [FromBody].
• Chiama ApplyTo(Object) 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 :

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 JSdocumenti patch ON dalla cartella del JSprogetto ON .

Risorse aggiuntive

• Specifica del metodo PATCH IETF RFC 5789
• Specifica patch IETF RFC 6902 JSON
• Puntatore IETF RFC 6901 JSON
• JSON Documentazione di Patch. Include collegamenti alle risorse per la creazione di JSdocumenti ON Patch.
• codice sorgente di ASP.NET Core JSON Patch