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 on biçimli verileri döndürürken JS, döndüren ContentResult ise 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.

Yerleşik yardımcı yöntemi ControllerBase.Ok varsayılan olarak ON biçimlendirilmiş verileri döndürür JS:

[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:application/json; charset=utf-8 içeren yanıt üst bilgisi.
  • İ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 ON'dırJS. İç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 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

Fiddler veya Postman gibi araçlar, dönüş biçimini belirtmek için istek üst bilgisini ayarlayabilirAccept. Ü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:

İ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 ON içinde JSdö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;
    });

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.

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:

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ç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 ON biçimli yanıtlar döndürmeye JSzorlar.
  • Diğer biçimlendiriciler yapılandırılmış olsa ve istemci farklı bir biçim belirtse bile ON biçimli yanıtlar döndürebilirsiniz JS.

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ılmışsa)
/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

ASP.NET Core MVC, yanıt verilerini biçimlendirme desteğine sahiptir. Yanıt verileri belirli biçimler kullanılarak veya istemci tarafından istenen biçime yanıt olarak biçimlendirilebilir.

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

Biçime Özgü Eylem Sonuçları

Bazı eylem sonuç türleri ve ContentResultgibi JsonResult belirli bir biçime özeldir. Eylemler, istemci tercihlerinden bağımsız olarak belirli bir biçimde biçimlendirilmiş sonuçlar döndürebilir. Örneğin, döndürüldüğünde JsonResult ON biçimlendirilmiş veriler döndürülüyor JS. veya dize, 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.

Yerleşik yardımcı yöntemi Ok ON biçimlendirilmiş verileri döndürür JS:

// GET: api/authors
[HttpGet]
public ActionResult Get()
{
    return Ok(_authors.List());
}

Örnek indirme, yazarların listesini döndürür. Önceki kodla F12 tarayıcı geliştirici araçlarını veya http-repl'i kullanma:

  • content-type:application/json; charset=utf-8 içeren yanıt üst bilgisi görüntülenir.
  • İstek üst bilgileri görüntülenir. Ö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:

// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
    return Content("An API listing authors of docs.asp.net.");
}

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

// GET api/authors/version
[HttpGet("version")]
public string Version()
{
    return "Version 1.0.0";
}

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

İç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 ON'dırJS. İç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 OkNotFound yardımcı yöntemlerini kullanır:

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authors.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

varsayılan olarak, ASP.NET Core , text/jsonve text/plain medya türlerini desteklerapplication/json. 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.

Nesne türü döndürülerek:

// GET api/authors/RickAndMSFT
[HttpGet("{alias}")]
public Author Get(string alias)
{
    return _authors.GetByAlias(alias);
}

Önceki kodda geçerli bir yazar diğer adı isteği, yazarın verileriyle birlikte bir 200 OK yanıt döndürür. Geçersiz diğer ad 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:

İ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 ON içinde JSdö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 trueolarak ayarlayınRespectBrowserAcceptHeader:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true; // false by default
    });
}

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 XmlSerializer uygulanan XML biçimlendiricileri çağrılarak AddXmlSerializerFormattersyapılandırılır:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddXmlSerializerFormatters();
}

Yukarıdaki kod kullanarak XmlSerializersonuçları serileştirir.

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

System.Text.Json Tabanlı biçimlendiricilerin özellikleri kullanılarak Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptionsyapılandırılabilir. Varsayılan biçimlendirme camelCase'dir. Aşağıdaki vurgulanmış kod PascalCase biçimlendirmesini ayarlar:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddJsonOptions(options =>
            options.JsonSerializerOptions.PropertyNamingPolicy = null);
}

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

[HttpGet("error")]
public IActionResult GetError()
{
    return Problem("Something went wrong!");
}

Yukarıdaki kodla:

  • https://localhost:5001/WeatherForecast/temperature PascalCase döndürür.
  • https://localhost:5001/WeatherForecast/error camelCase döndürür. Uygulama biçimi PascalCase olarak belirlese bile hata yanıtı her zaman camelCase olur. ProblemDetails, küçük harf belirten RFC 7807'yi izler

Aşağıdaki kod PascalCase'i ayarlar ve özel bir dönüştürücü ekler:

services.AddControllers().AddJsonOptions(options =>
{
    // Use the default property (Pascal) casing.
    options.JsonSerializerOptions.PropertyNamingPolicy = null;

    // Configure a custom converter.
    options.JsonSerializerOptions.Converters.Add(new MyCustomJsonConverter());
});

Eylem başına çıkış serileştirme seçenekleri kullanılarak JsonResultyapılandırılabilir. Örneğin:

public IActionResult Get()
{
    return Json(model, new JsonSerializerOptions
    {
        WriteIndented = true,
    });
}

Newtonsoft.Json tabanlı JSON biçim desteği ekleme

Varsayılan JSON biçimlendiricileri temel alır System.Text.Json. NuGet paketini yükleyip Microsoft.AspNetCore.Mvc.NewtonsoftJson içinde Startup.ConfigureServicesyapılandırarak, tabanlı biçimlendiriciler ve özellikler için Newtonsoft.Json destek sağlanır.

public void ConfigureServices(IServiceCollection services)
{
    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:

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.

Newtonsoft.JsonTabanlı biçimlendiricilerin özellikleri kullanılarak Microsoft.AspNetCore.Mvc.MvcNewtonsoftJsonOptions.SerializerSettingsyapılandırılabilir:

services.AddControllers().AddNewtonsoftJson(options =>
{
    // Use the default property (Pascal) casing
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();

    // Configure a custom converter
    options.SerializerSettings.Converters.Add(new MyCustomJsonConverter());
});

Eylem başına çıkış serileştirme seçenekleri kullanılarak JsonResultyapılandırılabilir. Örneğin:

public IActionResult Get()
{
    return Json(model, new JsonSerializerSettings
    {
        Formatting = Formatting.Indented,
    });
}

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("[controller]")]
[Produces("application/json")]
public class WeatherForecastController : 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 ON biçimli yanıtlar döndürmeye JSzorlar.
  • Diğer biçimlendiriciler yapılandırılırsa ve istemci farklı bir biçim belirtirse, JSON döndürülü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 yönteminde ConfigureServices kaldı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.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        // requires 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:

[Route("api/[controller]")]
[ApiController]
[FormatFilter]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}.{format?}")]
    public Product Get(int id)
    {

Yukarıdaki yol, istenen biçimin isteğe bağlı bir dosya uzantısı olarak 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/products/5 Varsayılan çıkış biçimlendiricisi
/api/products/5.json JSON biçimlendiricisi (yapılandırılmışsa)
/api/products/5.xml XML biçimlendiricisi (yapılandırıldıysa)

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 on biçimli verileri döndürürken JS, döndüren ContentResult ise 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.

Yerleşik yardımcı yöntemi ControllerBase.Ok varsayılan olarak ON biçimlendirilmiş verileri döndürür JS:

[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:application/json; charset=utf-8 içeren yanıt üst bilgisi.
  • İ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 ON'dırJS. İç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 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

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:

İ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 ON içinde JSdö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:

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 ON biçimli yanıtlar döndürmeye JSzorlar.
  • Diğer biçimlendiriciler yapılandırılmış olsa ve istemci farklı bir biçim belirtse bile ON biçimli yanıtlar döndürebilirsiniz JS.

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ılmışsa)
/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