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

Rick Anderson ve Steve Smith

ASP.NET Core MVC, yanıt verilerini biçimlendirme desteğine sahip. 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 ( nasılindir)

Biçime Özgü Eylem Sonuçları

Bazı eylem sonuç türleri ve gibi belirli bir biçime JsonResult ContentResult özeldir. Eylemler, istemci tercihlerine bakılmaksızın belirli bir biçimde biçimlendirilmiş sonuçlar getirebilirsiniz. Örneğin, döndürerek JsonResult JSON biçimli veriler döndürür. veya ContentResult dizesi döndürerek düz metin biçimlendirilmiş dize verileri döndürür.

Belirli bir türün dönüş için bir eylem gerekli değildir. ASP.NET Core herhangi bir nesne dönüş değerini destekler. Türler dışında nesnelere dönüşen IActionResult eylemlerin sonuçları, uygun uygulama kullanılarak seri hale IOutputFormatter getirilecek. Daha fazla bilgi için bkz. Web API'sinde denetleyici eylemi ASP.NET Core türleri.

Yerleşik yardımcı yöntemi Ok JSON biçimli verileri döndürür: [!code-csharp]

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

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

Düz metin biçimlendirilmiş verileri geri dönmek için ContentResult ve Content yardımcısini kullanın:

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

Yukarıdaki kodda döndürülen Content-Type text/plain değeridir. dizesini döndürerek Content-Type teslimi: 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, IActionResult dönüş. Örneğin, gerçekleştirilen işlemlerin sonuçlarına göre farklı HTTP durum kodları döndürebilirsiniz.

İçerik anlaşması

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

• tarafından ObjectResult uygulanır.
• Yardımcı yöntemlerden döndürülen durum koduna özgü eylem sonuçları yerleşiktir. Eylem sonuçları yardımcı yöntemleri temel ObjectResult almaktadır.

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

Aşağıdaki eylem yöntemi ve Ok NotFound 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 application/json , text/json ve medya türlerini text/plain destekler. Fiddler veya Postman gibi araçlar, dönüş biçimini Accept belirtmek için istek üst bilgisine sahip olabilir. Üst Accept bilgi sunucunun desteklediği bir tür içerdiğinde bu tür döndürülür. Sonraki bölümde, ek biçimlendirenler ekleme hakkında bilgi ve bilgiler yer almaktadır.

Denetleyici eylemleri POCO'ları (Düz Eski CLR Nesneleri) dönüşebiliyor. Bir POCO döndürüldü, çalışma zamanı otomatik olarak ObjectResult nesnesini sarmalar bir 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üren:

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

Yukarıdaki kodda, geçerli bir yazar diğer adı için istek, 200 OK yazarın verileriyle bir yanıt döndürür. Geçersiz diğer ad isteği bir yanıt 204 No Content döndürür.

Accept üst bilgisi

İçerik anlaşması, istekte Accept bir üst bilgi görüntülendiğinde uzlanır. İstek bir kabul üst bilgisi içerdiğinde ASP.NET Core:

• Tercih sırasına göre kabul üst bilgisinde yer alan medya türlerini numaralar.
• Belirtilen biçimlerden biri içinde yanıt üretecek bir biçimlendirıcı bulmaya çalışır.

İstemcinin isteğini karşılayamıyorsa şu ASP.NET Core:

• , 406 Not Acceptable veya MvcOptions.ReturnHttpNotAcceptable olarak true ayarlanmışsa döndürür-
• Yanıt üretecek ilk biçimlendirıcıyı bulmaya çalışır.

İstenen biçim için hiçbir biçimlendirıcı yapılandırılmamışsa, nesneyi biçimlendiren ilk biçimlendiren kullanılır. İstekte Accept üst bilgi yoksa:

• Yanıtı serileştirmek için nesnesini işleyemeyen ilk biçimlendiren kullanılır.
• Herhangi bir anlaşma yok. Sunucu, hangi biçimin geri döneceğine karar verir.

Accept üst bilgisi */* içeriyorsa, üzerinde true olarak ayarlanmazsa Üst Bilgi RespectBrowserAcceptHeader yoksayılır. MvcOptions

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

Tipik API istemcilerinin aksine, web tarayıcıları üst Accept bilgileri sağlar. Web tarayıcısı 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ılasa:

• Üst Accept bilgi yoksayılır.
• Aksi yapılandırılmadıkça içerik JSON ile döndürülür.

Bu, API'leri tüketen tarayıcılar arasında daha tutarlı bir deneyim sağlar.

Bir uygulamayı tarayıcının üst bilgileri kabul etmelerini kabul etmek üzere yapılandırmak için olarak RespectBrowserAcceptHeader true ayarlayın:

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

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

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

Biçimlendirenleri yapılandırma

Ek biçimleri desteklemesi gereken uygulamalar, uygun paketleri NuGet ve desteği yapılandırabilirsiniz. Giriş ve çıkış için ayrı biçimlendirenler vardır. Giriş biçimlendirenler Model Bağlaması tarafından kullanılır. Çıkış biçimlendirenler, yanıtları biçimlendirmek için kullanılır. Özel biçimlendirıcı oluşturma hakkında bilgi için bkz. Özel Biçimlendirenler.

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

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

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

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

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

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

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

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

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
        .AddXmlSerializerFormatters();
}

Biçim belirtin

Yanıt biçimlerini kısıtlamak için [Produces] filtreyi uygulayın. Çoğu filtregibi [Produces] eylem, denetleyici veya genel kapsamda de uygulanabilir:

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

Önceki [Produces] filtre:

• Denetleyici içindeki tüm eylemleri JSON biçimli yanıtları döndürecek şekilde zorlar.
• Diğer formatlayıcılar yapılandırıldıysa ve istemci farklı bir biçim belirtiyorsa JSON döndürülür.

Daha fazla bilgi için bkz. Filtreler.

Özel durum formatları

Bazı özel durumlar, yerleşik formatlayıcılar kullanılarak uygulanır. Varsayılan olarak, string dönüş türleri metin/düz olarak biçimlendirilir (üst bilgi ile isteniyorsa metin/html Accept ). Bu davranış, ' ı kaldırılarak silinebilir StringOutputFormatter . Biçimlendiriciler ConfigureServices yönteminde kaldırılır. Bir model nesne dönüş türü döndürme sırasında döndürülen eylemler 204 No Content null . Bu davranış, ' ı kaldırılarak silinebilir HttpNoContentOutputFormatter . Aşağıdaki kod ve öğesini kaldırır StringOutputFormatter HttpNoContentOutputFormatter .

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

Olmadan StringOutputFormatter , YERLEŞIK JSON biçimlendiricisi, string dönüş türlerini biçimlendirir. Yerleşik JSON biçimlendiricisi kaldırılırsa ve bir XML biçimlendirici varsa, XML biçimlendirici, string dönüş türlerini biçimlendirir. Aksi takdirde, string dönüş türleri döndürülür 406 Not Acceptable .

Olmadan HttpNoContentOutputFormatter , null nesneler yapılandırılmış biçimlendirici kullanılarak biçimlendirilir. Örneğin:

• JSON biçimlendiricisi, gövdesi olan bir yanıt döndürür null .
• XML biçimlendiricisi özniteliği ayarlanmış bir boş XML öğesi döndürüyor xsi:nil="true" .

Yanıt biçimi URL eşlemeleri

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

• Sorgu dizesinde veya yolun bir bölümünde.
• .xml veya. JSON gibi formata özgü bir dosya uzantısı kullanarak.

İstek yolundan eşleme, API 'nin kullandığı rotada belirtilmelidir. Örneğin:

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

Önceki yol, istenen biçimin isteğe bağlı bir dosya uzantısı olarak belirtilmesini sağlar. [FormatFilter]Özniteliği, içindeki biçim değerinin varlığını denetler RouteData ve yanıt oluşturulduğunda yanıt biçimini uygun biçimlendirici ile eşler.