JsonPatch in ASP.NET Core-web-API

In dit artikel wordt uitgelegd hoe u JSON Patch-aanvragen kunt verwerken in een ASP.NET Core-web-API.

Pakketinstallatie

Ondersteuning voor JSON Patch in ASP.NET Core-web-API is gebaseerd op Newtonsoft.Json en vereist het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket. JSON Patch-ondersteuning inschakelen:

• Installeer het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket.

• Bel AddNewtonsoftJson. Bijvoorbeeld:

  var builder = WebApplication.CreateBuilder(args);
  
  builder.Services.AddControllers()
      .AddNewtonsoftJson();
  
  var app = builder.Build();
  
  app.UseHttpsRedirection();
  
  app.UseAuthorization();
  
  app.MapControllers();
  
  app.Run();
  

AddNewtonsoftJson vervangt de standaard op System.Text.Jsongebaseerde invoer- en uitvoerindelingen die worden gebruikt voor het opmaken van alle JSON-inhoud. Deze extensiemethode is compatibel met de volgende MVC-serviceregistratiemethoden:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch vereist het instellen van de Content-Type-header op application/json-patch+json.

Ondersteuning voor JSON Patch toevoegen bij het gebruik van System.Text.Json

De System.Text.Json-based input formatter biedt geen ondersteuning voor JSON Patch. Ondersteuning voor JSON Patch toevoegen met behulp van Newtonsoft.Json, terwijl de andere invoer- en uitvoerindelingen ongewijzigd blijven:

• Installeer het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket.

• Program.csbijwerken:

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

Met de voorgaande code wordt een exemplaar van NewtonsoftJsonPatchInputFormatter gemaakt en als het eerste element in de MvcOptions.InputFormatters-collectie ingevoegd. Deze registratievolgorde zorgt ervoor dat:

• NewtonsoftJsonPatchInputFormatter verwerkt JSON Patch-aanvragen.
• De bestaande op System.Text.Jsongebaseerde input en formatters verwerken alle andere JSON-aanvragen en -antwoorden.

Gebruik de methode Newtonsoft.Json.JsonConvert.SerializeObject om een JsonPatchDocumentte serialiseren.

HTTP-aanvraagmethode PATCH

De methoden PUT en PATCH worden gebruikt om een bestaande resource bij te werken. Het verschil is dat PUT de hele resource vervangt, terwijl PATCH alleen de wijzigingen opgeeft.

JSON-patch

JSON Patch is een indeling voor het opgeven van updates die moeten worden toegepast op een resource. Een JSON Patch-document bevat een matrix met bewerkingen. Elke bewerking identificeert een bepaald type wijziging. Voorbeelden van dergelijke wijzigingen zijn het toevoegen van een matrixelement of het vervangen van een eigenschapswaarde.

De volgende JSON-documenten vertegenwoordigen bijvoorbeeld een resource, een JSON Patch-document voor de resource en het resultaat van het toepassen van de patchbewerkingen.

Bronvoorbeeld

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

Voorbeeld van JSON-patch

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

In de voorgaande JSON:

• De eigenschap op geeft het type bewerking aan.
• De eigenschap path geeft het element aan dat moet worden bijgewerkt.
• De eigenschap value biedt de nieuwe waarde.

Resource na de patch

Dit is de resource na het toepassen van het voorgaande JSON Patch-document:

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

De wijzigingen die zijn aangebracht door een JSON Patch-document toe te passen op een resource, zijn atomisch. Als een bewerking in de lijst mislukt, wordt er geen bewerking in de lijst toegepast.

Padsyntaxis

De eigenschap van het pad van een bewerkingsobject heeft slashes tussen de niveaus. Bijvoorbeeld "/address/zipCode".

Indexen op basis van nul worden gebruikt om matrixelementen op te geven. Het eerste element van de addresses matrix bevindt zich op /addresses/0. Als u aan het einde van een matrix wilt add, gebruikt u een afbreekstreepje (-) in plaats van een indexnummer: /addresses/-.

Operaties

In de volgende tabel ziet u ondersteunde bewerkingen zoals gedefinieerd in de JSON Patch-specificatie:

Operatie	Notities
add	Voeg een eigenschap of matrixelement toe. Voor bestaande eigenschap: waarde instellen.
remove	Een eigenschap of matrixelement verwijderen.
replace	Hetzelfde als remove gevolgd door add op dezelfde locatie.
move	Hetzelfde als remove van de bron, gevolgd door add naar de bestemming met behulp van de waarde uit de bron.
copy	Hetzelfde als add naar bestemming met behulp van waarde uit de bron.
test	Retourneer de success-statuscode als de waarde op path = opgegeven value.

JSON Patch in ASP.NET Core

De ASP.NET Core-implementatie van JSON Patch is beschikbaar in het Microsoft.AspNetCore.JsonPatch NuGet-pakket.

Code van actiemethode

In een API-controller, een actiemethode voor JSON Patch:

• Wordt geannoteerd met het kenmerk HttpPatch.
• Accepteert een JsonPatchDocument<TModel>, meestal met [FromBody].
• Roept ApplyTo(Object) aan in het patchdocument om de wijzigingen toe te passen.

Hier volgt een voorbeeld:

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

Deze code van de voorbeeld-app werkt met het volgende Customer model:

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

De voorbeeldactiemethode:

• Maakt een Customer.
• De patch wordt toegepast.
• Retourneert het resultaat in de hoofdtekst van het antwoord.

In een echte app haalt de code de gegevens op uit een archief, zoals een database, en werkt de database bij nadat de patch is toegepast.

Modeltoestand

In het voorgaande voorbeeld van de actiemethode wordt een overbelasting van ApplyTo aangeroepen die de modelstatus als een van de parameters gebruikt. Met deze optie kunt u foutberichten in antwoorden krijgen. In het volgende voorbeeld ziet u de body van een 400 Ongeldige Aanvraagreactie bij een test-bewerking:

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

Dynamische objecten

In het volgende voorbeeld van een actiemethode ziet u hoe u een patch toepast op een dynamisch object:

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

    return Ok(obj);
}

De toevoegbewerking

• Als path verwijst naar een matrixelement: voegt nieuw element in vóór het element dat is opgegeven door path.
• Als path verwijst naar een eigenschap: stelt de eigenschapswaarde in.
• Als path verwijst naar een niet-bestaande locatie:
  • Als de resource die moet worden gepatcht een dynamisch object is: voegt een eigenschap toe.
  • Als de resource om te patchen een statisch object is: de aanvraag mislukt.

In het volgende voorbeeldpatchdocument wordt de waarde van CustomerName ingesteld en wordt een Order-object toegevoegd aan het einde van de Orders-matrix.

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

De verwijderbewerking

• Als path verwijst naar een matrixelement: verwijdert het element.
• Als path verwijst naar een eigenschap:
  • Als de resource om te patchen een dynamisch object is, wordt de eigenschap verwijderd.
  • Als de resource om te patchen een statisch object is:
    • Als de eigenschap nullable is: stelt deze in op null.
    • Als de eigenschap niet nullbaar is, stelt u deze in op default<T>.

De volgende voorbeeldpatch stelt document CustomerName in op null en verwijdert Orders[0]:

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

De vervangingsbewerking

Deze bewerking is functioneel hetzelfde als een remove gevolgd door een add.

In het volgende voorbeeldpatchdocument wordt de waarde van CustomerName ingesteld en wordt Orders[0]vervangen door een nieuw Order-object:

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

De verplaatsingsbewerking

• Als path verwijst naar een matrixelement: kopieert from element naar de locatie van path element en voert vervolgens een remove bewerking uit op het from element.
• Als path verwijst naar een eigenschap: kopieert de waarde van from eigenschap naar path eigenschap en voert vervolgens een remove bewerking uit op de eigenschap from.
• Als path verwijst naar een niet-bestaande eigenschap:
  • Als de resource om te patchen een statisch object is: de aanvraag mislukt.
  • Als de resource die moet worden gepatcht een dynamisch object is: kopieert from eigenschap naar de locatie aangegeven door pathen voert vervolgens een remove bewerking uit op de eigenschap from.

Het volgende voorbeeldpatchdocument:

• Kopieert de waarde van Orders[0].OrderName naar CustomerName.
• Hiermee stelt u Orders[0].OrderName in op null.
• Hiermee verplaatst u Orders[1] naar vóór Orders[0].

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

De kopieerbewerking

Deze bewerking is functioneel hetzelfde als een move bewerking zonder de laatste remove stap.

Het volgende voorbeeldpatchdocument:

• Kopieert de waarde van Orders[0].OrderName naar CustomerName.
• Voegt een kopie van Orders[1] in vóór Orders[0].

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

De testbewerking

Als de waarde op de locatie die wordt aangegeven door path verschilt van de waarde in value, mislukt de aanvraag. In dat geval mislukt de hele PATCH-aanvraag, zelfs als alle andere bewerkingen in het patchdocument anders zouden slagen.

De test bewerking wordt vaak gebruikt om een update te voorkomen wanneer er een gelijktijdigheidsconflict is.

Het volgende voorbeeldpatchdocument heeft geen effect als de initiële waarde van CustomerName 'John' is, omdat de test mislukt:

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

De code ophalen

voorbeeldcode weergeven of downloaden. (Hoe te downloaden).

Als u het voorbeeld wilt testen, voert u de app uit en verzendt u HTTP-aanvragen met de volgende instellingen:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• HTTP-methode: PATCH
• Koptekst: Content-Type: application/json-patch+json
• Hoofdtekst: Kopieer en plak een van de voorbeelden van JSON-patchdocumenten uit de JSON- projectmap.

Aanvullende informatiebronnen

• IETF RFC 5789 PATCH-methodespecificatie
• IETF RFC 6902 JSON Patch-specificatie
• IETF RFC 6901 JSON Pointer
• ASP.NET Core broncode van JSON Patch