ASP.NET Core Program.cs

郎道發表於 2025-7-3 16:35:00

<h3 id="net-8-中-programcs-的标准结构详解">.NET 8 中 <code>Program.cs</code> 的标准结构详解</h3>
一个典型的 .NET 8 Web 应用 <code>Program.cs</code> 看起来像这样：
<pre><code class="language-csharp">// .NET 8 Program.cs - Minimal API 风格
var builder = WebApplication.CreateBuilder(args);

// 1. 配置服务 (依赖注入 DI Container)
// --------------------------------
builder.Services.AddControllers(); // 添加 MVC 控制器服务（如果使用）
builder.Services.AddEndpointsApiExplorer(); // 添加 API Explorer 服务（通常用于 Swagger）
builder.Services.AddSwaggerGen(); // 添加 Swagger 生成器服务
builder.Services.AddScoped<IMyService, MyService>(); // 注册自定义服务
// ... 其他服务注册 (数据库上下文、身份认证、授权、缓存等)

// 2. 构建应用程序实例
// --------------------------------
var app = builder.Build();

// 3. 配置中间件管道 (HTTP Request Pipeline)
// --------------------------------
if (app.Environment.IsDevelopment())
{
app.UseSwagger(); // 开发环境：提供 Swagger JSON 端点
app.UseSwaggerUI(); // 开发环境：提供 Swagger UI 界面
}

app.UseHttpsRedirection(); // 将 HTTP 请求重定向到 HTTPS
app.UseAuthorization(); // 启用授权中间件
// app.UseAuthentication(); // 如果需要认证，通常放在 UseAuthorization 前面
// app.UseStaticFiles(); // 启用静态文件服务
// app.UseRouting(); // 在 Minimal API 中通常隐式包含，显式调用也可

// 4. 配置端点 (路由)
// --------------------------------
// 方式 A: 使用 Minimal API 直接定义端点
app.MapGet("/", () => "Hello World from Minimal API!"); // GET /
app.MapGet("/api/users", (IMyService service) => service.GetUsers()); // GET /api/users，演示依赖注入
app.MapPost("/api/users", (User user) => Results.Created($"/api/users/{user.Id}", user)); // POST /api/users

// 方式 B: 使用控制器 (如果添加了 AddControllers)
app.MapControllers(); // 映射所有用和等属性标记的控制器

// 5. 运行应用程序
// --------------------------------
app.Run(); // 启动应用程序并开始监听请求
</code></pre>
<h3 id="关键组成部分详解">关键组成部分详解</h3>
<ol>
<li>
<code>var builder = WebApplication.CreateBuilder(args);</code>
<ul>
<li>这是入口点。它创建了一个 <code>WebApplicationBuilder</code> 实例。</li>
<li><code>args</code> 接收命令行参数。</li>
<li><code>builder</code> 对象是配置的起点，它提供了：
<ul>
<li><code>Configuration</code>：访问 <code>appsettings.json</code>、环境变量、命令行参数等配置源。</li>
<li><code>Services</code> (<code>IServiceCollection</code>)：用于注册应用程序所需的所有服务（依赖注入）。这是替代传统 <code>Startup.ConfigureServices</code> 的地方。</li>
<li><code>Logging</code>：配置日志记录提供程序。</li>
<li><code>Host</code> / <code>WebHost</code>：配置主机设置（较少需要手动配置）。</li>
</ul>
</li>
</ul>
</li>
<li>
服务注册 (<code>builder.Services.AddXxx()</code>)
<ul>
<li>使用 <code>builder.Services</code> 这个 <code>IServiceCollection</code> 来添加应用程序所需的服务。</li>
<li>常见的服务注册方法：
<ul>
<li><code>AddControllers()</code> / <code>AddControllersWithViews()</code>：注册 MVC 控制器服务（如果你选择使用 Controller 而不是纯 Minimal API 端点）。</li>
<li><code>AddEndpointsApiExplorer()</code>：为 Minimal API 或 Web API 添加 API 描述服务，是 Swagger/OpenAPI 的基础。</li>
<li><code>AddSwaggerGen()</code>：注册 Swagger 生成器，用于生成 OpenAPI 文档。</li>
<li><code>AddDbContext<MyDbContext>()</code>：注册 Entity Framework Core 数据库上下文。</li>
<li><code>AddIdentity<IdentityUser, IdentityRole>()</code>：注册 ASP.NET Core Identity 服务。</li>
<li><code>AddAuthentication()</code> / <code>AddJwtBearer()</code>：注册认证服务。</li>
<li><code>AddAuthorization()</code>：注册授权服务（通常与认证一起使用）。</li>
<li><code>AddScoped<TService, TImplementation>()</code> / <code>AddTransient<...></code> / <code>AddSingleton<...></code>：注册自定义服务，指定生命周期。</li>
</ul>
</li>
<li>所有依赖注入容器的配置都在这里完成。</li>
</ul>
</li>
<li>
<code>var app = builder.Build();</code>
<ul>
<li>在完成所有服务注册后，调用 <code>Build()</code> 方法。</li>
<li>这个方法根据之前的配置构建出实际的 <code>WebApplication</code> 实例 (<code>app</code>)。</li>
<li><code>app</code> 对象代表你的应用程序本身，用于配置中间件管道和路由。这是替代传统 <code>Startup.Configure</code> 的地方。</li>
</ul>
</li>
<li>
配置中间件管道 (<code>app.UseXxx()</code>)
<ul>
<li>中间件是处理 HTTP 请求和响应的组件，按添加到管道的顺序执行。</li>
<li>使用 <code>app.UseXxx()</code> 方法将中间件添加到管道中。</li>
<li>顺序至关重要！ 中间件按照添加的顺序执行。例如：
<ul>
<li>异常处理 (<code>UseExceptionHandler</code>) 通常应放在最前面，以便捕获后续中间件的所有异常。</li>
<li>HTTPS 重定向 (<code>UseHttpsRedirection</code>) 应在处理敏感数据（如认证、静态文件）之前。</li>
<li>静态文件 (<code>UseStaticFiles</code>) 通常放在认证之前，因为像图片、CSS 这些静态文件通常不需要认证。</li>
<li>路由 (<code>UseRouting</code>)：在 Minimal API 中，<code>MapXxx</code> 方法内部通常会处理路由，显式调用 <code>UseRouting()</code> 是可选的，但有时为了明确位置会加上。它负责将请求匹配到端点。</li>
<li>认证 (<code>UseAuthentication</code>)：必须在授权 (<code>UseAuthorization</code>) 之前调用，用于识别用户身份。</li>
<li>授权 (<code>UseAuthorization</code>)：根据认证结果和策略决定用户是否有权访问资源。</li>
<li>端点 (<code>UseEndpoints</code>)：在传统 MVC 中显式使用，在 Minimal API 中被 <code>MapXxx</code> 方法替代。</li>
</ul>
</li>
<li>环境判断 (<code>if (app.Environment.IsDevelopment())</code>) 常用于只在开发环境启用的中间件，如 Swagger UI、详细的错误页面。</li>
</ul>
</li>
<li>
配置端点 (<code>app.MapXxx()</code>)
<ul>
<li>这是定义应用程序如何响应特定 URL 和 HTTP 方法（GET, POST, PUT, DELETE 等）的地方。</li>
<li>Minimal API 方式： 使用 <code>MapGet()</code>, <code>MapPost()</code>, <code>MapPut()</code>, <code>MapDelete()</code>, <code>MapMethods()</code> 等方法直接在 <code>Program.cs</code> 中定义端点及其处理程序（通常是 Lambda 表达式或方法）。处理程序可以：
<ul>
<li>直接返回结果（字符串、JSON 对象、<code>IResult</code> 如 <code>Results.Ok()</code>, <code>Results.NotFound()</code>, <code>Results.Created()</code>）。</li>
<li>通过参数注入依赖的服务（由 DI 容器自动提供）。</li>
<li>访问 <code>HttpContext</code>。</li>
<li>使用模型绑定从请求体、查询字符串、路由数据等获取参数。</li>
</ul>
</li>
<li>控制器方式： 如果之前调用了 <code>AddControllers()</code>，则可以使用 <code>app.MapControllers()</code> 来映射所有遵循 MVC 模式的控制器类（使用 <code></code>, <code></code>, <code></code> 等属性）。这种方式更适合大型或复杂 API 的组织。</li>
</ul>
</li>
<li>
<code>app.Run();</code>
<ul>
<li>这是应用程序的终点。调用 <code>Run()</code> 方法会启动 Kestrel 服务器（或其他配置的主机），开始监听传入的 HTTP 请求。</li>
<li>应用程序会一直运行，直到被关闭（Ctrl+C 或系统信号）。</li>
</ul>
</li>
</ol>

</div>
<div id="MySignature" role="contentinfo">
本文来自博客园，作者：Y00，转载请注明原文链接：https://www.cnblogs.com/ayic/p/18963909
聊聊技术，聊聊人生。欢迎关注我的公众号！^_^
<img src="https://images.cnblogs.com/cnblogs_com/ayic/2228020/o_221015170948_qr_code_search.png" style="display:none;" /> 
来源：https://www.cnblogs.com/ayic/p/18963909

頁: [1]

琼殿技术论坛's Archiver

ASP.NET Core Program.cs