这类教程最值得先看的不是它讲了多少个知识点而是能不能帮你从零开始把环境搭起来、项目跑起来最后能自己动手改出东西。对于想学ASP.NET Core的人来说最大的障碍往往不是语法而是第一步的环境配置、项目结构理解以及如何把学到的零散知识串成一个能跑的 Web 应用。我建议你先别急着找最全、最长的视频而是按这个顺序来确认环境能跑通 - 理解一个最小项目的骨架 - 动手增删改查 - 最后再考虑部署和扩展。下面我就按这个实际落地的路径把从入门到能独立开发需要的关键环节拆解一遍。1. 先搞定环境不是装完SDK就结束了很多人卡在第一步不是 SDK 没装上而是装完不知道下一步该干嘛或者创建项目时一堆选项看不懂。1.1 运行环境与工具选择你需要准备两样东西.NET SDK和一个代码编辑器或 IDE。.NET SDK这是核心。直接去微软官网下载最新长期支持LTS版本。对于新手我强烈建议就用 LTS 版别追最新。比如当前 .NET 8 是 LTS就先用它。安装过程一路下一步就行装完打开命令行CMD、PowerShell 或终端输入dotnet --version能显示出版本号就说明安装成功。开发工具Visual StudioWindows如果你是 Windows 用户并且不排斥大型 IDE这是最省心的选择。安装时记得勾选“ASP.NET 和 Web 开发”工作负载。它的优势是创建项目、调试、运行一键搞定对新手非常友好。Visual Studio Code跨平台轻量、免费、跨平台。你需要额外安装 C# 扩展。它的优势是灵活、启动快适合喜欢轻量工具或使用 macOS/Linux 的开发者。对于纯粹的学习VS Code 完全足够。Rider跨平台第三方商业 IDE体验很好但需要付费。新手可以不考虑。注意不要在两个工具间反复横跳。选定一个先用熟。我个人的建议是Windows 新手用 Visual StudiomacOS/Linux 用户或喜欢轻量化的用 VS Code。1.2 创建第一个能跑的项目环境好了立刻创建一个项目并运行它建立信心。如果你用 Visual Studio启动 Visual Studio点击“创建新项目”。在搜索框里输入“ASP.NET Core Web API”或者“ASP.NET Core Web 应用”选择C#语言对应的那个模板。对于入门我建议先选“Web API”模板因为它结构最清晰没有前端页面干扰能让你专注后端逻辑。给项目起个名字比如MyFirstApi选择好位置。在“其他信息”页面注意几个选项框架选择.NET 8.0 (长期支持)。身份验证类型选择“无”。先不要搞复杂的登录认证。配置 HTTPS勾选。现在默认都走 HTTPS这是好习惯。使用控制器勾选。这是最经典、最易理解的 MVC 模式。启用 OpenAPI 支持务必勾选。这会自动集成 Swagger一个可以通过网页查看和测试 API 的工具对学习帮助巨大。点击“创建”。项目生成后直接按F5或绿色三角按钮运行。如果你用 VS Code打开一个空文件夹作为你的工作区。打开集成终端Ctrl。输入命令创建项目dotnet new webapi -n MyFirstApi。这个命令会用 Web API 模板创建一个名为MyFirstApi的新项目。进入项目目录cd MyFirstApi。运行项目dotnet run。无论哪种方式成功后命令行都会输出一个本地地址通常是https://localhost:7171或http://localhost:5000。用浏览器打开它如果看到类似“无法访问此页面”是正常的因为根路径可能没定义。关键的一步来了在地址后面加上/swagger即打开https://localhost:7171/swagger。你应该能看到一个 Swagger UI 页面里面列出了模板自带的WeatherForecastAPI。点击GET /WeatherForecast旁边的 “Try it out” - “Execute”看到返回了一串 JSON 数据。恭喜你的第一个 ASP.NET Core 应用跑起来了这个“跑起来”的瞬间比看十小时视频都重要。它证明了你的环境是通的项目结构是有效的。2. 理解项目骨架知道文件都是干嘛的项目能跑了现在打开文件夹别被一堆文件吓到。我们只关注最核心的几个。2.1 核心目录与文件解析MyFirstApi/ ├── Properties/ │ └── launchSettings.json // **启动配置文件**。定义了不同启动环境IIS Express, Kestrel的端口、环境变量等。初期不用改。 ├── Controllers/ │ └── WeatherForecastController.cs // **控制器**。处理HTTP请求返回响应。这是你写业务逻辑的主要地方。 ├── Program.cs // **程序入口**。.NET 6之后所有配置都从这里开始。这是最重要的文件之一。 ├── appsettings.json // **应用配置文件**。存放数据库连接字符串、日志级别等配置。 └── MyFirstApi.csproj // **项目文件**。定义了项目依赖的NuGet包、目标框架等。Program.cs这是 ASP.NET Core 应用的“心脏”。打开它你会看到类似下面的代码var builder WebApplication.CreateBuilder(args); // 添加服务到容器依赖注入。 builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); var app builder.Build(); // 配置HTTP请求管道中间件。 if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();这段代码做了两件事builder部分var builder ...到var app builder.Build()叫服务配置。你把各种功能如控制器、Swagger、数据库上下文注册到这里系统后面才能用。app部分var app ...到app.Run()叫请求管道配置。HTTP请求像水流过管道每个app.UseXxx()就是一个“处理器”决定请求怎么被处理、响应怎么被返回。顺序很重要。WeatherForecastController.cs这是“控制器”。它里面的WeatherForecastController类继承自ControllerBase。类里面那个[HttpGet]标记的方法Get()就是处理GET /WeatherForecast请求的地方。你以后写的 API 接口大部分都是这样的控制器类和方法。appsettings.jsonJSON 格式的配置文件。你可以在这里放自己的配置比如{ Logging: { ... }, MySetting: Hello from config, // 自定义配置 ConnectionStrings: { DefaultConnection: Server(localdb)\\mssqllocaldb;DatabaseMyDb;Trusted_ConnectionTrue; } }在Program.cs里可以用builder.Configuration[MySetting]来读取。2.2 关键概念依赖注入DI与中间件Middleware这是 ASP.NET Core 的两个核心设计模式不理解它们代码会写得很别扭。依赖注入DI简单说就是“你需要什么我系统给你什么而不是你自己去new”。比如控制器里需要访问数据库你不需要在控制器里new MyDbContext()而是在Program.cs的builder.Services里注册这个MyDbContext然后在控制器的构造函数中声明需要它系统会自动给你一个实例。这样做的好处是解耦、易测试。怎么用在Program.cs里builder.Services.AddScopedIMyService, MyService();这样注册。在控制器构造函数里private readonly IMyService _service;这样声明。中间件Middleware就是Program.cs里app.UseXxx()那些组件。请求进来后按顺序经过一个个中间件每个中间件都可以对请求或响应做点事比如记录日志、验证权限、处理异常然后决定是继续往下传还是直接返回。app.Run()是管道的终点。顺序很重要比如错误处理中间件app.UseExceptionHandler()应该放在管道最前面这样才能捕获后面所有中间件的异常。而路由匹配中间件app.MapControllers()通常放在靠后的位置。对于入门你不需要立刻精通但要有这个意识配置服务在builder.Services里配置请求处理流程在app里。3. 动手实战从增删改查CRUD理解全流程看懂了骨架我们来真的。目标是做一个简单的“待办事项Todo”API支持创建、查看、更新、删除。3.1 第一步定义模型Model模型就是数据的形状。在项目根目录创建一个Models文件夹里面添加一个TodoItem.cs类。namespace MyFirstApi.Models; public class TodoItem { public int Id { get; set; } // 唯一标识 public string? Title { get; set; } // 任务标题 public bool IsComplete { get; set; } // 是否完成 public DateTime CreatedTime { get; set; } DateTime.Now; // 创建时间 }这就是一个简单的模型对应数据库里的一张表如果以后用数据库的话。3.2 第二步创建数据库上下文DbContext并注册我们先用内存数据库这样不需要安装 SQL Server最适合学习。首先通过 NuGet 安装 EF Core 内存数据库包。在 VS 里可以在项目上右键“管理 NuGet 程序包”搜索Microsoft.EntityFrameworkCore.InMemory并安装。在 VS Code 终端里进入项目目录运行dotnet add package Microsoft.EntityFrameworkCore.InMemory。在Models文件夹下创建TodoContext.csusing Microsoft.EntityFrameworkCore; namespace MyFirstApi.Models; public class TodoContext : DbContext { public TodoContext(DbContextOptionsTodoContext options) : base(options) { } public DbSetTodoItem TodoItems { get; set; } // 代表TodoItems表 }在Program.cs的builder.Services部分注册这个上下文// 添加数据库上下文使用内存数据库 builder.Services.AddDbContextTodoContext(opt opt.UseInMemoryDatabase(TodoList));3.3 第三步创建控制器Controller在Controllers文件夹上右键添加 - 控制器 - API控制器使用 Entity Framework 读写操作。选择模型类TodoItem数据上下文类TodoContext。或者你可以手动创建一个TodoItemsController.csusing Microsoft.AspNetCore.Mvc; using Microsoft.EntityFrameworkCore; using MyFirstApi.Models; namespace MyFirstApi.Controllers; [Route(api/[controller])] // 路由模板访问路径会是 /api/TodoItems [ApiController] public class TodoItemsController : ControllerBase { private readonly TodoContext _context; public TodoItemsController(TodoContext context) { _context context; } // GET: api/TodoItems [HttpGet] public async TaskActionResultIEnumerableTodoItem GetTodoItems() { return await _context.TodoItems.ToListAsync(); } // GET: api/TodoItems/5 [HttpGet({id})] public async TaskActionResultTodoItem GetTodoItem(int id) { var todoItem await _context.TodoItems.FindAsync(id); if (todoItem null) { return NotFound(); // 返回404 } return todoItem; } // PUT: api/TodoItems/5 [HttpPut({id})] public async TaskIActionResult PutTodoItem(int id, TodoItem todoItem) { if (id ! todoItem.Id) { return BadRequest(); // 返回400 } _context.Entry(todoItem).State EntityState.Modified; try { await _context.SaveChangesAsync(); } catch (DbUpdateConcurrencyException) { if (!TodoItemExists(id)) { return NotFound(); } else { throw; } } return NoContent(); // 返回204 } // POST: api/TodoItems [HttpPost] public async TaskActionResultTodoItem PostTodoItem(TodoItem todoItem) { _context.TodoItems.Add(todoItem); await _context.SaveChangesAsync(); // CreatedAtAction 返回201状态码并在响应头Location中给出新资源的URI return CreatedAtAction(nameof(GetTodoItem), new { id todoItem.Id }, todoItem); } // DELETE: api/TodoItems/5 [HttpDelete({id})] public async TaskIActionResult DeleteTodoItem(int id) { var todoItem await _context.TodoItems.FindAsync(id); if (todoItem null) { return NotFound(); } _context.TodoItems.Remove(todoItem); await _context.SaveChangesAsync(); return NoContent(); } private bool TodoItemExists(int id) { return _context.TodoItems.Any(e e.Id id); } }这个控制器包含了完整的 CRUD 操作。注意每个方法上的[HttpGet],[HttpPost]等属性它们定义了 HTTP 方法和路由。3.4 第四步测试你的 API重新运行项目 (dotnet run或F5)打开 Swagger 页面 (/swagger)。现在你应该能看到TodoItems相关的 API 了。POST /api/TodoItems点击“Try it out”在 Request body 里输入 JSON{ title: 学习 ASP.NET Core, isComplete: false }然后 Execute。成功后返回 201并且返回了带 Id 的 TodoItem。GET /api/TodoItems执行你会看到包含刚才创建的那条数据的数组。GET /api/TodoItems/{id}把上一步返回的 Id 填进去执行获取单条。PUT /api/TodoItems/{id}修改一条数据比如把isComplete改成true。DELETE /api/TodoItems/{id}删除一条数据。到这里你已经完成了一个完整的、有数据库交互的 Web API 后端。这个过程涵盖了模型定义、依赖注入注册、控制器编写、HTTP 方法处理、以及通过 Swagger 测试。这是最核心的闭环。4. 深入与扩展把项目变得更“像样”完成基础 CRUD 后你需要了解如何让项目更健壮、更易维护。4.1 使用仓储Repository模式直接在控制器里写_context.TodoItems...虽然能跑但不利于测试和复用。更常见的做法是引入一个“仓储层”来封装数据访问逻辑。创建一个Interfaces文件夹和Repositories文件夹。在Interfaces里创建ITodoRepository.csusing MyFirstApi.Models; namespace MyFirstApi.Interfaces; public interface ITodoRepository { TaskIEnumerableTodoItem GetAllAsync(); TaskTodoItem? GetByIdAsync(int id); TaskTodoItem AddAsync(TodoItem item); Task UpdateAsync(TodoItem item); Task DeleteAsync(int id); Taskbool ExistsAsync(int id); }在Repositories里创建TodoRepository.cs实现这个接口using Microsoft.EntityFrameworkCore; using MyFirstApi.Interfaces; using MyFirstApi.Models; namespace MyFirstApi.Repositories; public class TodoRepository : ITodoRepository { private readonly TodoContext _context; public TodoRepository(TodoContext context) _context context; public async TaskIEnumerableTodoItem GetAllAsync() await _context.TodoItems.ToListAsync(); public async TaskTodoItem? GetByIdAsync(int id) await _context.TodoItems.FindAsync(id); public async TaskTodoItem AddAsync(TodoItem item) { _context.TodoItems.Add(item); await _context.SaveChangesAsync(); return item; } // ... 实现其他方法 }在Program.cs注册这个仓储builder.Services.AddScopedITodoRepository, TodoRepository();修改TodoItemsController不再注入TodoContext而是注入ITodoRepository并在方法中调用仓储。这样做的好处是控制器不再关心数据怎么存是内存、SQL Server 还是别的只关心业务逻辑。测试时也可以轻松模拟Mock一个仓储。4.2 添加日志记录日志是排查问题的生命线。ASP.NET Core 内置了强大的日志系统。在Program.cs的builder部分之后var app builder.Build();之前你就可以获取到 Logger 并记录var builder WebApplication.CreateBuilder(args); // 配置服务... // 在构建app之前可以获取一个Logger var logger builder.Services.BuildServiceProvider().GetRequiredServiceILoggerProgram(); logger.LogInformation(应用程序正在启动...); var app builder.Build(); // 配置中间件...在控制器或其他类中通过构造函数注入ILoggerTodoItemsController来使用。在appsettings.json里可以配置日志级别控制台输出等。4.3 处理异常与返回统一格式目前 API 出错时返回的是框架默认的错误页面或状态码。为了给前端提供更友好的信息可以创建全局异常处理中间件和统一响应模型。创建Models/ApiResponse.csnamespace MyFirstApi.Models; public class ApiResponseT { public bool Success { get; set; } public string? Message { get; set; } public T? Data { get; set; } public static ApiResponseT Ok(T data, string? message null) new() { Success true, Data data, Message message }; public static ApiResponseT Fail(string message) new() { Success false, Message message }; }创建一个中间件Middleware/ExceptionHandlingMiddleware.cs来捕获全局异常并返回统一的ApiResponse。在Program.cs的请求管道中app.UseMiddlewareExceptionHandlingMiddleware();。这样无论成功还是失败前端收到的都是{ success: true/false, message: “...”, data: ... }这种格式便于处理。4.4 连接真实数据库以 SQL Server 为例内存数据库只用于学习。真实项目需要持久化存储。安装 NuGet 包Microsoft.EntityFrameworkCore.SqlServer。修改appsettings.json添加连接字符串ConnectionStrings: { DefaultConnection: Server(localdb)\\mssqllocaldb;DatabaseTodoDb;Trusted_ConnectionTrue;MultipleActiveResultSetstrue }这里用了 LocalDB是 Visual Studio 自带的轻量版 SQL Server适合开发。修改Program.cs中的服务注册替换内存数据库// 替换掉 UseInMemoryDatabase builder.Services.AddDbContextTodoContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection)));创建数据库迁移在终端项目目录下运行dotnet ef migrations add InitialCreate dotnet ef database update这会在你的 LocalDB 中创建一个名为TodoDb的数据库并生成TodoItems表。5. 部署准备与常见问题排查学到最后你得知道怎么把它放到服务器上跑起来。5.1 发布应用ASP.NET Core 应用可以发布为“框架依赖”或“独立”部署。框架依赖目标机器上需要安装对应版本的 .NET 运行时。发布命令dotnet publish -c Release -o ./publish。生成的文件较小。独立将 .NET 运行时一起打包生成一个独立的可执行文件。发布命令dotnet publish -c Release -r win-x64 --self-contained true -o ./publish以 Windows x64 为例。生成的文件较大但目标机器不需要装 .NET。发布后publish文件夹里的文件就是你需要部署到服务器如 IIS, Nginx, Docker 容器的内容。5.2 常见问题与排查顺序项目跑不起来报错“找不到 SDK”或“项目文件错误”先查命令行运行dotnet --version确认 SDK 已安装且版本匹配项目文件.csproj中的TargetFramework。再查在项目目录下运行dotnet restore还原 NuGet 包。最后查用dotnet build看编译错误。Swagger 页面能打开但调用 API 返回 404先查控制器类和方法上的路由属性[Route]、[HttpGet(“{id}”)]是否写对。注意大小写。再查Program.cs里是否调用了app.MapControllers()。最后查启动日志里有没有路由注册成功的消息。连接数据库失败先查appsettings.json里的连接字符串是否正确数据库服务器是否启动。再查是否执行了数据库迁移 (dotnet ef database update)。最后查在Program.cs的app部分开始处添加app.Services.CreateScope()来手动触发数据库连接看具体错误。修改了代码但刷新页面没变化先查是否保存了文件。VS Code 有时需要手动保存。再查.NET热重载是否生效。可以尝试停止 (CtrlC) 后重新dotnet run。最后查浏览器缓存。尝试强制刷新 (CtrlF5) 或使用无痕窗口。发布到服务器后无法运行先查服务器上是否安装了对应的 .NET 运行时如果是框架依赖部署或运行时版本是否匹配。再查应用池IIS或服务Systemd的启动账户是否有权限访问文件、网络和数据库。最后查服务器防火墙是否开放了应用监听的端口默认是 5000, 5001 或你在launchSettings.json/appsettings.json里配置的端口。学习 ASP.NET Core最关键的不是看完多少小时的视频而是按照“环境 - 项目骨架 - 核心概念DI、中间件- 完整CRUD实战 - 模式优化仓储、日志- 真实数据库 - 部署”这个路径自己动手把每个环节都敲一遍、跑通、并理解为什么这么做。遇到报错别怕那是最好的学习材料按照上面的排查顺序大部分问题都能自己解决。 ASP.NET Core 从零到一：环境搭建、项目实战与核心概念解析
这类教程最值得先看的不是它讲了多少个知识点而是能不能帮你从零开始把环境搭起来、项目跑起来最后能自己动手改出东西。对于想学ASP.NET Core的人来说最大的障碍往往不是语法而是第一步的环境配置、项目结构理解以及如何把学到的零散知识串成一个能跑的 Web 应用。我建议你先别急着找最全、最长的视频而是按这个顺序来确认环境能跑通 - 理解一个最小项目的骨架 - 动手增删改查 - 最后再考虑部署和扩展。下面我就按这个实际落地的路径把从入门到能独立开发需要的关键环节拆解一遍。1. 先搞定环境不是装完SDK就结束了很多人卡在第一步不是 SDK 没装上而是装完不知道下一步该干嘛或者创建项目时一堆选项看不懂。1.1 运行环境与工具选择你需要准备两样东西.NET SDK和一个代码编辑器或 IDE。.NET SDK这是核心。直接去微软官网下载最新长期支持LTS版本。对于新手我强烈建议就用 LTS 版别追最新。比如当前 .NET 8 是 LTS就先用它。安装过程一路下一步就行装完打开命令行CMD、PowerShell 或终端输入dotnet --version能显示出版本号就说明安装成功。开发工具Visual StudioWindows如果你是 Windows 用户并且不排斥大型 IDE这是最省心的选择。安装时记得勾选“ASP.NET 和 Web 开发”工作负载。它的优势是创建项目、调试、运行一键搞定对新手非常友好。Visual Studio Code跨平台轻量、免费、跨平台。你需要额外安装 C# 扩展。它的优势是灵活、启动快适合喜欢轻量工具或使用 macOS/Linux 的开发者。对于纯粹的学习VS Code 完全足够。Rider跨平台第三方商业 IDE体验很好但需要付费。新手可以不考虑。注意不要在两个工具间反复横跳。选定一个先用熟。我个人的建议是Windows 新手用 Visual StudiomacOS/Linux 用户或喜欢轻量化的用 VS Code。1.2 创建第一个能跑的项目环境好了立刻创建一个项目并运行它建立信心。如果你用 Visual Studio启动 Visual Studio点击“创建新项目”。在搜索框里输入“ASP.NET Core Web API”或者“ASP.NET Core Web 应用”选择C#语言对应的那个模板。对于入门我建议先选“Web API”模板因为它结构最清晰没有前端页面干扰能让你专注后端逻辑。给项目起个名字比如MyFirstApi选择好位置。在“其他信息”页面注意几个选项框架选择.NET 8.0 (长期支持)。身份验证类型选择“无”。先不要搞复杂的登录认证。配置 HTTPS勾选。现在默认都走 HTTPS这是好习惯。使用控制器勾选。这是最经典、最易理解的 MVC 模式。启用 OpenAPI 支持务必勾选。这会自动集成 Swagger一个可以通过网页查看和测试 API 的工具对学习帮助巨大。点击“创建”。项目生成后直接按F5或绿色三角按钮运行。如果你用 VS Code打开一个空文件夹作为你的工作区。打开集成终端Ctrl。输入命令创建项目dotnet new webapi -n MyFirstApi。这个命令会用 Web API 模板创建一个名为MyFirstApi的新项目。进入项目目录cd MyFirstApi。运行项目dotnet run。无论哪种方式成功后命令行都会输出一个本地地址通常是https://localhost:7171或http://localhost:5000。用浏览器打开它如果看到类似“无法访问此页面”是正常的因为根路径可能没定义。关键的一步来了在地址后面加上/swagger即打开https://localhost:7171/swagger。你应该能看到一个 Swagger UI 页面里面列出了模板自带的WeatherForecastAPI。点击GET /WeatherForecast旁边的 “Try it out” - “Execute”看到返回了一串 JSON 数据。恭喜你的第一个 ASP.NET Core 应用跑起来了这个“跑起来”的瞬间比看十小时视频都重要。它证明了你的环境是通的项目结构是有效的。2. 理解项目骨架知道文件都是干嘛的项目能跑了现在打开文件夹别被一堆文件吓到。我们只关注最核心的几个。2.1 核心目录与文件解析MyFirstApi/ ├── Properties/ │ └── launchSettings.json // **启动配置文件**。定义了不同启动环境IIS Express, Kestrel的端口、环境变量等。初期不用改。 ├── Controllers/ │ └── WeatherForecastController.cs // **控制器**。处理HTTP请求返回响应。这是你写业务逻辑的主要地方。 ├── Program.cs // **程序入口**。.NET 6之后所有配置都从这里开始。这是最重要的文件之一。 ├── appsettings.json // **应用配置文件**。存放数据库连接字符串、日志级别等配置。 └── MyFirstApi.csproj // **项目文件**。定义了项目依赖的NuGet包、目标框架等。Program.cs这是 ASP.NET Core 应用的“心脏”。打开它你会看到类似下面的代码var builder WebApplication.CreateBuilder(args); // 添加服务到容器依赖注入。 builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); var app builder.Build(); // 配置HTTP请求管道中间件。 if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();这段代码做了两件事builder部分var builder ...到var app builder.Build()叫服务配置。你把各种功能如控制器、Swagger、数据库上下文注册到这里系统后面才能用。app部分var app ...到app.Run()叫请求管道配置。HTTP请求像水流过管道每个app.UseXxx()就是一个“处理器”决定请求怎么被处理、响应怎么被返回。顺序很重要。WeatherForecastController.cs这是“控制器”。它里面的WeatherForecastController类继承自ControllerBase。类里面那个[HttpGet]标记的方法Get()就是处理GET /WeatherForecast请求的地方。你以后写的 API 接口大部分都是这样的控制器类和方法。appsettings.jsonJSON 格式的配置文件。你可以在这里放自己的配置比如{ Logging: { ... }, MySetting: Hello from config, // 自定义配置 ConnectionStrings: { DefaultConnection: Server(localdb)\\mssqllocaldb;DatabaseMyDb;Trusted_ConnectionTrue; } }在Program.cs里可以用builder.Configuration[MySetting]来读取。2.2 关键概念依赖注入DI与中间件Middleware这是 ASP.NET Core 的两个核心设计模式不理解它们代码会写得很别扭。依赖注入DI简单说就是“你需要什么我系统给你什么而不是你自己去new”。比如控制器里需要访问数据库你不需要在控制器里new MyDbContext()而是在Program.cs的builder.Services里注册这个MyDbContext然后在控制器的构造函数中声明需要它系统会自动给你一个实例。这样做的好处是解耦、易测试。怎么用在Program.cs里builder.Services.AddScopedIMyService, MyService();这样注册。在控制器构造函数里private readonly IMyService _service;这样声明。中间件Middleware就是Program.cs里app.UseXxx()那些组件。请求进来后按顺序经过一个个中间件每个中间件都可以对请求或响应做点事比如记录日志、验证权限、处理异常然后决定是继续往下传还是直接返回。app.Run()是管道的终点。顺序很重要比如错误处理中间件app.UseExceptionHandler()应该放在管道最前面这样才能捕获后面所有中间件的异常。而路由匹配中间件app.MapControllers()通常放在靠后的位置。对于入门你不需要立刻精通但要有这个意识配置服务在builder.Services里配置请求处理流程在app里。3. 动手实战从增删改查CRUD理解全流程看懂了骨架我们来真的。目标是做一个简单的“待办事项Todo”API支持创建、查看、更新、删除。3.1 第一步定义模型Model模型就是数据的形状。在项目根目录创建一个Models文件夹里面添加一个TodoItem.cs类。namespace MyFirstApi.Models; public class TodoItem { public int Id { get; set; } // 唯一标识 public string? Title { get; set; } // 任务标题 public bool IsComplete { get; set; } // 是否完成 public DateTime CreatedTime { get; set; } DateTime.Now; // 创建时间 }这就是一个简单的模型对应数据库里的一张表如果以后用数据库的话。3.2 第二步创建数据库上下文DbContext并注册我们先用内存数据库这样不需要安装 SQL Server最适合学习。首先通过 NuGet 安装 EF Core 内存数据库包。在 VS 里可以在项目上右键“管理 NuGet 程序包”搜索Microsoft.EntityFrameworkCore.InMemory并安装。在 VS Code 终端里进入项目目录运行dotnet add package Microsoft.EntityFrameworkCore.InMemory。在Models文件夹下创建TodoContext.csusing Microsoft.EntityFrameworkCore; namespace MyFirstApi.Models; public class TodoContext : DbContext { public TodoContext(DbContextOptionsTodoContext options) : base(options) { } public DbSetTodoItem TodoItems { get; set; } // 代表TodoItems表 }在Program.cs的builder.Services部分注册这个上下文// 添加数据库上下文使用内存数据库 builder.Services.AddDbContextTodoContext(opt opt.UseInMemoryDatabase(TodoList));3.3 第三步创建控制器Controller在Controllers文件夹上右键添加 - 控制器 - API控制器使用 Entity Framework 读写操作。选择模型类TodoItem数据上下文类TodoContext。或者你可以手动创建一个TodoItemsController.csusing Microsoft.AspNetCore.Mvc; using Microsoft.EntityFrameworkCore; using MyFirstApi.Models; namespace MyFirstApi.Controllers; [Route(api/[controller])] // 路由模板访问路径会是 /api/TodoItems [ApiController] public class TodoItemsController : ControllerBase { private readonly TodoContext _context; public TodoItemsController(TodoContext context) { _context context; } // GET: api/TodoItems [HttpGet] public async TaskActionResultIEnumerableTodoItem GetTodoItems() { return await _context.TodoItems.ToListAsync(); } // GET: api/TodoItems/5 [HttpGet({id})] public async TaskActionResultTodoItem GetTodoItem(int id) { var todoItem await _context.TodoItems.FindAsync(id); if (todoItem null) { return NotFound(); // 返回404 } return todoItem; } // PUT: api/TodoItems/5 [HttpPut({id})] public async TaskIActionResult PutTodoItem(int id, TodoItem todoItem) { if (id ! todoItem.Id) { return BadRequest(); // 返回400 } _context.Entry(todoItem).State EntityState.Modified; try { await _context.SaveChangesAsync(); } catch (DbUpdateConcurrencyException) { if (!TodoItemExists(id)) { return NotFound(); } else { throw; } } return NoContent(); // 返回204 } // POST: api/TodoItems [HttpPost] public async TaskActionResultTodoItem PostTodoItem(TodoItem todoItem) { _context.TodoItems.Add(todoItem); await _context.SaveChangesAsync(); // CreatedAtAction 返回201状态码并在响应头Location中给出新资源的URI return CreatedAtAction(nameof(GetTodoItem), new { id todoItem.Id }, todoItem); } // DELETE: api/TodoItems/5 [HttpDelete({id})] public async TaskIActionResult DeleteTodoItem(int id) { var todoItem await _context.TodoItems.FindAsync(id); if (todoItem null) { return NotFound(); } _context.TodoItems.Remove(todoItem); await _context.SaveChangesAsync(); return NoContent(); } private bool TodoItemExists(int id) { return _context.TodoItems.Any(e e.Id id); } }这个控制器包含了完整的 CRUD 操作。注意每个方法上的[HttpGet],[HttpPost]等属性它们定义了 HTTP 方法和路由。3.4 第四步测试你的 API重新运行项目 (dotnet run或F5)打开 Swagger 页面 (/swagger)。现在你应该能看到TodoItems相关的 API 了。POST /api/TodoItems点击“Try it out”在 Request body 里输入 JSON{ title: 学习 ASP.NET Core, isComplete: false }然后 Execute。成功后返回 201并且返回了带 Id 的 TodoItem。GET /api/TodoItems执行你会看到包含刚才创建的那条数据的数组。GET /api/TodoItems/{id}把上一步返回的 Id 填进去执行获取单条。PUT /api/TodoItems/{id}修改一条数据比如把isComplete改成true。DELETE /api/TodoItems/{id}删除一条数据。到这里你已经完成了一个完整的、有数据库交互的 Web API 后端。这个过程涵盖了模型定义、依赖注入注册、控制器编写、HTTP 方法处理、以及通过 Swagger 测试。这是最核心的闭环。4. 深入与扩展把项目变得更“像样”完成基础 CRUD 后你需要了解如何让项目更健壮、更易维护。4.1 使用仓储Repository模式直接在控制器里写_context.TodoItems...虽然能跑但不利于测试和复用。更常见的做法是引入一个“仓储层”来封装数据访问逻辑。创建一个Interfaces文件夹和Repositories文件夹。在Interfaces里创建ITodoRepository.csusing MyFirstApi.Models; namespace MyFirstApi.Interfaces; public interface ITodoRepository { TaskIEnumerableTodoItem GetAllAsync(); TaskTodoItem? GetByIdAsync(int id); TaskTodoItem AddAsync(TodoItem item); Task UpdateAsync(TodoItem item); Task DeleteAsync(int id); Taskbool ExistsAsync(int id); }在Repositories里创建TodoRepository.cs实现这个接口using Microsoft.EntityFrameworkCore; using MyFirstApi.Interfaces; using MyFirstApi.Models; namespace MyFirstApi.Repositories; public class TodoRepository : ITodoRepository { private readonly TodoContext _context; public TodoRepository(TodoContext context) _context context; public async TaskIEnumerableTodoItem GetAllAsync() await _context.TodoItems.ToListAsync(); public async TaskTodoItem? GetByIdAsync(int id) await _context.TodoItems.FindAsync(id); public async TaskTodoItem AddAsync(TodoItem item) { _context.TodoItems.Add(item); await _context.SaveChangesAsync(); return item; } // ... 实现其他方法 }在Program.cs注册这个仓储builder.Services.AddScopedITodoRepository, TodoRepository();修改TodoItemsController不再注入TodoContext而是注入ITodoRepository并在方法中调用仓储。这样做的好处是控制器不再关心数据怎么存是内存、SQL Server 还是别的只关心业务逻辑。测试时也可以轻松模拟Mock一个仓储。4.2 添加日志记录日志是排查问题的生命线。ASP.NET Core 内置了强大的日志系统。在Program.cs的builder部分之后var app builder.Build();之前你就可以获取到 Logger 并记录var builder WebApplication.CreateBuilder(args); // 配置服务... // 在构建app之前可以获取一个Logger var logger builder.Services.BuildServiceProvider().GetRequiredServiceILoggerProgram(); logger.LogInformation(应用程序正在启动...); var app builder.Build(); // 配置中间件...在控制器或其他类中通过构造函数注入ILoggerTodoItemsController来使用。在appsettings.json里可以配置日志级别控制台输出等。4.3 处理异常与返回统一格式目前 API 出错时返回的是框架默认的错误页面或状态码。为了给前端提供更友好的信息可以创建全局异常处理中间件和统一响应模型。创建Models/ApiResponse.csnamespace MyFirstApi.Models; public class ApiResponseT { public bool Success { get; set; } public string? Message { get; set; } public T? Data { get; set; } public static ApiResponseT Ok(T data, string? message null) new() { Success true, Data data, Message message }; public static ApiResponseT Fail(string message) new() { Success false, Message message }; }创建一个中间件Middleware/ExceptionHandlingMiddleware.cs来捕获全局异常并返回统一的ApiResponse。在Program.cs的请求管道中app.UseMiddlewareExceptionHandlingMiddleware();。这样无论成功还是失败前端收到的都是{ success: true/false, message: “...”, data: ... }这种格式便于处理。4.4 连接真实数据库以 SQL Server 为例内存数据库只用于学习。真实项目需要持久化存储。安装 NuGet 包Microsoft.EntityFrameworkCore.SqlServer。修改appsettings.json添加连接字符串ConnectionStrings: { DefaultConnection: Server(localdb)\\mssqllocaldb;DatabaseTodoDb;Trusted_ConnectionTrue;MultipleActiveResultSetstrue }这里用了 LocalDB是 Visual Studio 自带的轻量版 SQL Server适合开发。修改Program.cs中的服务注册替换内存数据库// 替换掉 UseInMemoryDatabase builder.Services.AddDbContextTodoContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection)));创建数据库迁移在终端项目目录下运行dotnet ef migrations add InitialCreate dotnet ef database update这会在你的 LocalDB 中创建一个名为TodoDb的数据库并生成TodoItems表。5. 部署准备与常见问题排查学到最后你得知道怎么把它放到服务器上跑起来。5.1 发布应用ASP.NET Core 应用可以发布为“框架依赖”或“独立”部署。框架依赖目标机器上需要安装对应版本的 .NET 运行时。发布命令dotnet publish -c Release -o ./publish。生成的文件较小。独立将 .NET 运行时一起打包生成一个独立的可执行文件。发布命令dotnet publish -c Release -r win-x64 --self-contained true -o ./publish以 Windows x64 为例。生成的文件较大但目标机器不需要装 .NET。发布后publish文件夹里的文件就是你需要部署到服务器如 IIS, Nginx, Docker 容器的内容。5.2 常见问题与排查顺序项目跑不起来报错“找不到 SDK”或“项目文件错误”先查命令行运行dotnet --version确认 SDK 已安装且版本匹配项目文件.csproj中的TargetFramework。再查在项目目录下运行dotnet restore还原 NuGet 包。最后查用dotnet build看编译错误。Swagger 页面能打开但调用 API 返回 404先查控制器类和方法上的路由属性[Route]、[HttpGet(“{id}”)]是否写对。注意大小写。再查Program.cs里是否调用了app.MapControllers()。最后查启动日志里有没有路由注册成功的消息。连接数据库失败先查appsettings.json里的连接字符串是否正确数据库服务器是否启动。再查是否执行了数据库迁移 (dotnet ef database update)。最后查在Program.cs的app部分开始处添加app.Services.CreateScope()来手动触发数据库连接看具体错误。修改了代码但刷新页面没变化先查是否保存了文件。VS Code 有时需要手动保存。再查.NET热重载是否生效。可以尝试停止 (CtrlC) 后重新dotnet run。最后查浏览器缓存。尝试强制刷新 (CtrlF5) 或使用无痕窗口。发布到服务器后无法运行先查服务器上是否安装了对应的 .NET 运行时如果是框架依赖部署或运行时版本是否匹配。再查应用池IIS或服务Systemd的启动账户是否有权限访问文件、网络和数据库。最后查服务器防火墙是否开放了应用监听的端口默认是 5000, 5001 或你在launchSettings.json/appsettings.json里配置的端口。学习 ASP.NET Core最关键的不是看完多少小时的视频而是按照“环境 - 项目骨架 - 核心概念DI、中间件- 完整CRUD实战 - 模式优化仓储、日志- 真实数据库 - 部署”这个路径自己动手把每个环节都敲一遍、跑通、并理解为什么这么做。遇到报错别怕那是最好的学习材料按照上面的排查顺序大部分问题都能自己解决。