本文首發於《嘗新體驗ASP.NET Core 6預覽版本中釋出的最小Web API(minimal APIS)新特性》
概述
.NET開發者們大家好，我是Rector。
幾天前(美國時間2021年8月10日)，微軟官方釋出了.NET 6的第7個預覽版，其中包含了很多新的特性和功能，比如：
- 優化最小Web API(minimal APIS)模板
- 為生成常用HTTP響應添加了IResult的介面實現
- 最小操作支援Request,Response等
- 優化了最小主機、模板
- 從查詢字串中獲取Blazor元件引數
- ...
本文我們主要來體驗最小Web API的功能和特性。最小Web API的目的主要是幫助C#(或者F#)後端開發者快速建立微服務專案或者HTTP API服務。
與之前的ASP.NET Core Web API相比，最小Web API在啟動模板和框架結構上都有些不同。最小Web API的模板相當簡潔，你幾需要寫4行程式碼便可完成一個最小Web API專案的搭建。
下面我們從頭開始建立一個最小Web API專案並體驗。
準備工作
在開始建立最小Web API之前，請確保開發環境中已安裝了.NET SDK 6.0.100-preview.7.21379.14(當前最新的.NET SDK版本)，在Windows作業系統中，你可以使用.NET Cli命令來檢視，比如：
dotnet --info
執行結果如下圖：
如果需要檢視當前環境已安裝的.NET模板，執行如下命令：
dotnet new -l
執行結果如下：
Template Name Short Name Language Tags
-------------------------------------------- ------------------- ---------- --------------------------
ASP.NET Core Empty web [C#],F# Web/Empty
ASP.NET Core gRPC Service grpc [C#] Web/gRPC
ASP.NET Core Web API webapi [C#],F# Web/WebAPI
ASP.NET Core Web App razor,webapp [C#] Web/MVC/Razor Pages
ASP.NET Core Web App (Model-View-Controller) mvc [C#],F# Web/MVC
ASP.NET Core with Angular angular [C#] Web/MVC/SPA
ASP.NET Core with React.js react [C#] Web/MVC/SPA
ASP.NET Core with React.js and Redux reactredux [C#] Web/MVC/SPA
Blazor Server App blazorserver [C#] Web/Blazor
Blazor WebAssembly App blazorwasm [C#] Web/Blazor/WebAssembly/PWA
Class Library classlib [C#],F#,VB Common/Library
Console Application console [C#],F#,VB Common/Console
dotnet gitignore file gitignore Config
Dotnet local tool manifest file tool-manifest Config
global.json file globaljson Config
MSTest Test Project mstest [C#],F#,VB Test/MSTest
MVC ViewImports viewimports [C#] Web/ASP.NET
MVC ViewStart viewstart [C#] Web/ASP.NET
NuGet Config nugetconfig Config
NUnit 3 Test Item nunit-test [C#],F#,VB Test/NUnit
NUnit 3 Test Project nunit [C#],F#,VB Test/NUnit
Protocol Buffer File proto Web/gRPC
Razor Class Library razorclasslib [C#] Web/Razor/Library
Razor Component razorcomponent [C#] Web/ASP.NET
Razor Page page [C#] Web/ASP.NET
Solution File sln Solution
Web Config webconfig Config
Windows Forms App winforms [C#],VB Common/WinForms
Windows Forms Class Library winformslib [C#],VB Common/WinForms
Windows Forms Control Library winformscontrollib [C#],VB Common/WinForms
Worker Service worker [C#],F# Common/Worker/Web
WPF Application wpf [C#],VB Common/WPF
WPF Class library wpflib [C#],VB Common/WPF
WPF Custom Control Library wpfcustomcontrollib [C#],VB Common/WPF
WPF User Control Library wpfusercontrollib [C#],VB Common/WPF
xUnit Test Project xunit [C#],F#,VB Test/xUnit
建立最小API程式專案
在.NET Core中建立程式的方式有多種，可以使用命令列工具執行dotnet new <模板名稱> <專案名稱>建立，也可以使用IDE(如：Visual Studio, Rider, VS Code)來建立。
使用命令列工具建立最小API專案
在本地磁碟建立一個儲存專案的目錄，假如路徑為D:\Project\tmp\MinimalApi，開啟命令列工具並進入此目錄，在當前目錄下執行如下命令：
dotnet new web MinApi
執行結果如下圖
生成的專案資料夾和檔案如下圖
至此，以命令列方式建立最小API專案即完成。
使用Visual Studio建立最小API專案
使用Visual Studio建立最小API專案，請確保已安裝Visual Studio 2022 17.0.0 Preview 3.0(當前最新版本)。
依次開啟Visual Studio 2022的【Start Window】->【Create a new project】視窗，在右側的已安裝模板列表中選擇【ASP.NET Core Empty】專案模板，之後點選[Next]按鈕，如圖：
在彈出的【Configure your new project】中，完善Project name(專案名稱)，Location(位置)，Solution name(解決方案名稱)等資訊，然後點選[Next]按鈕，如圖：
在彈出的【Additional Information】視窗中，Framework的版本選擇[.NET 6.0(Preview)]，然後點選[Next]按鈕，以完成最小API專案的建立，如圖：
最小API解析
在IDE中開啟剛才建立的MinimalApi，並在程式碼編輯器中開啟Program.cs檔案，如下：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.MapGet("/", () => "Hello World!");
app.Run();
可以看到，最小API專案的程式碼非常簡潔，如果去掉其中的異常處理程式碼，就還剩4行程式碼了，如下：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
為了不啟用https，我們修改一下位於Properties目錄中的launchSettings.json配置檔案，修改後如下：
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:2200",
"sslPort": 0
}
},
"profiles": {
"MinimalApi": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "http://localhost:2200",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
然後啟用專案，看是否能正常執行起來。在Visual Studio 2022中，按F5執行，如果在瀏覽中開啟並顯示如下頁面，說明最小API專案執行正常，如圖：
在最小API專案中，直接呼叫WebApplication.MapGet()方法即可完成路由的註冊和對映，如新增一個error的路由：
app.MapGet("/error", () => Results.Problem("錯誤",statusCode:500));
執行結果如圖：
WebApplication例項提供了很多路由對映的方法，比如HTTP請求協議：MapGet(),MapPost(),MapDelete(),MapPut()等等。
與以往的ASP.NET Core應用程式相同，在最小API專案中，你仍然可以使用像Swagger這樣的介面文件元件。
首先，在Nuget包管理工具中搜索Swashbuckle，然後安裝Swashbuckle.AspNetCore元件，如圖：
然後註冊Swagger的服務和路由，完整的示例如下：
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
/// <summary>
/// 新增Swagger
/// </summary>
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Api", Version = "v1" });
});
/// <summary>
/// 註冊API發現功能
/// </summary>
builder.Services.AddEndpointsApiExplorer();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.MapGet("/", () => "Hello World!");
/// <summary>
/// 丟擲異常測試
/// </summary>
app.MapGet("/throw", () => { throw new Exception("Exception occured"); });
/// <summary>
/// 錯誤頁面示例
/// </summary>
app.MapGet("/error", () => Results.Problem("錯誤",statusCode:500));
/// <summary>
/// 註冊Swagger的路由
/// </summary>
app.UseSwagger();
/// <summary>
/// 註冊Swagger UI的路由
/// </summary>
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Api v1"));
app.Run();
執行後的Swagger介面如圖：
在最小API應用程式中，我們同樣也可以返回實體物件，比如：註冊一個/customer的路由，然後返回一個Customer的例項模型，如下：
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
/// <summary>
/// 新增Swagger
/// </summary>
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Api", Version = "v1" });
});
/// <summary>
/// 註冊API發現功能
/// </summary>
builder.Services.AddEndpointsApiExplorer();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.MapGet("/", () => "Hello World!");
/// <summary>
/// 丟擲異常測試
/// </summary>
app.MapGet("/throw", () => { throw new Exception("Exception occured"); });
/// <summary>
/// 錯誤頁面示例
/// </summary>
app.MapGet("/error", () => Results.Problem("錯誤",statusCode:500));
/// <summary>
/// 返回客戶實體模型
/// </summary>
app.MapGet("/customer", () => new Customer("Rector", "Liu"));
/// <summary>
/// 註冊Swagger的路由
/// </summary>
app.UseSwagger();
/// <summary>
/// 註冊Swagger UI的路由
/// </summary>
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Api v1"));
app.Run();
/// <summary>
/// 客戶實體
/// </summary>
/// <param name="FirstName"></param>
/// <param name="LastName"></param>
public record Customer(string FirstName, string LastName);
執行結果如圖：
好了，本文對最小Web API的體驗到此。碼友網將在後續的文章中為大家分享的關於最小Web API的其他功能和特性，敬請關注。