辽宁省住房与城乡建设厅网站,郑州建设网站企业定制,建设项目自主验收网站,企业网站的cms构建最小 API#xff0c;以创建具有最小依赖项的 HTTP API。 它们非常适合需要在 ASP.NET Core 中仅包括最少文件、功能和依赖项的微服务和应用。 本教程介绍使用 ASP.NET Core 生成最小 API 的基础知识。 在 ASP.NET Core 中创建 API 的另一种方法是使用控制器。 有关在最小 … 构建最小 API以创建具有最小依赖项的 HTTP API。 它们非常适合需要在 ASP.NET Core 中仅包括最少文件、功能和依赖项的微服务和应用。 本教程介绍使用 ASP.NET Core 生成最小 API 的基础知识。 在 ASP.NET Core 中创建 API 的另一种方法是使用控制器。 有关在最小 API 和基于控制器的 API 之间进行选择的帮助请参阅 API 概述。 有关基于包含更多功能的控制器创建 API 项目的教程请参阅创建 Web API。
概述 本教程将创建以下 API
API描述请求正文响应正文GET /todoitems获取所有待办事项None待办事项的数组GET /todoitems/complete获取已完成的待办事项None待办事项的数组GET /todoitems/{id}按 ID 获取项None待办事项POST /todoitems添加新项待办事项待办事项PUT /todoitems/{id}更新现有项待办事项NoneDELETE /todoitems/{id} 删除项None无
先决条件
带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022 创建 API 项目
启动 Visual Studio 2022 并选择“创建新项目”。
在“创建新项目”对话框中 在“搜索模板”搜索框中输入 Empty。 选择“ASP.NET Core 空”模板然后选择“下一步”。 将项目命名为 TodoApi然后选择“下一步”。
在“其他信息”对话框中 选择“.NET 8.0 (长期支持)” 取消选中“不使用顶级语句” 选择“创建” 检查代码 Program.cs 文件包含以下代码
var builder WebApplication.CreateBuilder(args); var app builder.Build();
app.MapGet(/, () Hello World!);
app.Run();
前面的代码 创建具有预配置默认值的 WebApplicationBuilder 和 WebApplication。 创建返回 Hello World! 的 HTTP GET 终结点 /
运行应用
按 CtrlF5 以在不使用调试程序的情况下运行。
Visual Studio 会显示以下对话框 如果信任 IIS Express SSL 证书请选择“是”。
将显示以下对话框 如果你同意信任开发证书请选择“是”。
有关信任 Firefox 浏览器的信息请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。
Visual Studio 启动 Kestrel Web 服务器然后打开浏览器窗口。
Hello World! 将显示在浏览器中。 Program.cs 文件包含一个最小但完整的应用。
关闭浏览器窗口。
添加 NuGet 包
必须添加 NuGet 包以支持本教程中使用的数据库和诊断。 在“工具”菜单中选择“NuGet 包管理器”“管理解决方案的 NuGet 包”。 选择“浏览”选项卡。 在搜索框中输入“Microsoft.EntityFrameworkCore.InMemory”然后选择 Microsoft.EntityFrameworkCore.InMemory。 选中右窗格中的“项目”复选框然后选择“安装” 。 按照上述说明添加 Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore 包。
模型和数据库上下文类
在项目文件夹中创建名为 Todo.cs 的文件包含以下代码
public class Todo { public int Id { get; set; } public string? Name { get; set; } public bool IsComplete { get; set; } }
前面的代码为此应用创建模型。 模型是一个表示应用管理的数据的类。 使用以下代码创建名为 TodoDb.cs 的文件 using Microsoft.EntityFrameworkCore;
class TodoDb : DbContext { public TodoDb(DbContextOptionsTodoDb options) : base(options) { } public DbSetTodo Todos SetTodo(); }
前面的代码定义了数据库上下文它是为数据模型协调实体框架功能的主类。 此类从 Microsoft.EntityFrameworkCore.DbContext 类派生。
添加 API 代码
将 Program.cs 文件的内容替换为以下代码
using Microsoft.EntityFrameworkCore;
var builder WebApplication.CreateBuilder(args); builder.Services.AddDbContextTodoDb(opt opt.UseInMemoryDatabase(TodoList)); builder.Services.AddDatabaseDeveloperPageExceptionFilter(); var app builder.Build();
app.MapGet(/todoitems, async (TodoDb db) await db.Todos.ToListAsync());
app.MapGet(/todoitems/complete, async (TodoDb db) await db.Todos.Where(t t.IsComplete).ToListAsync());
app.MapGet(/todoitems/{id}, async (int id, TodoDb db) await db.Todos.FindAsync(id) is Todo todo ? Results.Ok(todo) : Results.NotFound());
app.MapPost(/todoitems, async (Todo todo, TodoDb db) { db.Todos.Add(todo); await db.SaveChangesAsync(); return Results.Created($/todoitems/{todo.Id}, todo); });
app.MapPut(/todoitems/{id}, async (int id, Todo inputTodo, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return Results.NotFound(); todo.Name inputTodo.Name; todo.IsComplete inputTodo.IsComplete; await db.SaveChangesAsync(); return Results.NoContent(); });
app.MapDelete(/todoitems/{id}, async (int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return Results.NoContent(); } return Results.NotFound(); });
app.Run();
以下突出显示的代码将数据库上下文添加到依赖关系注入 (DI) 容器并且允许显示与数据库相关的异常
var builder WebApplication.CreateBuilder(args); builder.Services.AddDbContextTodoDb(opt opt.UseInMemoryDatabase(TodoList)); builder.Services.AddDatabaseDeveloperPageExceptionFilter(); var app builder.Build();
DI 容器提供对数据库上下文和其他服务的访问权限。 本教程使用终结点资源管理器和 .http 文件来测试 API。
测试发布数据
Program.cs 中的以下代码创建 HTTP POST 终结点 /todoitems 以将数据添加到内存中数据库
app.MapPost(/todoitems, async (Todo todo, TodoDb db) { db.Todos.Add(todo); await db.SaveChangesAsync(); return Results.Created($/todoitems/{todo.Id}, todo); });
运行应用。 浏览器显示 404 错误因为不再存在 / 终结点。
POST 终结点将用于向应用添加数据。 选择“查看”“其他 Windows”“终结点资源管理器”。 右键单击“POST”终结点然后选择“生成请求”。 在名为 TodoApi.http 的项目文件夹中创建一个新文件其内容类似于以下示例
TodoApi_HostAddress https://localhost:7031
Post {{TodoApi_HostAddress}}/todoitems
### 第一行创建了一个变量该变量适用于所有终结点。 下一行定义了 POST 请求。 三重井号标签 (###) 行是请求分隔符对于不同的请求该标签之后的内容属于另一个请求。
POST 请求需要标头和正文。 若要定义请求的这些部分请紧随 POST 请求行之后添加以下行
Content-Type: application/json
{ name:walk dog, isComplete:true }
前面的代码会添加 Content-Type 标头和 JSON 请求正文。 TodoApi.http 文件现在应如以下示例所示但带有端口号
TodoApi_HostAddress https://localhost:7057
Post {{TodoApi_HostAddress}}/todoitems Content-Type: application/json
{ name:walk dog, isComplete:true }
###
运行应用。
选择 POST 请求行上方的“发送请求”链接。 POST 请求将发送到应用响应将显示在“响应”窗格中。 检查 GET 终结点 示例应用通过调用 MapGet 实现多个 GET 终结点
API描述请求正文响应正文GET /todoitems获取所有待办事项None待办事项的数组GET /todoitems/complete获取所有已完成的待办事项None待办事项的数组GET /todoitems/{id}按 ID 获取项None待办事项
app.MapGet(/todoitems, async (TodoDb db) await db.Todos.ToListAsync());
app.MapGet(/todoitems/complete, async (TodoDb db) await db.Todos.Where(t t.IsComplete).ToListAsync());
app.MapGet(/todoitems/{id}, async (int id, TodoDb db) await db.Todos.FindAsync(id) is Todo todo ? Results.Ok(todo) : Results.NotFound());
测试 GET 终结点
通过从浏览器或使用终结点资源管理器调用 GET 终结点来测试应用。 以下步骤适用于终结点资源管理器。 在“终结点资源管理器”中右键单击第一个 GET 终结点然后选择“生成请求”。 将以下内容添加到 TodoApi.http 文件中 Get {{TodoApi_HostAddress}}/todoitems
###
选择新的 GET 请求行上方的“发送请求”链接。
GET 请求将发送到应用响应将显示在“响应”窗格中。
响应正文与以下 JSON 类似
[ { id: 1, name: walk dog, isComplete: true } ]
在“终结点资源管理器”中右键单击“/todoitems/{id} GET”终结点然后选择“生成请求”。 将以下内容添加到 TodoApi.http 文件中
GET {{TodoApi_HostAddress}}/todoitems/{id}
###
将 {id} 替换为 1。
选择新的 GET 请求行上方的“发送请求”链接。
GET 请求将发送到应用响应将显示在“响应”窗格中。
响应正文与以下 JSON 类似
{ id: 1, name: walk dog, isComplete: true }
此应用使用内存中数据库。 如果已重新启动应用GET 请求不会返回任何数据。 如果未返回任何数据请将数据 POST 到应用然后重新尝试 GET 请求。
返回值
ASP.NET Core 自动将对象序列化为 JSON并将 JSON 写入响应消息的正文中。 此返回类型的响应代码为 200 OK假设没有未处理的异常。 未经处理的异常将转换为 5xx 错误。
返回类型可以表示大范围的 HTTP 状态代码。 例如GET /todoitems/{id} 可以返回两个不同的状态值 如果没有任何项与请求的 ID 匹配该方法将返回 404 状态 NotFound 错误代码。 否则此方法将返回具有 JSON 响应正文的 200。 返回 item 则产生 HTTP 200 响应。
检查 PUT 终结点
示例应用使用 MapPut 实现单个 PUT 终结点
app.MapPut(/todoitems/{id}, async (int id, Todo inputTodo, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return Results.NotFound(); todo.Name inputTodo.Name; todo.IsComplete inputTodo.IsComplete; await db.SaveChangesAsync(); return Results.NoContent(); }); 此方法类似于 MapPost 方法但它使用 HTTP PUT。 成功响应返回 204 (无内容)。 根据 HTTP 规范PUT 请求需要客户端发送整个更新的实体而不仅仅是更改。 若要支持部分更新请使用 HTTP PATCH。
测试 PUT 终结点
本示例使用内存内、数据库每次启动应用时都必须对其进行初始化。 在进行 PUT 调用之前数据库中必须有一个项。 调用 GET以确保在调用 PUT 之前数据库中存在项。
更新具有 Id 1 的 to-do 项并将其名称设置为 feed fish。 在“终结点资源管理器”中右键单击 PUT 终结点然后选择“生成请求”。 将以下内容添加到 TodoApi.http 文件中 Put {{TodoApi_HostAddress}}/todoitems/{id} ### 在 PUT 请求行中将 {id} 替换为 1。 紧随 PUT 请求行之后添加以下行 Content-Type: application/json { name: feed fish, isComplete: false } 前面的代码会添加 Content-Type 标头和 JSON 请求正文。 选择新的 PUT 请求行上方的“发送请求”链接。 PUT 请求将发送到应用响应将显示在“响应”窗格中。 响应正文为空状态代码为 204。
检查并测试 DELETE 终结点
示例应用使用 MapDelete 实现单个 DELETE 终结点
app.MapDelete(/todoitems/{id}, async (int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return Results.NoContent(); } return Results.NotFound(); });
在“终结点资源管理器”中右键单击 DELETE 终结点然后选择“生成请求”。
将 DELETE 请求添加到 TodoApi.http。
将 DELETE 请求行中的 {id} 替换为 1。 DELETE 请求应如以下示例所示
DELETE {{TodoApi_HostAddress}}/todoitems/1
###
选择 DELETE 请求的“发送请求”链接。
DELETE 请求将发送到应用响应将显示在“响应”窗格中。 响应正文为空状态代码为 204。
使用 MapGroup API 示例应用代码每次设置终结点时都会重复 todoitems URL 前缀。 API 通常具有带常见 URL 前缀的终结点组并且 MapGroup 方法可用于帮助组织此类组。 它减少了重复代码并允许通过对 RequireAuthorization 和 WithMetadata 等方法的单一调用来自定义整个终结点组。
将 Program.cs 的内容替换为以下代码
using Microsoft.EntityFrameworkCore;
var builder WebApplication.CreateBuilder(args); builder.Services.AddDbContextTodoDb(opt opt.UseInMemoryDatabase(TodoList)); builder.Services.AddDatabaseDeveloperPageExceptionFilter(); var app builder.Build();
var todoItems app.MapGroup(/todoitems);
todoItems.MapGet(/, async (TodoDb db) await db.Todos.ToListAsync());
todoItems.MapGet(/complete, async (TodoDb db) await db.Todos.Where(t t.IsComplete).ToListAsync());
todoItems.MapGet(/{id}, async (int id, TodoDb db) await db.Todos.FindAsync(id) is Todo todo ? Results.Ok(todo) : Results.NotFound());
todoItems.MapPost(/, async (Todo todo, TodoDb db) { db.Todos.Add(todo); await db.SaveChangesAsync(); return Results.Created($/todoitems/{todo.Id}, todo); });
todoItems.MapPut(/{id}, async (int id, Todo inputTodo, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return Results.NotFound(); todo.Name inputTodo.Name; todo.IsComplete inputTodo.IsComplete; await db.SaveChangesAsync(); return Results.NoContent(); });
todoItems.MapDelete(/{id}, async (int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return Results.NoContent(); } return Results.NotFound(); });
app.Run();
前面的代码执行以下更改 添加 var todoItems app.MapGroup(/todoitems); 以使用 URL 前缀 /todoitems 设置组。 将所有 app.MapHttpVerb 方法更改为 todoItems.MapHttpVerb。 从 MapHttpVerb 方法调用中移除 URL 前缀 /todoitems。
测试终结点以验证它们的运行方式是否相同。
使用 TypedResults API 返回 TypedResults而不是 Results有几个优点包括可测试性和自动返回 OpenAPI 的响应类型元数据来描述终结点。 有关详细信息请参阅 TypedResults 与 Results。
MapHttpVerb 方法可以调用路由处理程序方法而不是使用 lambda。 若要查看示例请使用以下代码更新 Program.cs
using Microsoft.EntityFrameworkCore;
var builder WebApplication.CreateBuilder(args); builder.Services.AddDbContextTodoDb(opt opt.UseInMemoryDatabase(TodoList)); builder.Services.AddDatabaseDeveloperPageExceptionFilter(); var app builder.Build();
var todoItems app.MapGroup(/todoitems);
todoItems.MapGet(/, GetAllTodos); todoItems.MapGet(/complete, GetCompleteTodos); todoItems.MapGet(/{id}, GetTodo); todoItems.MapPost(/, CreateTodo); todoItems.MapPut(/{id}, UpdateTodo); todoItems.MapDelete(/{id}, DeleteTodo);
app.Run();
static async TaskIResult GetAllTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.ToArrayAsync()); }
static async TaskIResult GetCompleteTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.Where(t t.IsComplete).ToListAsync()); }
static async TaskIResult GetTodo(int id, TodoDb db) { return await db.Todos.FindAsync(id) is Todo todo ? TypedResults.Ok(todo) : TypedResults.NotFound(); }
static async TaskIResult CreateTodo(Todo todo, TodoDb db) { db.Todos.Add(todo); await db.SaveChangesAsync(); return TypedResults.Created($/todoitems/{todo.Id}, todo); }
static async TaskIResult UpdateTodo(int id, Todo inputTodo, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return TypedResults.NotFound(); todo.Name inputTodo.Name; todo.IsComplete inputTodo.IsComplete; await db.SaveChangesAsync(); return TypedResults.NoContent(); }
static async TaskIResult DeleteTodo(int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return TypedResults.NoContent(); } return TypedResults.NotFound(); }
MapHttpVerb 代码现在调用方法而不是 lambda
var todoItems app.MapGroup(/todoitems);
todoItems.MapGet(/, GetAllTodos); todoItems.MapGet(/complete, GetCompleteTodos); todoItems.MapGet(/{id}, GetTodo); todoItems.MapPost(/, CreateTodo); todoItems.MapPut(/{id}, UpdateTodo); todoItems.MapDelete(/{id}, DeleteTodo);
这些方法返回实现 IResult 并由 TypedResults 定义的对象
static async TaskIResult GetAllTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.ToArrayAsync()); }
static async TaskIResult GetCompleteTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.Where(t t.IsComplete).ToListAsync()); }
static async TaskIResult GetTodo(int id, TodoDb db) { return await db.Todos.FindAsync(id) is Todo todo ? TypedResults.Ok(todo) : TypedResults.NotFound(); }
static async TaskIResult CreateTodo(Todo todo, TodoDb db) { db.Todos.Add(todo); await db.SaveChangesAsync(); return TypedResults.Created($/todoitems/{todo.Id}, todo); }
static async TaskIResult UpdateTodo(int id, Todo inputTodo, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return TypedResults.NotFound(); todo.Name inputTodo.Name; todo.IsComplete inputTodo.IsComplete; await db.SaveChangesAsync(); return TypedResults.NoContent(); }
static async TaskIResult DeleteTodo(int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return TypedResults.NoContent(); } return TypedResults.NotFound(); }
单元测试可以调用这些方法并测试它们是否返回正确的类型。 例如如果方法是 GetAllTodos
static async TaskIResult GetAllTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.ToArrayAsync()); }
单元测试代码可以验证是否从处理程序方法返回了 OkTodo[]类型的对象。 例如
public async Task GetAllTodos_ReturnsOkOfTodosResult() { // Arrange var db CreateDbContext(); // Act var result await TodosApi.GetAllTodos(db); // Assert: Check for the correct returned type Assert.IsTypeOkTodo[](result); }
防止过度发布 目前示例应用公开了整个 Todo 对象。 生产应用程序中的生产应用是模型的一个子集通常用于限制可输入和返回的数据。 这背后有多种原因但安全性是主要原因。 模型的子集通常称为数据传输对象 (DTO)、输入模型或视图模型。 本文使用的是 DTO。
DTO 可以用于 防止过度发布。 隐藏客户端不应查看的属性。 省略某些属性以减少有效负载大小。 平展包含嵌套对象的对象图。 对客户端而言平展的对象图可能更方便。 若要演示 DTO 方法请更新 Todo 类使其包含机密字段 public class Todo { public int Id { get; set; } public string? Name { get; set; } public bool IsComplete { get; set; } public string? Secret { get; set; } }
此应用需要隐藏机密字段但管理应用可以选择公开它。
确保可以发布和获取机密字段。
使用以下代码创建名为 TodoItemDTO.cs 的文件
public class TodoItemDTO { public int Id { get; set; } public string? Name { get; set; } public bool IsComplete { get; set; } public TodoItemDTO() { } public TodoItemDTO(Todo todoItem) (Id, Name, IsComplete) (todoItem.Id, todoItem.Name, todoItem.IsComplete); }
将 Program.cs 文件的内容替换为以下代码以使用此 DTO 模型
using Microsoft.EntityFrameworkCore;
var builder WebApplication.CreateBuilder(args); builder.Services.AddDbContextTodoDb(opt opt.UseInMemoryDatabase(TodoList)); builder.Services.AddDatabaseDeveloperPageExceptionFilter(); var app builder.Build();
RouteGroupBuilder todoItems app.MapGroup(/todoitems);
todoItems.MapGet(/, GetAllTodos); todoItems.MapGet(/complete, GetCompleteTodos); todoItems.MapGet(/{id}, GetTodo); todoItems.MapPost(/, CreateTodo); todoItems.MapPut(/{id}, UpdateTodo); todoItems.MapDelete(/{id}, DeleteTodo);
app.Run();
static async TaskIResult GetAllTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.Select(x new TodoItemDTO(x)).ToArrayAsync()); }
static async TaskIResult GetCompleteTodos(TodoDb db) { return TypedResults.Ok(await db.Todos.Where(t t.IsComplete).Select(x new TodoItemDTO(x)).ToListAsync()); }
static async TaskIResult GetTodo(int id, TodoDb db) { return await db.Todos.FindAsync(id) is Todo todo ? TypedResults.Ok(new TodoItemDTO(todo)) : TypedResults.NotFound(); }
static async TaskIResult CreateTodo(TodoItemDTO todoItemDTO, TodoDb db) { var todoItem new Todo { IsComplete todoItemDTO.IsComplete, Name todoItemDTO.Name }; db.Todos.Add(todoItem); await db.SaveChangesAsync(); todoItemDTO new TodoItemDTO(todoItem); return TypedResults.Created($/todoitems/{todoItem.Id}, todoItemDTO); }
static async TaskIResult UpdateTodo(int id, TodoItemDTO todoItemDTO, TodoDb db) { var todo await db.Todos.FindAsync(id); if (todo is null) return TypedResults.NotFound(); todo.Name todoItemDTO.Name; todo.IsComplete todoItemDTO.IsComplete; await db.SaveChangesAsync(); return TypedResults.NoContent(); }
static async TaskIResult DeleteTodo(int id, TodoDb db) { if (await db.Todos.FindAsync(id) is Todo todo) { db.Todos.Remove(todo); await db.SaveChangesAsync(); return TypedResults.NoContent(); } return TypedResults.NotFound(); }
确保可以发布和获取除机密字段以外的所有字段。
用完成的示例进行故障排除
如果遇到无法解决的问题请将你的代码与完成的项目进行比较。 查看或下载已完成的项目如何下载
原文连接教程使用 ASP.NET Core 创建最小 API | Microsoft Learn
