ASP.NET Core web API'sinde JsonPatch

Bu makalede, ASP.NET Core web API'sinde ON Patch isteklerinin nasıl işleneceğini JSaçıklanmaktadır.

Paket yükleme

JSASP.NET Core web API'sindeki ON Patch desteği NuGet paketini temel alır Newtonsoft.Json ve gerektirir Microsoft.AspNetCore.Mvc.NewtonsoftJson . ON Patch desteğini etkinleştirmek JSiçin:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet paketini yükleyin.

• AddNewtonsoftJson çağrısı yapın. Örnek:

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

AddNewtonsoftJson, tümJSON içeriğini biçimlendirmek için kullanılan varsayılan System.Text.Jsontabanlı giriş ve çıkış biçimlendiricilerinin yerini alır. Bu uzantı yöntemi aşağıdaki MVC hizmet kayıt yöntemleriyle uyumludur:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch için üst bilginin application/json-patch+jsonolarak ayarlanması Content-Type gerekir.

System.Text.Json kullanırken ON Patch desteği JSekleme

System.Text.JsonTabanlı giriş biçimlendirici ON Patch'i desteklemezJS. kullanarak Newtonsoft.JsonON Patch desteği eklemek ve diğer giriş ve çıkış biçimlendiricilerini değiştirmeden bırakmak içinJS:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet paketini yükleyin.

• Güncelleştirme 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();
      }
  }
  

Yukarıdaki kod bir örneği NewtonsoftJsonPatchInputFormatter oluşturur ve bunu koleksiyondaki MvcOptions.InputFormatters ilk girdi olarak ekler. Bu kayıt sırası aşağıdakilerin sağlanmasını sağlar:

• NewtonsoftJsonPatchInputFormatterJSON Patch isteklerini işler.
• Mevcut System.Text.Jsontabanlı giriş ve biçimlendiriciler diğer JStüm ON isteklerini ve yanıtlarını işler.

Newtonsoft.Json.JsonConvert.SerializeObject bir serileştirmek JsonPatchDocumentiçin yöntemini kullanın.

PATCH HTTP istek yöntemi

PUT ve PATCH yöntemleri, mevcut bir kaynağı güncelleştirmek için kullanılır. Aralarındaki fark, PUT'nin kaynağın tamamının yerini aldığı, PATCH'nin ise yalnızca değişiklikleri belirttiğidir.

JSON Patch

JSON Patch , bir kaynağa uygulanacak güncelleştirmeleri belirtmek için bir biçimdir. JSON Patch belgesinde bir dizi işlem vardır. Her işlem belirli bir değişiklik türünü tanımlar. Dizi öğesi ekleme veya özellik değerini değiştirme gibi değişikliklere örnek olarak verilebilir.

Örneğin, aşağıdaki JSON belgeleri bir kaynağı, kaynak için on JSPatch belgesini ve Patch işlemlerinin uygulanmasının sonucunu temsil eder.

Kaynak örneği

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

JSON düzeltme eki örneği

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

Yukarıdaki JSON'da:

• op özelliği, işlemin türünü gösterir.
• path özelliği, güncelleştirilecek öğeyi gösterir.
• value özelliği yeni değeri sağlar.

Düzeltme eki sonrasındaki kaynak

Yukarıdaki JSON Patch belgesi uygulandıktan sonra kaynak aşağıdadır:

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

Kaynağa ON JSPatch belgesi uygulanarak yapılan değişiklikler atomik olarak yapılır. Listedeki herhangi bir işlem başarısız olursa, listedeki hiçbir işlem uygulanmaz.

Yol söz dizimi

İşlem nesnesinin path özelliği düzeyler arasında eğik çizgi içerir. Örneğin, "/address/zipCode".

Dizi öğelerini belirtmek için sıfır tabanlı dizinler kullanılır. Dizinin ilk öğesi addresses konumunda /addresses/0olacaktır. Dizinin add sonuna kadar dizin numarası yerine kısa çizgi (-) kullanın: /addresses/-.

Operations

Aşağıdaki tabloda, ON Patch belirtiminde JStanımlanan desteklenen işlemler gösterilmektedir:

İşlem	Notlar
add	Özellik veya dizi öğesi ekleyin. Mevcut özellik için: set value.
remove	Bir özelliği veya dizi öğesini kaldırın.
replace	Aynı konumda ve ardından add aynı konumda olduğu gibiremove.
move	Kaynaktan alınan değeri kullanarak kaynaktan add hedefe kadar remove olan değerle aynıdır.
copy	add Kaynaktan değer kullanan hedefle aynıdır.
test	= değeri sağlandıysa pathvaluebaşarı durum kodunu döndürür.

JSASP.NET Core'da ON Düzeltme Eki

ON Patch'in JSASP.NET Core uygulaması Microsoft.AspNetCore.JsonPatch NuGet paketinde sağlanır.

Eylem yöntemi kodu

BIR API denetleyicisinde ON Patch için JSbir eylem yöntemi:

• özniteliğiyle HttpPatch ek açıklama eklenir.
• genellikle ile bir JsonPatchDocument<TModel>[FromBody]kabul eder.
• Değişiklikleri uygulamak için düzeltme eki belgesine çağrılar ApplyTo(Object) .

Aşağıda bir örnek verilmiştir:

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

Örnek uygulamadaki bu kod aşağıdaki Customer modelle çalışır:

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

Örnek eylem yöntemi:

• bir Customeroluşturur.
• Düzeltme ekini uygular.
• Yanıtın gövdesindeki sonucu döndürür.

Gerçek bir uygulamada kod, verileri veritabanı gibi bir depodan alır ve düzeltme ekini uyguladıktan sonra veritabanını güncelleştirir.

Model durumu

Yukarıdaki eylem yöntemi örneği, model durumunu parametrelerinden biri olarak alan bir aşırı yüklemesini ApplyTo çağırır. Bu seçenekle yanıtlarda hata iletileri alabilirsiniz. Aşağıdaki örnek, bir işlem için test 400 Hatalı İstek yanıtının gövdesini gösterir:

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

Dinamik nesneler

Aşağıdaki eylem yöntemi örneği, bir dinamik nesneye düzeltme ekinin nasıl uygulanacağını gösterir:

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

    return Ok(obj);
}

Ekleme işlemi

• Bir dizi öğesine işaret ederse path : tarafından pathbelirtilen öğeden önce yeni öğe ekler.
• Bir özelliğe işaret ederse path : özellik değerini ayarlar.
• Var olmayan bir konuma işaret ederse path :
  • Düzeltme eki uygulama kaynağı dinamik bir nesneyse: bir özellik ekler.
  • Düzeltme eki uygulanacak kaynak statik bir nesneyse, istek başarısız olur.

Aşağıdaki örnek düzeltme eki belgesi değerini CustomerName ayarlar ve dizinin sonuna Orders bir Order nesne ekler.

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

Kaldırma işlemi

• Bir dizi öğesine işaret ederse path : öğesini kaldırır.
• Bir özelliğe işaret ederse path :
  • Düzeltme eki uygulanacak kaynak dinamik bir nesneyse: özelliği kaldırır.
  • Düzeltme eki uygulanacak kaynak statik bir nesneyse:
    • Özellik null atanabilirse: null olarak ayarlar.
    • Özelliği null atanamazsa olarak ayarlar default<T>.

Aşağıdaki örnek düzeltme eki belge null olarak ayarlanır CustomerName ve silinir Orders[0]:

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

Değiştirme işlemi

Bu işlem işlevsel olarak bir remove ile aynıdır ve ardından bir ile aynıdır add.

Aşağıdaki örnek düzeltme eki belgesi değerini CustomerName ayarlar ve değerini yeni Order bir nesneyle değiştirirOrders[0]:

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

Taşıma işlemi

• Bir dizi öğesine işaret edersepath: öğeyi öğenin konumuna path kopyalarfrom, ardından öğesinde from bir remove işlem çalıştırır.
• Bir özelliğe işaret edersepath: özelliğin pathfrom değerini özelliğe kopyalar, ardından özelliğinde from bir remove işlem çalıştırır.
• Var olmayan bir özelliğe işaret ederse path :
  • Düzeltme eki uygulanacak kaynak statik bir nesneyse, istek başarısız olur.
  • Düzeltme eki uygulanacak kaynak dinamik bir nesneyse: özelliği tarafından pathbelirtilen konuma kopyalar from ve özelliği üzerinde from bir remove işlem çalıştırır.

Aşağıdaki örnek düzeltme eki belgesi:

• değerini Orders[0].OrderName olarak CustomerNamekopyalar.
• Null olarak ayarlanır Orders[0].OrderName .
• öncesine Orders[0]giderOrders[1].

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

Kopyalama işlemi

Bu işlem işlevsel olarak son remove adım olmadan bir move işlemle aynıdır.

Aşağıdaki örnek düzeltme eki belgesi:

• değerini Orders[0].OrderName olarak CustomerNamekopyalar.
• öncesinin Orders[1]Orders[0]bir kopyasını ekler.

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

Test işlemi

tarafından path belirtilen konumdaki değer, içinde valuesağlanan değerden farklıysa istek başarısız olur. Bu durumda düzeltme eki belgesindeki diğer tüm işlemler başarılı olsa bile PATCH isteğinin tamamı başarısız olur.

İşlem test genellikle eşzamanlılık çakışması olduğunda güncelleştirme yapılmasını önlemek için kullanılır.

Aşağıdaki örnek düzeltme eki belgesinin ilk değeri CustomerName "John" ise hiçbir etkisi yoktur, çünkü test başarısız olur:

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

Kodu alma

Örnek kodu görüntüleyin veya indirme. (Nasıl indirilir).

Örneği test etmek için uygulamayı çalıştırın ve aşağıdaki ayarlarla HTTP istekleri gönderin:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• HTTP yöntemi: PATCH
• Üstbilgi: Content-Type: application/json-patch+json
• Gövde: ON proje klasöründeki JSON düzeltme eki belge örneklerinden JSbirini kopyalayıp yapıştırın.

Ek kaynaklar

• IETF RFC 5789 PATCH yöntemi belirtimi
• IETF RFC 6902 JSON Patch belirtimi
• IETF RFC 6901 JSON İşaretçisi
• JSON Patch belgeleri. ON Patch belgeleri oluşturmaya JSyönelik kaynakların bağlantılarını içerir.
• ASP.NET Core JSON Patch kaynak kodu