ASP.NET Core 的 WebApplication 类

郑子铭

发布于 2025-06-11 08:31:30

8700

代码可运行

文章被收录于专栏：DotNet NB && CloudNativeDotNet NB && CloudNative

运行总次数：0

代码可运行

ASP.NET Core 提供了 3 个主机类（Host）。这些类用于配置应用、管理生命周期和启动 Web 服务。

• WebApplication：ASP.NET Core 6 引入的新 Host 类。它适合 Web 应用或 Web API。
• Host：适合非 Web 类型的应用。比如控制台应用或后台服务。
• WebHost：ASP.NET Core 6 之前使用的 Host 类。现在不推荐使用。

本文重点介绍 WebApplication 类的功能和用法。

一、WebApplication 类的功能详解

1.1 创建应用程序：CreateBuilder 与 Create 方法

WebApplication 提供两个静态方法来创建应用实例。

`CreateBuilder()`

这个方法返回一个 WebApplicationBuilder 对象。它支持链式调用添加服务和中间件。最后通过 Build() 方法生成 WebApplication 实例。

var builder = WebApplication.CreateBuilder(args);

// 添加控制器支持
builder.Services.AddControllers();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

`Create()`

这个方法直接生成一个 WebApplication 实例。默认已经配置了一些中间件。

var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run();

⚠️ 注意：Create() 没有 CreateBuilder() 灵活。建议在简单场景中使用。

1.2 启动方式：Run、RunAsync 与 StartAsync

WebApplication 提供三种方式启动应用。每种适合不同场景。

方法	描述
Run()	阻塞当前线程，直到 Host 关闭。常用于主函数中启动服务。
RunAsync()	异步启动 Host，直到触发取消令牌或关闭信号。
StartAsync()	异步启动 Host，启动成功后立即返回。HTTP Server 开始接收请求。

await app.RunAsync(); // 异步启动并等待退出

二、常用扩展方法分类

下面是 WebApplication 常用的扩展方法。按功能分组说明。

2.1 中间件相关

方法	说明
UseRequestLocalization()	根据客户端请求设置语言环境。
UseAuthentication()	启用身份验证。
UseAuthorization()	启用权限验证（要放在 UseRouting() 和 UseEndpoints() 之间）。
UseStaticFiles()	启用静态文件支持。
UseDeveloperExceptionPage()	在开发环境下显示异常页面。
UseHttpsRedirection()	把 HTTP 请求重定向到 HTTPS。
UseSession()	启用会话功能。
UseWebSockets()	启用 WebSocket 支持。
UseMiddleware<T>()	使用自定义中间件。

2.2 路由相关

方法	说明
UseRouting()	启用路由匹配机制。
UseEndpoints()	定义端点映射规则。
MapGet/Post/Put/Delete()	映射特定 HTTP 方法的请求。
MapControllers()	自动映射控制器中的路由。
MapFallbackToController()	当没有匹配时，回退到指定控制器。

2.3 文件与目录相关

方法	说明
UseDefaultFiles()	启用默认首页文件（如 index.html）。
UseDirectoryBrowser()	启用目录浏览功能。
UseFileServer()	启用静态文件和默认文件功能。

2.4 性能与优化

方法	说明
UseResponseCaching()	启用响应缓存。
UseResponseCompression()	启用响应压缩。
UseRateLimiter()	控制请求频率。
UseConcurrencyLimiter()	控制并发请求数量。

2.5 安全相关

方法	说明
UseHsts()	启用 HSTS（HTTPS 安全策略）。
UseCors()	启用跨域资源共享。
UseCookiePolicy()	启用 Cookie 使用策略。

三、关键属性说明

WebApplication 提供多个重要属性。可用于访问运行时信息和做高级控制。

属性	说明
Configuration	获取应用的配置（如 appsettings.json）。
Environment	获取当前运行环境（如 Development / Production）。
Lifetime	管理应用的生命周期事件。
LoggerFactory	获取日志工厂，用于记录日志。
Services	获取依赖注入容器。
Urls	获取或设置监听地址（如 http://localhost:5000）。

app.Urls.Clear();
//设置监听地址
app.Urls.Add("http://*:8080");

四、依赖注入与 Services 注册

通过 WebApplicationBuilder.Services 可注册服务。支持多种生命周期模式（Singleton、Scoped、Transient）。

var builder = WebApplication.CreateBuilder(args);

// 添加内存缓存
builder.Services.AddMemoryCache();

// 添加 Scoped 生命周期的服务
builder.Services.AddScoped<ITodoRepository, TodoRepository>();

// 添加 Singleton 生命周期的服务
builder.Services.AddSingleton<ILoggerService, ConsoleLoggerService>();

var app = builder.Build();