ASP.NET Core是微软推出的跨平台Web框架，它不再依赖IIS即可独立运行，开发者用C#就能写出轻量服务。构建第一个应用前，只需安装对应版本的.NET SDK，然后通过命令行或Visual Studio创建空项目即可进入编码阶段。
一、创建项目与理解基础结构
使用命令行工具执行 dotnet new web -o MyFirstApp 会生成一个最简Web项目。该命令创建的文件夹中包含 Program.cs 与项目文件 MyFirstApp.csproj。Program.cs 是应用入口，所有服务注册和请求管道配置都集中在这里，这和传统ASP.NET的分散配置有很大区别。
打开 Program.cs 你会看到顶层语句写法，没有显式的 Main 方法。编译器会自动将其包装为程序入口。这种简洁结构降低了初学者的认知负担，但也要求你理解每一行代码在主机启动过程中的作用，例如 WebApplication.CreateBuilder 负责读取配置并准备依赖注入容器。
1.1 项目文件说明
csproj 文件中定义了目标框架与隐式引用。默认情况下，SDK风格的项目会自动引入ASP.NET Core核心包，无需手动添加大量dll。你可以通过修改 TargetFramework 节点切换版本，例如从 net8.0 改为 net6.0，但需注意API兼容性。
另一个重要文件是 appsettings.json，它用于存放数据库连接、日志级别等配置。在Program中可通过 builder.Configuration 读取，这比旧版Web.config的强类型绑定更灵活，也更容易在容器环境中用环境变量覆盖。
二、编写最小API响应
最小API是ASP.NET Core近年引入的特性，允许不定义Controller类就直接映射路由。下面代码展示如何在Program里添加一个返回文本的接口，它适合快速验证服务是否启动成功。
// 创建Web应用构建器
var builder = WebApplication.CreateBuilder(args);
// 注册服务到依赖注入容器，此处暂未添加额外服务
builder.Services.AddSingleton<string>("hello from di");
// 构建应用实例
var app = builder.Build();
// 映射GET请求，访问根路径返回文本
app.MapGet("/", () => "Hello ASP.NET Core");
// 映射带参数的路由
app.MapGet("/name/{name}", (string name) => $"Hi {name}");
// 启动监听
app.Run();
上述代码中，app.MapGet 将HTTP GET请求绑定到匿名方法。当浏览器访问根地址，就会收到纯文本响应。这种方式省去了路由特性和控制器基类的样板代码，非常适合演示第一个应用的运行原理。
如果你需要读取前面注册的服务，可以把接口改为接收参数。例如将根路径改为 app.MapGet("/", (string msg) => msg) 并从DI容器解析，这样能直观看到依赖注入如何工作。注意匿名方法的参数由框架自动绑定，无需手动从Request取数。
2.1 常见启动错误与处理
新手常遇到端口被占用导致应用无法绑定。默认ASP.NET Core会监听5000和5001，若被其他程序使用，可在 appsettings.json 的Urls节点或环境变量ASPNETCORE_URLS中指定新端口，例如 http://localhost:5080。
另一个坑是忘记调用 app.Run() 或把映射写在 Build 之前。管道必须在Build之后配置，而Run会阻塞线程启动监听。若顺序颠倒，会得到空管道或编译期明确报错，按提示调整即可。
三、依赖注入与配置分离
ASP.NET Core内置依赖注入容器，所有服务都在 builder.Services 中注册，在请求处理时通过构造函数或委托参数解析。这样业务类不需自己new对象，便于单元测试和替换实现。
// 定义简单服务接口
public interface IGreeter
{
string Greet(string name);
}
// 实现类
public class Greeter : IGreeter
{
public string Greet(string name) => $"Welcome {name}";
}
// 在Program中注册
builder.Services.AddScoped<IGreeter, Greeter>();
// 在路由中使用
app.MapGet("/greet/{n}", (IGreeter g, string n) => g.Greet(n));
上面示例把问候逻辑封装为服务，并用作用域生命周期注册。每次HTTP请求会获得一个实例，请求结束即释放。相比单例，它更适合保留用户相关状态而又不想手动管理的场景。
配置也可以通过选项模式绑定到强类型类。例如把appsettings里的邮件设置映射为MailOptions，再用 AddOptions<MailOptions>().BindConfiguration("Mail") 注册，控制器里直接注入IOptions<MailOptions>读取，避免到处写字符串键名。
四、运行与验证
在项目目录执行 dotnet run 后，终端会输出监听地址。打开浏览器访问对应URL，若看到返回文本说明应用已正常工作。你也可以用curl命令在命令行测试接口，确认JSON或文本内容符合预期。
当第一个应用跑通后，下一步可引入MVC或Razor Pages写页面，或接入Entity Framework Core操作数据库。但核心的宿主模型、管道与依赖注入概念是一致的，掌握本文的最小结构能为后续扩展打下基础。
| 概念 | 所在位置 | 作用 |
|---|---|---|
| Builder | Program首行 | 收集配置与服务注册 |
| App | Build之后 | 定义请求管道与路由 |
| Run | 末尾 | 启动主机并阻塞 |
综上，ASP.NET Core构建第一个Web应用并不复杂，关键是理清Program中的三段式流程：创建构建器、注册与构建、映射和运行。避开端口与顺序误区，你就能在几分钟内拥有可访问的服务端点。
ASP.NET_CoreWeb应用依赖注入修改时间：2026-08-08 20:48:34