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 ContentResultgibi JsonResult 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, döndürme JsonResult JSON biçimli verileri döndürür ve döndüren ContentResult , 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 eylemi 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:

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

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

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

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

Birden çok dönüş türüne sahip eylemler için döndür.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:

• tarafından ObjectResultuygulanı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 temel ObjectResultalır.

Bir model türü döndürülürken dönüş türü şeklindedir ObjectResult.

Aşağıdaki eylem yöntemi ve Ok NotFound 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

Fiddler veya http-repl gibi araçlar, dönüş biçimini belirtmek için istek üst bilgisini ayarlayabilir Accept . Üst bilgi sunucunun Accept desteklediği bir tür içerdiğinde, bu tür döndürülür. Sonraki bölümde ek biçimlendiricilerin nasıl ekleneceği gösterilmektedir.

Denetleyici 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 öğesi isteği 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 kabul üst bilgisi 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:

• , veya - olarak ayarlanmışsa MvcOptions.ReturnHttpNotAcceptable truedöndürür 406 Not Acceptable
• 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*/*, üzerinde MvcOptionstrue olarak ayarlanmadığı sürece RespectBrowserAcceptHeader Üst Bilgi yoksayılır.

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

Tipik API istemcilerinden farklı olarak web tarayıcıları üst bilgiler sağlar Accept . 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:

• Üst Accept bilgi yoksayılır.
• İçerik, aksi yapılandırılmadığı sürece JSON'da 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ı üst bilgilerini kabul etmek üzere yapılandırmak için özelliğini olarak trueayarlayınRespectBrowserAcceptHeader:

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

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

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ı biçimlendiricileri yapılandırma System.Text.Json

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

Tabanlı JSON biçimi desteği ekleme Newtonsoft.Json

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

var builder = WebApplication.CreateBuilder(args);

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

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

• JSON okuyan ve yazan giriş ve çıkış biçimlendiricileri
• JsonResult
• JSON Düzeltme Eki
• IJsonHelper
• TempData

Bazı özellikler tabanlı biçimlendiricilerle System.Text.Jsondüzgün çalışmayabilir ve tabanlı biçimlendiricilere başvuru Newtonsoft.Jsongerektirebilir. Uygulama şu Newtonsoft.Jsondurumlarda -based formatters kullanmaya devam edin:

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

Tabanlı biçimlendiricilerin Newtonsoft.Jsonözelliklerini yapılandırmak için kullanın SerializerSettings:

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

Biçimlendirme ProblemDetails ve ValidationProblemDetails yanıtlar

Aşağıdaki eylem yöntemi yanıt oluşturmak ProblemDetails için çağrı yaparControllerBase.Problem:

[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.

Özniteliği bir denetleyici sınıfına [ApiController] uygulandığında, Model Doğrulaması başarısız olduğunda denetleyici bir ValidationProblemDetails 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."
    ]
  }
}

Hata anahtarları olarak kullanılan özellik adlarını biçimlendirmek için, uygulaması koleksiyonuna MvcOptions.ModelMetadataDetailsProviders ekleyinIMetadataDetailsProvider. Aşağıdaki örnek, SystemTextJsonValidationMetadataProviderözellik adlarını varsayılan olarak camelCase olarak biçimlendiren tabanlı bir System.Text.Jsonuygulama ekler:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider ayrıca, özellik adlarını biçimlendirmek için özel bir JsonNamingPolicy adlandırma ilkesi belirten oluşturucusunda uygulamasını 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."
    ]
  }
}

kullanarak yanıtı biçimlendirmek ValidationProblemDetails için kullanınNewtonsoftJsonValidationMetadataProvider:Newtonsoft.Json

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 ayrıca, özellik adlarını biçimlendirmek için özel bir NamingPolicy adlandırma ilkesi belirten oluşturucusunda uygulamasını 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 eylem, [Produces] denetleyici veya genel kapsamda da 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 (üst bilgi aracılığıyla Accept istenirse metin/html) olarak biçimlendirilir. Bu davranış, kaldırılarak StringOutputFormattersilinebilir. Biçimlendiriciler içinde Program.cskaldırılır. Model nesnesi dönüş türüne sahip eylemler, döndürürken nulldöndürür204 No Content. Bu davranış, kaldırılarak HttpNoContentOutputFormattersilinebilir. Aşağıdaki kod ve HttpNoContentOutputFormatteröğesini StringOutputFormatter 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>();
});

StringOutputFormatterolmadan, yerleşik JSON biçimlendirici biçimleri string türleri döndürür. 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.

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

• JSON biçimlendiricisi gövdesine nullsahip 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 bölümünde.
• .xml veya .json gibi biçime özgü bir dosya uzantısı kullanarak.

İstek yolundan eşleme, API'nin kullandığı yolda 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.

Rota	Biçimlendiricisi
/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 seri durumdan çıkarma

Yerleşik özellikler sınırlı bir polimorfik serileştirme aralığı sağlar ancak 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)