Supporto di patch JSON nell'API Web di ASP.NET Core

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

Il supporto delle patch JSON nell'API Web di ASP.NET Core si basa sulla System.Text.Json serializzazione e richiede il Microsoft.AspNetCore.JsonPatch.SystemTextJson pacchetto NuGet.

Che cos'è lo standard JSON Patch?

Lo standard JSON Patch:

• Formato standard per descrivere le modifiche da applicare a un documento JSON.

• È definito in RFC 6902 ed è ampiamente usato nelle API RESTful per eseguire aggiornamenti parziali alle risorse JSON.

• Descrive una sequenza di operazioni che modificano un documento JSON, ad esempio:

  • add
  • remove
  • replace
  • move
  • copy
  • test

Nelle app Web, patch JSON viene comunemente usata in un'operazione PATCH per eseguire aggiornamenti parziali di una risorsa. Anziché inviare l'intera risorsa per un aggiornamento, i client possono inviare un documento patch JSON contenente solo le modifiche. L'applicazione di patch riduce le dimensioni del payload e migliora l'efficienza.

Per una panoramica dello standard JSON Patch, vedere jsonpatch.com.

Supporto di patch JSON nell'API Web di ASP.NET Core

Il supporto per le JSON Patch nell'API Web di ASP.NET Core è basato sulla serializzazione System.Text.Json, e a partire da .NET 10, implementa Microsoft.AspNetCore.JsonPatch in base alla serializzazione System.Text.Json. Questa funzionalità offre i vantaggi seguenti:

• Richiede il Microsoft.AspNetCore.JsonPatch.SystemTextJson pacchetto NuGet.
• È in linea con le procedure .NET moderne sfruttando la System.Text.Json libreria, ottimizzata per .NET.
• Offre prestazioni migliorate e un utilizzo ridotto della memoria rispetto all'implementazione basata su legacy Newtonsoft.Json. Per altre informazioni sull'implementazione basata su legacy Newtonsoft.Json, vedere la versione .NET 9 di questo articolo.

Note

L'implementazione di Microsoft.AspNetCore.JsonPatch basata sulla serializzazione System.Text.Json non può sostituire l'implementazione basata su Newtonsoft.Json legacy. Non supporta i tipi dinamici, ad esempio ExpandoObject.

Important

Lo standard JSON Patch presenta rischi di sicurezza intrinseci. Poiché questi rischi sono intrinseci allo standard JSON Patch, l'implementazione di ASP.NET Core non tenta di attenuare i rischi di sicurezza intrinseci. È responsabilità dello sviluppatore assicurarsi che il documento JSON Patch sia sicuro da applicare all'oggetto di destinazione. Per altre informazioni, vedere la sezione Mitigazione dei rischi per la sicurezza .

Abilitare il supporto delle patch JSON con System.Text.Json

Per abilitare il supporto delle patch JSON con System.Text.Json, installare il Microsoft.AspNetCore.JsonPatch.SystemTextJson pacchetto NuGet.

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson --prerelease

Questo pacchetto fornisce una JsonPatchDocument<TModel> classe per rappresentare un documento JSON Patch per oggetti di tipo T e logica personalizzata per la serializzazione e la deserializzazione di documenti patch JSON tramite System.Text.Json. Il metodo chiave della JsonPatchDocument<TModel> classe è ApplyTo(Object), che applica le operazioni patch a un oggetto di destinazione di tipo T.

Codice del metodo di azione che applica patch JSON

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

• Viene annotato con l'attributo HttpPatchAttribute.
• Accetta un oggetto JsonPatchDocument<TModel>, in genere con FromBodyAttribute.
• Chiama ApplyTo(Object) nel documento di patch per applicare le modifiche.

Esempio di metodo di azione del controller:

[HttpPatch("{id}", Name = "UpdateCustomer")]
public IActionResult Update(AppDb db, string id, [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    // Retrieve the customer by ID
    var customer = db.Customers.FirstOrDefault(c => c.Id == id);

    // Return 404 Not Found if customer doesn't exist
    if (customer == null)
    {
        return NotFound();
    }

    patchDoc.ApplyTo(customer, jsonPatchError =>
        {
            var key = jsonPatchError.AffectedObject.GetType().Name;
            ModelState.AddModelError(key, jsonPatchError.ErrorMessage);
        }
    );

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

    return new ObjectResult(customer);
}

Questo codice dell'app di esempio funziona con i modelli Customer e Order seguenti:

namespace App.Models;

public class Customer
{
    public string Id { get; set; }
    public string? Name { get; set; }
    public string? Email { get; set; }
    public string? PhoneNumber { get; set; }
    public string? Address { get; set; }
    public List<Order>? Orders { get; set; }

    public Customer()
    {
        Id = Guid.NewGuid().ToString();
    }
}

namespace App.Models;

public class Order
{
    public string Id { get; set; }
    public DateTime? OrderDate { get; set; }
    public DateTime? ShipDate { get; set; }
    public decimal TotalAmount { get; set; }

    public Order()
    {
        Id = Guid.NewGuid().ToString();
    }
}

Passaggi chiave del metodo di azione di esempio:

• Recuperare il cliente:
  • Il metodo recupera un Customer oggetto dal database AppDb utilizzando l'ID specificato.
  • Se non viene trovato alcun Customer oggetto, restituisce una 404 Not Found risposta.
• Applica patch JSON:
  • Il metodo ApplyTo(Object) applica le operazioni di JSON Patch dal documento di patch al Customer oggetto recuperato.
  • Se si verificano errori durante l'applicazione patch, ad esempio operazioni o conflitti non validi, vengono acquisiti da un delegato di gestione degli errori. Questo delegato aggiunge messaggi di errore all'oggetto ModelState utilizzando il nome del tipo dell'oggetto interessato e il messaggio di errore.
• Validate ModelState:
  • Dopo aver applicato la patch, il metodo controlla ModelState per errori.
  • Se l'oggetto ModelState non è valido, ad esempio a causa di errori di patch, restituisce una 400 Bad Request risposta con gli errori di convalida.
• Restituire il cliente aggiornato:
  • Se la patch viene applicata correttamente e l'oggetto ModelState è valido, il metodo restituisce l'oggetto aggiornato Customer nella risposta.

Risposta di errore di esempio:

L'esempio seguente mostra il corpo di una risposta 400 Bad Request per un'operazione JSON Patch quando il percorso specificato non è valido.

{
  "Customer": [
    "The target location specified by path segment 'foobar' was not found."
  ]
}

Applicare un documento Patch JSON a un oggetto

Gli esempi seguenti illustrano come usare il ApplyTo(Object) metodo per applicare un documento Patch JSON a un oggetto .

Esempio: Applicare un JsonPatchDocument<TModel> a un oggetto

L'esempio seguente illustra:

• Operazioni add, replacee remove .
• Operazioni sulle proprietà annidate.
• Aggiunta di un nuovo elemento a una matrice.
• Uso di un convertitore di enumerazioni di stringhe JSON in un documento di patch JSON.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com",
    PhoneNumbers = [new() {Number = "123-456-7890", Type = PhoneNumberType.Mobile}],
    Address = new Address
    {
        Street = "123 Main St",
        City = "Anytown",
        State = "TX"
    }
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/FirstName", "value": "Jane" },
    { "op": "remove", "path": "/Email"},
    { "op": "add", "path": "/Address/ZipCode", "value": "90210" },
    { "op": "add", "path": "/PhoneNumbers/-", "value": { "Number": "987-654-3210",
                                                                "Type": "Work" } }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document
patchDoc!.ApplyTo(person);

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

L'esempio precedente restituisce l'output seguente dell'oggetto aggiornato:

{
    "firstName": "Jane",
    "lastName": "Doe",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "TX",
        "zipCode": "90210"
    },
    "phoneNumbers": [
        {
            "number": "123-456-7890",
            "type": "Mobile"
        },
        {
            "number": "987-654-3210",
            "type": "Work"
        }
    ]
}

Il metodo ApplyTo(Object) segue in genere le convenzioni e le opzioni di System.Text.Json per l'elaborazione di JsonPatchDocument<TModel>, incluso il comportamento controllato dalle seguenti opzioni:

• JsonNumberHandling: indica se le proprietà numeriche vengono lette dalle stringhe.
• PropertyNameCaseInsensitive: indica se i nomi delle proprietà fanno distinzione tra maiuscole e minuscole.

Differenze principali tra System.Text.Json e la nuova JsonPatchDocument<TModel> implementazione:

• Il tipo di runtime dell'oggetto di destinazione, non il tipo dichiarato, determina quali proprietà vengono modificate da ApplyTo(Object).
• System.Text.Json la deserializzazione si basa sul tipo dichiarato per identificare le proprietà idonee.

Esempio: Applicare un jsonPatchDocument con la gestione degli errori

Esistono diversi errori che possono verificarsi quando si applica un documento patch JSON. Ad esempio, l'oggetto di destinazione potrebbe non avere la proprietà specificata oppure il valore specificato potrebbe non essere compatibile con il tipo di proprietà.

JSON Patch supporta l'operazione test , che controlla se un valore specificato è uguale alla proprietà di destinazione. In caso contrario, restituisce un errore.

Nell'esempio seguente viene illustrato come gestire correttamente questi errori.

Important

L'oggetto passato al metodo ApplyTo(Object) viene modificato sul posto. Il chiamante è responsabile dell'eliminazione delle modifiche in caso di errore di un'operazione.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com"
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/Email", "value": "janedoe@gmail.com"},
    { "op": "test", "path": "/FirstName", "value": "Jane" },
    { "op": "replace", "path": "/LastName", "value": "Smith" }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document, catching any errors
Dictionary<string, string[]>? errors = null;
patchDoc!.ApplyTo(person, jsonPatchError =>
    {
        errors ??= new ();
        var key = jsonPatchError.AffectedObject.GetType().Name;
        if (!errors.ContainsKey(key))
        {
            errors.Add(key, new string[] { });
        }
        errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
    });
if (errors != null)
{
    // Print the errors
    foreach (var error in errors)
    {
        Console.WriteLine($"Error in {error.Key}: {string.Join(", ", error.Value)}");
    }
}

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

L'esempio precedente restituisce l'output seguente:

Error in Person: The current value 'John' at path 'FirstName' is not equal 
to the test value 'Jane'.
{
    "firstName": "John",
    "lastName": "Smith",              <<< Modified!
    "email": "janedoe@gmail.com",     <<< Modified!
    "phoneNumbers": []
}

Prevenzione dei rischi per la sicurezza

Quando si usa il Microsoft.AspNetCore.JsonPatch.SystemTextJson pacchetto, è fondamentale comprendere e mitigare i potenziali rischi per la sicurezza. Le sezioni seguenti illustrano i rischi di sicurezza identificati associati alla patch JSON e forniscono mitigazioni consigliate per garantire l'utilizzo sicuro del pacchetto.

Important

Questo non è un elenco completo delle minacce. Gli sviluppatori di app devono condurre revisioni del proprio modello di minaccia per determinare un elenco completo specifico dell'app e trovare soluzioni di mitigazione appropriate in base alle esigenze. Ad esempio, le app che espongono raccolte alle operazioni patch devono considerare il potenziale di attacchi di complessità algoritmica se tali operazioni inseriscono o rimuovono elementi all'inizio della raccolta.

Per ridurre al minimo i rischi di sicurezza durante l'integrazione della funzionalità Patch JSON nelle app, gli sviluppatori devono:

• Eseguire modelli di minaccia completi per le proprie app.
• Risolvere le minacce identificate.
• Seguire le mitigazioni consigliate nelle sezioni seguenti.

Denial of Service (DoS) tramite amplificazione della memoria

• Scenario: un client dannoso invia un'operazione copy che duplica più volte grafici di oggetti di grandi dimensioni, causando un consumo eccessivo di memoria.
• Impatto: potenziali condizioni di out-Of-Memory (OOM), causando interruzioni del servizio.
• Mitigation:
  • Convalidare i documenti patch JSON in ingresso per le dimensioni e la struttura prima di chiamare ApplyTo(Object).
  • La convalida deve essere specifica dell'app, ma una convalida di esempio può essere simile alla seguente:

public void Validate(JsonPatchDocument<T> patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app needs.
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count()
                              > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

Subversione della logica di business

• Scenario: le operazioni patch possono modificare i campi con invarianti impliciti (ad esempio flag interni, ID o campi calcolati), violando i vincoli aziendali.
• Impatto: problemi di integrità dei dati e comportamento imprevisto dell'app.
• Mitigation:
  • Usare oggetti POCO (Plain Old CLR Objects) con proprietà definite in modo esplicito che sono sicure da modificare.
    • Evitare di esporre proprietà sensibili o critiche per la sicurezza nell'oggetto di destinazione.
    • Se non viene usato un oggetto POCO, convalidare l'oggetto modificato dopo l'applicazione delle operazioni per garantire che le regole aziendali e le invarianti non vengano violate.

Autenticazione e autorizzazione

• Scenario: i client non autenticati o non autorizzati inviano richieste di patch JSON dannose.
• Impatto: accesso non autorizzato per modificare i dati sensibili o interrompere il comportamento dell'app.
• Mitigation:
  • Proteggere gli endpoint che accettano richieste patch JSON con meccanismi di autenticazione e autorizzazione appropriati.
  • Limitare l'accesso a client o utenti attendibili con autorizzazioni appropriate.

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

• Specifica del metodo PATCH IETF RFC 5789
• Specifica JSON Patch IETF RFC 6902
• Puntatore JSON IETF RFC 6901
• Codice sorgente JSON Patch in ASP.NET Core