ASP.NET Core 指定Action的響應型別

1.格式化Ation輸出

Action方法可以返回指定的格式例而忽略客戶端請求格式，例如：使用JsonResult返回JSON格式的數據，ContentResult返回字串數據

如果返回的不是IActionResult型別，系統會使用合適的格式化器 IOutputFormatter格式化輸出的格式

預設情況下，內建的ControllerBase.Ok方法返回Json型別的格式：

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

上面程式碼非常簡單返回一個todo列表，我們使用F12在瀏覽器中可以看到如下：

響應頭包含Content-Type: application/json; charset=utf-8

使用 ContentResult和Content返回字串數據

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

我們看到返回的Content-Type是text/plain

2.內容協商

最常用的HTTP協商有2種方式：

伺服器驅動型內容協商（Server-driven negotiation） ：伺服器根據客戶端請求中的資訊，如Accept頭部欄位（表示客戶端可以接受的響應內容型別）、Accept-Language頭部欄位（表示客戶端首選的語言）、Accept-Encoding頭部欄位（表示客戶端支持的內容編碼方式）等，決定響應內容。伺服器會根據這些資訊選擇最適合的響應內容，並將其包含在響應中。

客戶端驅動型內容協商（Agent-driven negotiation） ：客戶端發送的請求中包含了資源的一些特定要求，例如透過使用Accept頭部欄位中指定特定的內容型別或者使用Quality Values（q值）來表明優先級。伺服器根據這些請求條件來選擇響應內容，然後返回最符合條件的內容。

內容協商發生在當客戶端指定一個 Accept header，在rfc9110(https://www.rfc-editor.org/rfc/rfc9110#field.accept)中，參與http內容協商有5個欄位，他們分別為：

ASP.NET Core預設使用JSON格式，ASP.NET Core中支持下列媒體型別：

當Action方法返回POCO(普通C#類)，執行時會自動建立一個ObjectResult物件類封裝這個POCO，客戶端會收到序列化之後的物件，如果沒有找到該物件將返回204 No Content

下列物件將返回一個POCO型別

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

當Accept出現在請求的Header中時則會發生內容協商，首先ASP.NET Core會按照順序列舉頭部Accept中的媒體型別，這個順序會根據Accept中指定Q值的權重來列舉，嘗試找到一個符合的格式化器來生成相應

3.配置格式化器

ASP.NET Core應用程式支持掛載額外的格式化器，輸入格式化器和輸出的格式化器通常是分開的，輸入的格式化器通常使用模型繫結，輸出格式化器通常用來格式化響應

3.1 XML格式化器支持

配置XML格式化器，使用XmlSerializer

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

3.2 配置基於System.Text.Json格式化器

使用下面程式碼配置基於System.Text.Json的格式化器：

builder.Services.AddControllers() .AddJsonOptions(options => { //JSON 序列化器將使用 .NET 物件的內容名作為 JSON 內容名，而不會進行任何額外的命名轉換 options.JsonSerializerOptions.PropertyNamingPolicy = null; });

3.3 配置基於Newtonsoft.Json格式化器

預設使用了System.Text.Json的JSON格式化，我們可以透過配置來使用Newtonsoft.Json格式化器，需要安裝如下包

Microsoft.AspNetCore.Mvc.NewtonsoftJson

配置如下：

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

Newtonsoft.Json比System.Text.Json提供了更多豐富的特性， System.Text.Json雖然沒有 Newtonsoft.Json提供的功能豐富，但是在效能方面更好，這個可以根據自己的需求來選擇

4. 指定返回特定的格式

我們可以使用[Produces] 過濾器來指定響應格式， [Produces]過濾器能夠使用在Action，Controller或Global級別

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

原始碼地址：

https://github.com/bingbing-gui/Asp.Net-Core-Skill/tree/master/Fundamentals/AspNetCore.APIControllers/AspNetCore.FormatResponseOutputData

參考文章：

https://learn.microsoft.com/en-us/aspnet/core/web-api/advanced/formatting?view=aspnetcore-8.0