什麼是響應結果
響應結果就是,在客戶端向伺服器發出請求後,伺服器根據客戶端的請求引數,給出的結果,這就是一個完整的響應結果過程。響應的結果包含的內容非常多,主要的有 HTTP Status Code,Content-Type,Content 等等,在這裡不再一一贅述。
一般情況下,在 .NET MVC 中,如果是 API 介面,預設使用 JsonOutputFormatter 對結果進行格式化,但是也不排除某些情況下,我們需要對業務進行相容化的設定,比如部分介面使用 xml,部分介面使用自定義的格式,需求的響應是第一要務。
常見響應結果格式化器
在 .NET(介於官方改名,我們也不叫 Core 了哈) MVC中,有幾種內建的常見響應結果格式化器,他們分別是:
0、OutputFormatter(基類)
1、TextOutputFormatter(基類)
2、StringOutputFormatter
3、StreamOutputFormatter
4、JsonOutputFormatter
5、XmlSerializerOutputFormatter
由於這幾種常見的格式化器的存在,我們可以放心的在 .NET MVC 中使用 請求-> 響應 過程,而不必關心他具體的實現。
來自天氣預報的示例
預設的響應結果格式json
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private IEnumerable<WeatherForecast> GetWeatherForecast()
{
var rng = new Random();
return Enumerable.Range(1, 3).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-20, 55),
Summary = Summaries[rng.Next(Summaries.Length)]
})
.ToArray();
}
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
return GetWeatherForecast();
}
當我們請求上面的 API 介面,將得到下面的預設輸出結果。
[
{
"date": "2020-10-24T17:19:05.4638588+08:00",
"temperatureC": 2,
"temperatureF": 35,
"summary": "Cool"
},
{
"date": "2020-10-25T17:19:05.464602+08:00",
"temperatureC": 18,
"temperatureF": 64,
"summary": "Sweltering"
},
{
"date": "2020-10-26T17:19:05.4646057+08:00",
"temperatureC": -14,
"temperatureF": 7,
"summary": "Mild"
}
]
這很好,是我們想要的結果。
Xml響應結果格式器
在上面的天氣預報示例中,API介面預設使用了 json 格式輸出響應結果,在不改動業務程式碼的情況下,我們可以增加一種 xml 輸出結果,具體做法就是增加一個 API 介面,然後在 startup.cs 中新增 xml 格式化器。
[Produces("application/xml")]
[HttpGet("xml")]
public IEnumerable<WeatherForecast> Xml()
{
return GetWeatherForecast();
}
配置 Xml 格式器 XmlDataContractSerializerOutputFormatter
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers(configure =>
{
configure.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
});
}
這個時候再請求 API 地址:/weatherforecast/xml ,我們將會得到的結果如下
<ArrayOfWeatherForecast xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/CustomBinder">
<WeatherForecast>
<Date>2020-10-24T17:24:19.1047116+08:00</Date>
<Summary>Scorching</Summary>
<TemperatureC>49</TemperatureC>
</WeatherForecast>
<WeatherForecast>
<Date>2020-10-25T17:24:19.1047219+08:00</Date>
<Summary>Cool</Summary>
<TemperatureC>6</TemperatureC>
</WeatherForecast>
<WeatherForecast>
<Date>2020-10-26T17:24:19.1047221+08:00</Date>
<Summary>Freezing</Summary>
<TemperatureC>-20</TemperatureC>
</WeatherForecast>
</ArrayOfWeatherForecast>
細心的同學可能發現了問題。
API 介面 /xml 的特性標註多了一個 [Produces("application/xml")]正是得益於 ProducesAttribute 特性,我們可以在 MVC 框架內隨意的定製響應結果。
ProducesAttribute 和其它的特性類沒有太多的區別,其基本原理就是使用使用者指定的 contentType 引數(本例中為 application/xml) 到 OutputFormatters 中查詢對應型別的 Formatters,如果找到了,就使用該 Formatters 格式化響應結果,如果沒有找到,就丟擲 No output formatter was found for content types 的警告,同時,客戶端會收到一個 406(Not Acceptable) 的響應結果。
我想要更多-自定義格式化器
沒錯,上面的幾種常見的格式化器雖然非常好用。但是,我現在要對接一箇舊的第三方客戶端,該客戶端採用的是 url 引數請求協議包,很明顯,由於這個客戶端過於年長(假裝找不到維護人員),只能在伺服器端進行相容了。
不過也不用過於擔心,開發一個自定義的格式化器還是非常簡單的。我們只需要定義一個繼承自 TextOutputFormatter 的子類即可,其中有小部分需要編寫的程式碼。
需求
我們接到的需求是相容 url 方式的請求引數響應結果,經過調研,確認格式如下
key=value&key=value&key=value
需求調研清楚後,編碼的速度就得跟上了
定義格式化器 WeatherOutputFormatter
public class WeatherOutputFormatter : TextOutputFormatter
{
private readonly static Type WeatherForecastType = typeof(WeatherForecast);
public WeatherOutputFormatter()
{
SupportedEncodings.Add(Encoding.UTF8);
SupportedEncodings.Add(Encoding.Unicode);
SupportedMediaTypes.Add("text/weather");
}
public override bool CanWriteResult(OutputFormatterCanWriteContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (context.ObjectType == WeatherForecastType || context.Object is WeatherForecast || context.ObjectType.GenericTypeArguments[0] == WeatherForecastType)
{
return base.CanWriteResult(context);
}
return false;
}
private string WriterText(IEnumerable<WeatherForecast> weathers)
{
StringBuilder builder = new StringBuilder();
foreach (var wealther in weathers)
{
builder.Append(WriterText(wealther));
}
return builder.ToString();
}
private string WriterText(WeatherForecast weather) => $"date={WebUtility.UrlEncode(weather.Date.ToString())}&temperatureC={weather.TemperatureC}&temperatureF={weather.TemperatureF}&summary={WebUtility.UrlEncode(weather.Summary)}";
public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (selectedEncoding == null)
{
throw new ArgumentNullException(nameof(selectedEncoding));
}
string text = string.Empty;
if (context.ObjectType == WeatherForecastType)
text = WriterText(context.Object as WeatherForecast);
else if (context.ObjectType.GenericTypeArguments[0] == WeatherForecastType)
text = WriterText(context.Object as IEnumerable<WeatherForecast>);
if (string.IsNullOrEmpty(text))
{
await Task.CompletedTask;
}
var response = context.HttpContext.Response;
await response.WriteAsync(text, selectedEncoding);
}
}
正所謂一圖勝千言,所以我給大家畫了一張圖,方便理解
從圖中可以看出,我們只需要重寫兩個方法,同時編寫一個自定義格式化邏輯即可完成,看起來還是非常簡單的。
細心的同學可能發現了,在 WriterText 方法中,考慮到相容性的問題,我們還將 url 中的 value 進行轉義,可以說還是非常貼心的哈。
編寫測試方法
[Produces("text/weather")]
[HttpGet("weather")]
public IEnumerable<WeatherForecast> Weather()
{
return GetWeatherForecast();
}
測試方法中定義 Produces("text/weather"),指定需要的 ContentType,同時,還需要將 WeatherOutputFormatter 新增到 OutputFormatters 中使用
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers(configure =>
{
configure.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
configure.OutputFormatters.Add(new WeatherOutputFormatter());
});
}
呼叫介面進行測試
請求 API 地址 /weather,得到結果如下
date=2020%2F10%2F27+10%3A35%3A36&temperatureC=42&temperatureF=107&summary=Scorchingdate=2020%2F10%2F28+10%3A35%3A36&temperatureC=28&temperatureF=82&summary=Freezingdate=2020%2F10%2F29+10%3A35%3A36&temperatureC=17&temperatureF=62&summary=Sweltering
結束語
至此,自定義格式化器已經完成,本文通過一個簡單的示例實現,幫助大家理解如何在 MVC 中使用自定義格式化器,文章篇幅不長,做圖花了點心思,歡迎您的關注。
示例程式碼託管在:
https://github.com/lianggx/EasyAspNetCoreDemo/tree/master/CustomBinder