ASP.NET Core Web API'sinde yanıt verilerini biçimlendirme

ASP.NET Core MVC, belirtilen biçimleri kullanarak veya istemcinin isteğine yanıt olarak yanıt verilerini biçimlendirmeyi destekler.

Biçime Özgü Eylem Sonuçları

Bazı eylem sonuç türleri ve JsonResultgibi ContentResult belirli bir biçime özeldir. Eylemler, istemcinin farklı bir biçim isteğini yoksayarak her zaman belirtilen biçimi kullanan sonuçlar döndürebilir. Örneğin, JsonResult geri döndürmek JSON biçimli verileri ve ContentResult geri döndürmek düz metin biçimli dize verilerini döndürür.

Belirli bir türü döndürmek için eylem gerekmez. ASP.NET Core herhangi bir nesne dönüş değerini destekler. Tür olmayan IActionResult nesneleri döndüren eylemlerden elde edilen sonuçlar, uygun IOutputFormatter uygulama kullanılarak serileştirilir. Daha fazla bilgi için bkz ASP.NET Core web API'sinde denetleyici işlem dönüş türleri.

Varsayılan olarak, yerleşik yardımcı yöntemi ControllerBase.Ok JSON biçimli verileri döndürür:

[HttpGet]
public IActionResult Get()
    => Ok(_todoItemStore.GetList());

Örnek kod, yapılacaklar öğelerinin listesini döndürür. Önceki kodla F12 tarayıcı geliştirici araçlarını veya http-repl'i kullanarak şunları görüntüler:

• Yanıt üst bilgisi içeren content-type:application/json; charset=utf-8.
• İstek üst bilgileri. Örneğin, Accept üst bilgi. Önceki kod tarafından Accept üst bilgi yoksayılır.

Düz metin biçimlendirilmiş verileri döndürmek için ContentResult ve Content yardımcısını kullanın.

[HttpGet("Version")]
public ContentResult GetVersion()
    => Content("v1.0.0");

Önceki kodda döndürülen Content-Typetext/plain değeridir.

Birden çok dönüş türüne sahip eylemler için döndürün IActionResult. Örneğin, işlemin sonucuna göre farklı HTTP durum kodları döndürürken.

İçerik anlaşması

İstemci bir Accept üst bilgisi belirttiğinde içerik anlaşması gerçekleşir. ASP.NET Core tarafından kullanılan varsayılan biçim JSON'dır. İçerik anlaşması şu şekildedir:

• ObjectResult tarafından uygulanır.
• Yardımcı yöntemlerden döndürülen durum koduna özgü eylem sonuçlarında yerleşik olarak bulunur. Eylem sonuçları yardımcı yöntemleri ObjectResult'ya dayanır.

Bir model türü döndürüldüğünde dönüş türü ObjectResult'dir.

Aşağıdaki eylem yöntemi ve OkNotFound yardımcı yöntemlerini kullanır:

[HttpGet("{id:long}")]
public IActionResult GetById(long id)
{
    var todo = _todoItemStore.GetById(id);

    if (todo is null)
    {
        return NotFound();
    }

    return Ok(todo);
}

Varsayılan olarak, ASP.NET Core aşağıdaki medya türlerini destekler:

• application/json
• text/json
• text/plain

Araçlar, örneğin Fiddler veya http-repl, yanıt formatını belirtmek için Accept istek başlığını ayarlayabilir. Sunucunun desteklediği bir türü içerdiğinde, Accept üst bilgisi bu türü döndürür. Sonraki bölümde ek biçimlendiricilerin nasıl ekleneceği gösterilmektedir.

Denetleyici (Controller) eylemleri, POCO'lar (Düz Eski CLR Nesneleri) döndürebilir. PoCO döndürülürken çalışma zamanı otomatik olarak nesneyi sarmalayan bir ObjectResult oluşturur. İstemci, biçimlendirilmiş serileştirilmiş nesneyi alır. Döndürülen nesne ise null, bir 204 No Content yanıt döndürülür.

Aşağıdaki örnek bir nesne türü döndürür:

[HttpGet("{id:long}")]
public TodoItem? GetById(long id)
    => _todoItemStore.GetById(id);

Önceki kodda geçerli bir yapılacaklar öğesine yönelik bir istek, bir 200 OK yanıt döndürür. Geçersiz bir yapılacaklar öğesi isteği bir 204 No Content yanıt döndürür.

Accept üst bilgisi

İçerik anlaşması , istekte bir Accept üst bilgi görüntülendiğinde gerçekleşir. Bir istek "accept" başlığı içerdiğinde ASP.NET Core:

• Kabul üst bilgisindeki medya türlerini tercih sırasına göre numaralandırır.
• Belirtilen biçimlerden birinde yanıt oluşturabilen bir biçimlendirici bulmaya çalışır.

İstemcinin isteğini karşılayan bir biçimlendirici bulunamazsa ASP.NET Core:

• MvcOptions.ReturnHttpNotAcceptable true olarak ayarlandığında 406 Not Acceptable değerini döndürür veya -
• Yanıt üretebilecek ilk biçimlendiriciyi bulmaya çalışır.

İstenen biçim için yapılandırılan bir biçimlendirici yoksa, nesneyi biçimlendirebilen ilk biçimlendirici kullanılır. İstekte üst Accept bilgi görünmüyorsa:

• Nesneyi işleyebilen ilk biçimlendirici, yanıtı seri hale getirmek için kullanılır.
• Herhangi bir pazarlık yok. Sunucu hangi biçimin döndürüleceği konusunda karara varıyor.

Accept üst bilgisi */* içeriyorsa, MvcOptions üst bilgisi RespectBrowserAcceptHeader true olarak ayarlanmadığı sürece yoksayılır.

Tarayıcılar ve içerik anlaşması

Tipik API istemcilerinden farklı olarak, web tarayıcıları Accept üst bilgileri sağlar. Web tarayıcıları joker karakterler de dahil olmak üzere birçok biçim belirtir. Varsayılan olarak, çerçeve isteğin bir tarayıcıdan geldiğini algıladığında:

• Başlık Accept yoksayılır.
• İçerik, aksi yapılandırılmadığı sürece yanıt türünü işleyebilen ilk kayıtlı çıkış biçimlendiricisi kullanılarak döndürülür.

Bu yaklaşım, API'leri kullanırken tarayıcılar arasında daha tutarlı bir deneyim sağlar.

Bir uygulamayı tarayıcı kabul üst bilgilerine saygı gösterecek şekilde yapılandırmak için RespectBrowserAcceptHeader özelliğinin true olarak ayarlanması gerekir.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    options.RespectBrowserAcceptHeader = true;
});

Biçimlendiricileri yapılandırma

Ek biçimleri desteklemesi gereken uygulamalar uygun NuGet paketlerini ekleyebilir ve desteği yapılandırabilir. Giriş ve çıkış için ayrı biçimlendiriciler vardır. Giriş biçimlendiricileri Model Bağlama tarafından kullanılır. Çıkış biçimlendiricileri yanıtları biçimlendirmek için kullanılır. Özel biçimlendirici oluşturma hakkında bilgi için bkz . Özel Biçimlendiriciler.

XML biçimi desteği ekleme

XML biçimlendiricilerini kullanılarak yapılandırmak için çağrısını gerçekleştirin.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddXmlSerializerFormatters();

Yukarıdaki kodu kullanırken denetleyici yöntemleri, isteğin Accept üst bilgisine göre uygun biçimi döndürür.

Tabanlı System.Text.Json biçimlendiricileri yapılandırma

Tabanlı biçimlendiricilerin System.Text.Jsonözelliklerini yapılandırmak için kullanın Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Aşağıdaki vurgulanmış kod varsayılan camelCase biçimlendirmesi yerine PascalCase biçimlendirmesini yapılandırıyor:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy = null;
    });

Belirli eylemler için çıkış serileştirme seçeneklerini yapılandırmak için kullanın JsonResult. Örneğin:

[HttpGet]
public IActionResult Get() 
    => new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerOptions { PropertyNamingPolicy = null });

Newtonsoft.Json-tabanlı JSON biçimi desteği ekle

Varsayılan JSON biçimlendiricileri kullanır System.Text.Json. Tabanlı biçimlendiricileri kullanmak için Newtonsoft.Json olan NuGet paketini yükleyin Microsoft.AspNetCore.Mvc.NewtonsoftJson ve Program.cs içinde yapılandırın.

var builder = WebApplication.CreateBuilder(args);

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

Yukarıdaki kodda, AddNewtonsoftJson çağrısı, aşağıdaki Web API, MVC ve Razor Pages özelliklerini Newtonsoft.Json kullanacak şekilde yapılandırıyor.

• JSON okuyan ve yazan giriş ve çıkış biçimlendiricileri
• JsonResult
• JSON Yaması
• IJsonHelper
• TempData

Bazı özellikler System.Text.Json tabanlı biçimlendiricilerle iyi çalışmayabilir ve Newtonsoft.Json tabanlı biçimlendiricilere referans gerektirebilir. Uygulama Newtonsoft.Json tabanlı formatlayıcıları kullanmaya devam ettiğinde:

• Newtonsoft.Json öznitelikleri kullanır. Örneğin, [JsonProperty] veya [JsonIgnore].
• Serileştirme ayarlarını özelleştirir.
• Newtonsoft.Json tarafından sağlanan özelliklere dayanır.

Newtonsoft.Json tabanlı biçimlendiricilerin özelliklerini yapılandırmak için SerializerSettings kullanabilirsiniz.

builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = new DefaultContractResolver();
    });

Belirli eylemler için çıkış serileştirme seçeneklerini yapılandırmak için kullanın JsonResult. Örneğin:

[HttpGet]
public IActionResult GetNewtonsoftJson()
    => new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerSettings { ContractResolver = new DefaultContractResolver() });

ProblemDetails ve ValidationProblemDetails yanıtlarını biçimlendir

Aşağıdaki aksiyon metodu, bir yanıt oluşturmak için ControllerBase.Problem'yi çağırırProblemDetails.

[HttpGet("Error")]
public IActionResult GetError()
    => Problem("Something went wrong.");

ProblemDetails Uygulama biçimi PascalCase olarak belirlese bile yanıt her zaman camelCase şeklindedir. ProblemDetails, küçük harf belirten RFC 7807'yi izler.

Öznitelik bir denetleyici sınıfına [ApiController] uygulandığında, ValidationProblemDetails denetleyici, Model Doğrulaması başarısız olduğunda bir yanıt oluşturur. Bu yanıt, modelin özellik adlarını değişmeden hata anahtarları olarak kullanan bir sözlük içerir. Örneğin, aşağıdaki model doğrulama gerektiren tek bir özellik içerir:

public class SampleModel
{
    [Range(1, 10)]
    public int Value { get; set; }
}

Varsayılan olarak, ValidationProblemDetails özellik geçersiz olduğunda Value döndürülen yanıt, aşağıdaki örnekte gösterildiği gibi hata anahtarını Valuekullanır:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-00000000000000000000000000000000-000000000000000-00",
  "errors": {
    "Value": [
      "The field Value must be between 1 and 10."
    ]
  }
}

Özellik adlarını hata anahtarları olarak biçimlendirmek için, bir uygulamayı IMetadataDetailsProvider koleksiyonuna MvcOptions.ModelMetadataDetailsProviders ekleyin. Aşağıdaki örnek, System.Text.Jsonözellik adlarını varsayılan olarak camelCase olarak biçimlendiren tabanlı bir SystemTextJsonValidationMetadataProvideruygulama ekler:

builder.Services.AddControllers();

builder.Services.Configure<MvcOptions>(options =>
{
    options.ModelMetadataDetailsProviders.Add(
        new SystemTextJsonValidationMetadataProvider());
});

SystemTextJsonValidationMetadataProvider ayrıca, oluşturucusunda, özellik adlarını biçimlendirmek için özel bir adlandırma ilkesi belirten bir JsonNamingPolicy implementasyonunu kabul eder.

Model içindeki bir özelliğin özel adını ayarlamak için özelliğinde [JsonPropertyName] özniteliğini kullanın:

public class SampleModel
{
    [Range(1, 10)]
    [JsonPropertyName("sampleValue")]
    public int Value { get; set; }
}

ValidationProblemDetails Özellik geçersiz olduğunda Value önceki model için döndürülen yanıt, aşağıdaki örnekte gösterildiği gibi hata anahtarını sampleValuekullanır:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-00000000000000000000000000000000-000000000000000-00",
  "errors": {
    "sampleValue": [
      "The field Value must be between 1 and 10."
    ]
  }
}

Yanıtı ValidationProblemDetails kullanarak biçimlendirmek için Newtonsoft.Json kullanın: NewtonsoftJsonValidationMetadataProvider

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

builder.Services.Configure<MvcOptions>(options =>
{
    options.ModelMetadataDetailsProviders.Add(
        new NewtonsoftJsonValidationMetadataProvider());
});

Varsayılan olarak, NewtonsoftJsonValidationMetadataProvider özellik adlarını camelCase olarak biçimlendirmektedir. NewtonsoftJsonValidationMetadataProvider oluşturucusunda özellik adlarını biçimlendirmek için özel bir NamingPolicy adlandırma ilkesini belirten uygulamayı da kabul eder. Model içindeki bir özelliğin özel adını ayarlamak için özniteliğini [JsonProperty] kullanın.

Biçim belirtme

Yanıt biçimlerini kısıtlamak için filtreyi [Produces] uygulayın. Çoğu Filtre gibi, [Produces] eylemde, denetleyicide veya genel kapsamda uygulanabilir.

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoItemsController : ControllerBase

Yukarıdaki [Produces] filtre:

• Denetleyici içindeki tüm eylemleri POCO'lar (Düz Eski CLR Nesneleri) veya ObjectResult türetilmiş türleri için JSON biçimli yanıtlar döndürmeye zorlar.
• Diğer biçimlendiriciler yapılandırılmış olsa ve istemci farklı bir biçim belirtse bile JSON biçimli yanıtlar döndürür.

Daha fazla bilgi için bkz . Filtreler.

Özel durum biçimlendiricileri

Bazı özel durumlar yerleşik biçimlendiriciler kullanılarak uygulanır. Varsayılan olarak, string dönüş türleri metin/düz olarak biçimlendirilir (istek halinde Accept üstbilgisi aracılığıyla metin/html). Bu davranış, StringOutputFormatter kaldırılarak silinebilir. Program.cs içindeki biçimlendiriciler kaldırılır. Model nesnesi dönüş türüne sahip eylemler, null döndürülürken 204 No Content döndürür. Bu davranış, HttpNoContentOutputFormatter kaldırılarak silinebilir. Aşağıdaki kod StringOutputFormatter ve HttpNoContentOutputFormatter öğelerini kaldırır.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    // using Microsoft.AspNetCore.Mvc.Formatters;
    options.OutputFormatters.RemoveType<StringOutputFormatter>();
    options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});

StringOutputFormatter olmadan, yerleşik JSON biçimlendirici string dönüş türlerini biçimlendirir. Yerleşik JSON biçimlendiricisi kaldırılırsa ve xml biçimlendirici kullanılabilir durumdaysa, XML biçimlendirici biçimleri string türleri döndürür. Aksi takdirde, string dönüş türleri döndürür 406 Not Acceptable.

"HttpNoContentOutputFormatter olmadan, null nesneler, yapılandırılan biçimlendirici kullanılarak biçimlendirilir." Örneğin:

• JSON biçimlendiricisi, gövdesi null olan bir yanıt döndürür.
• XML biçimlendirici, öznitelik xsi:nil="true" kümesine sahip boş bir XML öğesi döndürür.

Yanıt biçimi URL eşlemeleri

İstemciler URL'nin bir parçası olarak belirli bir biçim isteyebilir, örneğin:

• Sorgu dizesinde veya yolun bir kısmında.
• .xml veya .json gibi biçime özgü bir dosya uzantısı kullanarak.

İstek yolunun eşlenmesi, API'nin kullandığı rota yapılandırmasında belirtilmelidir. Örneğin:

[ApiController]
[Route("api/[controller]")]
[FormatFilter]
public class TodoItemsController : ControllerBase
{
    private readonly TodoItemStore _todoItemStore;

    public TodoItemsController(TodoItemStore todoItemStore)
        => _todoItemStore = todoItemStore;

    [HttpGet("{id:long}.{format?}")]
    public TodoItem? GetById(long id)
        => _todoItemStore.GetById(id);

Yukarıdaki yol, isteğe bağlı bir dosya uzantısı kullanılarak istenen biçimin belirtilmesine izin verir. [FormatFilter] özniteliği içindeki RouteData biçim değerinin varlığını denetler ve yanıt oluşturulduğunda yanıt biçimini uygun biçimlendiriciyle eşler.

Route	Formatter
/api/todoitems/5	Varsayılan çıkış biçimlendiricisi
/api/todoitems/5.json	JSON biçimlendiricisi (yapılandırıldıysa)
/api/todoitems/5.xml	XML biçimlendiricisi (yapılandırıldıysa)

Polimorfik deserializasyon

Yerleşik özellikler sınırlı bir polimorfik serileştirme kapasitesi sağlar fakat seri durumdan çıkarma desteği sunmaz. Seri durumdan çıkarma için özel bir dönüştürücü gerekir. Tam bir polimorfik seri durumdan çıkarma örneği için bkz. Polimorfik seri durumdan çıkarma.

Ek kaynaklar

• Örnek kodu görüntüleme veya indirme (indirme)