Memformat data respons di ASP.NET Core Web API

ASP.NET Core MVC mendukung data respons pemformatan, menggunakan format tertentu atau sebagai respons terhadap permintaan klien.

Hasil Tindakan khusus format

Beberapa jenis hasil tindakan khusus untuk format tertentu, seperti JsonResult dan ContentResult. Tindakan dapat mengembalikan hasil yang selalu menggunakan format tertentu, mengabaikan permintaan klien untuk format yang berbeda. Misalnya, mengembalikan JsonResult data berformat JSON dan mengembalikan ContentResult data string berformat teks biasa.

Tindakan tidak diperlukan untuk mengembalikan jenis tertentu. ASP.NET Core mendukung nilai pengembalian objek apa pun. Hasil dari tindakan yang mengembalikan objek yang bukan IActionResult jenis diserialisasikan menggunakan implementasi yang sesuai IOutputFormatter . Untuk informasi selengkapnya, lihat Jenis pengembalian tindakan pengontrol di API web ASP.NET Core.

Secara default, metode ControllerBase.Ok pembantu bawaan mengembalikan data berformat JSON:

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

Kode sampel mengembalikan daftar item todo. Menggunakan alat pengembang browser F12 atau http-repl dengan kode sebelumnya ditampilkan:

• Header respons yang berisi jenis konten: application/json; charset=utf-8.
• Header permintaan. Misalnya, Accept header . Header Accept diabaikan oleh kode sebelumnya.

Untuk mengembalikan data berformat teks biasa, gunakan ContentResult dan pembantu Content :

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

Dalam kode sebelumnya, yang Content-Type dikembalikan adalah text/plain.

Untuk tindakan dengan beberapa jenis pengembalian, kembalikan IActionResult. Misalnya, saat mengembalikan kode status HTTP yang berbeda berdasarkan hasil operasi.

Negosiasi konten

Negosiasi konten terjadi ketika klien menentukan header Terima. Format default yang digunakan oleh ASP.NET Core adalah JSON. Negosiasi konten adalah:

• Diimplementasikan oleh ObjectResult.
• Dibangun ke dalam hasil tindakan khusus kode status yang dikembalikan dari metode pembantu. Metode pembantu hasil tindakan didasarkan pada ObjectResult.

Saat jenis model dikembalikan, jenis pengembaliannya adalah ObjectResult.

Metode tindakan berikut menggunakan metode dan NotFound pembantuOk:

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

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

    return Ok(todo);
}

Secara default, ASP.NET Core mendukung jenis media berikut:

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

Alat seperti Fiddler atau http-repl dapat mengatur Accept header permintaan untuk menentukan format pengembalian. Accept Ketika header berisi jenis yang didukung server, jenis tersebut dikembalikan. Bagian berikutnya memperlihatkan cara menambahkan pemformat tambahan.

Tindakan pengontrol dapat mengembalikan POCO (Objek CLR Lama Biasa). Saat POCO dikembalikan, runtime secara otomatis membuat yang ObjectResult membungkus objek. Klien mendapatkan objek serial yang diformat. Jika objek yang dikembalikan adalah null, 204 No Content respons dikembalikan.

Contoh berikut mengembalikan jenis objek:

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

Dalam kode sebelumnya, permintaan untuk item todo yang valid mengembalikan 200 OK respons. Permintaan untuk item todo yang tidak valid mengembalikan 204 No Content respons.

Header Terima

Negosiasi konten terjadi ketika Accept header muncul dalam permintaan. Saat permintaan berisi header terima, ASP.NET Core:

• Menghitung jenis media di header terima dalam urutan preferensi.
• Mencoba menemukan formatter yang dapat menghasilkan respons dalam salah satu format yang ditentukan.

Jika tidak ada pemformat yang dapat memenuhi permintaan klien, ASP.NET Core:

• Mengembalikan 406 Not Acceptable jika MvcOptions.ReturnHttpNotAcceptable diatur ke true, atau -
• Mencoba menemukan formatter pertama yang dapat menghasilkan respons.

Jika tidak ada formatter yang dikonfigurasi untuk format yang diminta, formatter pertama yang dapat memformat objek digunakan. Jika tidak ada Accept header yang muncul dalam permintaan:

• Formatter pertama yang dapat menangani objek digunakan untuk menserialisasikan respons.
• Tidak ada negosiasi yang terjadi. Server menentukan format apa yang akan dikembalikan.

Jika header Terima berisi */*, Header diabaikan kecuali RespectBrowserAcceptHeader diatur ke true pada MvcOptions.

Browser dan negosiasi konten

Tidak seperti klien API biasa, browser web menyediakan Accept header. Browser web menentukan banyak format, termasuk kartubebas. Secara default, ketika kerangka kerja mendeteksi bahwa permintaan berasal dari browser:

• Header Accept diabaikan.
• Konten dikembalikan dalam JSON, kecuali dikonfigurasi lain.

Pendekatan ini memberikan pengalaman yang lebih konsisten di seluruh browser saat menggunakan API.

Untuk mengonfigurasi aplikasi untuk menghormati header penerima browser, atur properti ke RespectBrowserAcceptHeader true:

var builder = WebApplication.CreateBuilder(args);

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

Mengonfigurasi pemformat

Aplikasi yang perlu mendukung format tambahan dapat menambahkan paket NuGet yang sesuai dan mengonfigurasi dukungan. Ada formatter terpisah untuk input dan output. Pemformat input digunakan oleh Pengikatan Model. Formatter output digunakan untuk memformat respons. Untuk informasi tentang membuat formatter kustom, lihat Pemformat Kustom.

Menambahkan dukungan format XML

Untuk mengonfigurasi formatter XML yang diimplementasikan menggunakan XmlSerializer, panggil AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

Saat menggunakan kode sebelumnya, metode pengontrol mengembalikan format yang sesuai berdasarkan header permintaan Accept .

Mengonfigurasi System.Text.Jsonformatter berbasis

Untuk mengonfigurasi fitur untuk System.Text.Jsonformatter berbasis, gunakan Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Kode yang disorot berikut mengonfigurasi pemformatan PascalCase alih-alih pemformatan camelCase default:

var builder = WebApplication.CreateBuilder(args);

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

Untuk mengonfigurasi opsi serialisasi output untuk tindakan tertentu, gunakan JsonResult. Contohnya:

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

Tambahkan Newtonsoft.Jsondukungan format JSON berbasis

Formatter JSON default menggunakan System.Text.Json. Untuk menggunakan Newtonsoft.Jsonformatter berbasis, instal Microsoft.AspNetCore.Mvc.NewtonsoftJson paket NuGet dan konfigurasikan di Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Dalam kode sebelumnya, panggilan untuk AddNewtonsoftJson mengonfigurasi fitur Web API, MVC, dan Razor Pages berikut untuk menggunakan Newtonsoft.Json:

• Formatter input dan output yang membaca dan menulis JSON
• JsonResult
• JSON Patch
• IJsonHelper
• TempData

Beberapa fitur mungkin tidak berfungsi dengan baik dengan System.Text.Jsonformatter berbasis dan memerlukan referensi ke Newtonsoft.Jsonformatter berbasis. Lanjutkan Newtonsoft.Jsonmenggunakan formatter berbasis saat aplikasi:

• Newtonsoft.Json Menggunakan atribut. Misalnya, [JsonProperty] atau [JsonIgnore].
• Menyesuaikan pengaturan serialisasi.
• Bergantung pada fitur yang Newtonsoft.Json menyediakan.

Untuk mengonfigurasi fitur untuk Newtonsoft.Jsonformatter berbasis, gunakan SerializerSettings:

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

Untuk mengonfigurasi opsi serialisasi output untuk tindakan tertentu, gunakan JsonResult. Contohnya:

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

Format ProblemDetails dan ValidationProblemDetails respons

Metode tindakan berikut memanggil ControllerBase.Problem untuk membuat ProblemDetails respons:

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

ProblemDetails Respons selalu camelCase, bahkan ketika aplikasi mengatur format ke PascalCase. ProblemDetailsmengikuti RFC 7807, yang menentukan huruf kecil.

[ApiController] Saat atribut diterapkan ke kelas pengontrol, pengontrol membuat ValidationProblemDetails respons saat Validasi Model gagal. Respons ini mencakup kamus yang menggunakan nama properti model sebagai kunci kesalahan, tidak berubah. Misalnya, model berikut menyertakan satu properti yang memerlukan validasi:

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

Secara default, ValidationProblemDetails respons yang dikembalikan ketika Value properti tidak valid menggunakan kunci Valuekesalahan , seperti yang ditunjukkan dalam contoh berikut:

{
  "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."
    ]
  }
}

Untuk memformat nama properti yang digunakan sebagai kunci kesalahan, tambahkan implementasi IMetadataDetailsProvider ke MvcOptions.ModelMetadataDetailsProviders koleksi. Contoh berikut menambahkan System.Text.Jsonimplementasi berbasis, SystemTextJsonValidationMetadataProvider, yang memformat nama properti sebagai camelCase secara default:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider juga menerima implementasi JsonNamingPolicy dalam konstruktornya, yang menentukan kebijakan penamaan kustom untuk memformat nama properti.

Untuk mengatur nama kustom untuk properti dalam model, gunakan atribut [JsonPropertyName] pada properti :

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

Respons ValidationProblemDetails yang dikembalikan untuk model sebelumnya ketika Value properti tidak valid menggunakan kunci sampleValuekesalahan , seperti yang ditunjukkan dalam contoh berikut:

{
  "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."
    ]
  }
}

Untuk memformat ValidationProblemDetails respons menggunakan Newtonsoft.Json, gunakan NewtonsoftJsonValidationMetadataProvider:

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

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

Secara default, NewtonsoftJsonValidationMetadataProvider memformat nama properti sebagai camelCase. NewtonsoftJsonValidationMetadataProvider juga menerima implementasi NamingPolicy dalam konstruktornya, yang menentukan kebijakan penamaan kustom untuk memformat nama properti. Untuk mengatur nama kustom untuk properti dalam model, gunakan [JsonProperty] atribut .

Tentukan format

Untuk membatasi format respons, terapkan [Produces] filter. Seperti kebanyakan Filter, [Produces] dapat diterapkan pada tindakan, pengontrol, atau cakupan global:

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

Filter sebelumnya [Produces] :

• Memaksa semua tindakan dalam pengontrol untuk mengembalikan respons berformat JSON untuk POCO (Objek CLR Lama Biasa) atau ObjectResult dan jenis turunannya.
• Mengembalikan respons berformat JSON meskipun formatter lain dikonfigurasi dan klien menentukan format yang berbeda.

Untuk informasi selengkapnya, lihat Filter.

Pemformat kasus khusus

Beberapa kasus khusus diimplementasikan menggunakan formatter bawaan. Secara default, string jenis pengembalian diformat sebagai teks/biasa (teks/html jika diminta melalui Accept header). Perilaku ini dapat dihapus dengan menghapus StringOutputFormatter. Formatter dihapus di Program.cs. Tindakan yang memiliki jenis 204 No Content pengembalian objek model saat mengembalikan null. Perilaku ini dapat dihapus dengan menghapus HttpNoContentOutputFormatter. Kode berikut menghapus StringOutputFormatter dan HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

StringOutputFormatterTanpa format formatter JSON bawaan string mengembalikan jenis. Jika formatter JSON bawaan dihapus dan formatter XML tersedia, format string format XML mengembalikan jenis. Jika tidak, string kembalikan jenis mengembalikan 406 Not Acceptable.

HttpNoContentOutputFormatterTanpa objek , null diformat menggunakan formatter yang dikonfigurasi. Contohnya:

• Formatter JSON mengembalikan respons dengan isi null.
• Formatter XML mengembalikan elemen XML kosong dengan set atribut xsi:nil="true" .

Pemetaan URL format respons

Klien dapat meminta format tertentu sebagai bagian dari URL, misalnya:

• Dalam string kueri atau bagian dari jalur.
• Dengan menggunakan ekstensi file khusus format seperti .xml atau .json.

Pemetaan dari jalur permintaan harus ditentukan dalam rute yang digunakan API. Contohnya:

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

Rute sebelumnya memungkinkan format yang diminta ditentukan menggunakan ekstensi file opsional. Atribut [FormatFilter] memeriksa keberadaan nilai format dalam RouteData dan memetakan format respons ke format yang sesuai saat respons dibuat.

Rute	Formatter
/api/todoitems/5	Pemformat output default
/api/todoitems/5.json	Formatter JSON (jika dikonfigurasi)
/api/todoitems/5.xml	Formatter XML (jika dikonfigurasi)

Deserialisasi polimorfik

Fitur bawaan menyediakan berbagai serialisasi polimorfik terbatas tetapi tidak ada dukungan untuk deserialisasi sama sekali. Deserialisasi memerlukan pengonversi kustom. Lihat Deserialisasi polimorfik untuk sampel lengkap deserialisasi polimorfik.

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)