使用 ASP.NET Core 和 MongoDB 创建 Web API

作者 Pratik Khandelwal 和 Scott Addie

本教程创建对 MongoDB NoSQL 数据库运行创建、读取、更新和删除 (CRUD) 操作的 Web API。

在本教程中，你将了解：

• 配置 MongoDB
• 创建 MongoDB 数据库
• 定义 MongoDB 集合和架构
• 从 Web API 执行 MongoDB CRUD 操作
• 自定义 JSON 序列化

先决条件

• MongoDB 6.0.5 或更高版本
• MongoDB Shell

Visual Studio

• 带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

  

Visual Studio Code

• Visual Studio Code
• 适用于 Visual Studio Code 的 C# 开发工具包
• .NET 9 SDK

可以按照 macOS、Linux 或 Windows 上的 Visual Studio Code 说明进行操作。 如果使用 Visual Studio Code 以外的集成开发环境（IDE），可能需要更改。

配置 MongoDB

从开发计算机上的任意位置启用 MongoDB 和 MongoDB Shell 访问 (Windows/Linux/macOS)：

1. 下载并安装 MongoDB Shell：

   • macOS/Linux：选择要将 MongoDB Shell 提取到的目录。 将 mongosh 的结果路径添加到 PATH 环境变量。
   • Windows：MongoDB Shell（mongosh.exe）安装在 C：\Users\<user>\AppData\Local\Programs\mongosh。 将 mongosh.exe 的结果路径添加到 PATH 环境变量。

2. 下载并安装 MongoDB：

   • macOS/Linux：验证安装了 MongoDB 的目录，通常在 /usr/local/mongodb 中。 将 mongodb 的结果路径添加到 PATH 环境变量。
   • Windows：MongoDB 默认安装在 C:\Program Files\MongoDB。 将 C:\Program Files\MongoDB\Server\<version_number>\bin 添加到 PATH 环境变量。

3. 选择数据存储目录：选择开发计算机上用于存储数据的目录。 创建目录（如果不存在）。 MongoDB Shell 不会创建新目录：

   • macOS/Linux：例如 /usr/local/var/mongodb。
   • Windows：例如 C:\\BooksData。

4. 在 OS 命令行界面（而不是 MongoDB Shell）中，使用以下命令连接到默认端口 27017 上的 MongoDB。 将 <data_directory_path> 替换为上一步中选择的目录。

   mongod --dbpath <data_directory_path>
   

在以下步骤中使用之前安装的 MongoDB Shell 可以创建数据库、创建集合和存储文档。 有关 MongoDB Shell 命令的详细信息，请参阅 mongosh。

1. 通过启动 mongosh.exe或在命令行界面中运行以下命令来打开 MongoDB 命令 shell 实例：

   mongosh
   

2. 在命令行界面中，通过运行以下命令连接到默认测试数据库：

   use BookStore
   

   如果它不存在，则创建名为 BookStore 的数据库。 如果该数据库存在，则将为事务打开其连接。

3. 使用以下命令创建 Books 集合：

   db.createCollection('Books')
   

   显示以下结果：

   { "ok" : 1 }
   

4. 使用以下命令定义 Books 集合的架构并插入两个文档：

   db.Books.insertMany([{ "Name": "Design Patterns", "Price": 54.93, "Category": "Computers", "Author": "Ralph Johnson" }, { "Name": "Clean Code", "Price": 43.15, "Category": "Computers","Author": "Robert C. Martin" }])
   

   显示的结果如下所示：

   {
       "acknowledged" : true,
       "insertedIds" : [
           ObjectId("61a6058e6c43f32854e51f51"),
           ObjectId("61a6058e6c43f32854e51f52")
        ]
    }
   

   注意

   前面结果中显示的 ObjectId 与命令行界面中显示的结果不一致。

5. 使用以下命令查看数据库中的文档：

   db.Books.find().pretty()
   

   显示的结果如下所示：

   {
        "_id" : ObjectId("61a6058e6c43f32854e51f51"),
        "Name" : "Design Patterns",
        "Price" : 54.93,
        "Category" : "Computers",
        "Author" : "Ralph Johnson"
    }
    {
        "_id" : ObjectId("61a6058e6c43f32854e51f52"),
        "Name" : "Clean Code",
        "Price" : 43.15,
        "Category" : "Computers",
        "Author" : "Robert C. Martin"
    }
   

   该架构将为每个文档添加类型 _id 的自动生成的 ObjectId 属性。

创建 ASP.NET Core Web API 项目

Visual Studio

1. 转到“文件”>“新建”>“项目”。
2. 选择“ASP.NET Core Web API”项目类型，然后选择“下一步”。
3. 将项目命名为“BookStoreApi”，然后选择“下一步”。
4. 在“其他信息”对话框中：

• 确认 Framework 为 .NET 9.0（标准期限支持）。
• 确认已选中“使用控制器”复选框。
• 确认已选中“启用 OpenAPI 支持”复选框。
• 选择 创建。

1. 在“包管理器控制台”窗口中，导航到项目根。 运行以下命令以安装适用于 MongoDB 的 .NET 驱动程序：

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. 在命令行界面中运行以下命令：

   dotnet new webapi -o BookStoreApi --use-controllers
   code BookStoreApi
   

   上述命令将生成新的 ASP.NET Core Web API 项目，然后在 Visual Studio Code 中打开该项目。

2. OmniSharp 服务器启动后，对话框将询问“'BookStoreApi' 缺少生成和调试所需的资产。是否添加它们?”。 选择是。

3. 打开“集成终端”并运行以下命令，以安装适用于 MongoDB 的 .NET 驱动程序：

   dotnet add package MongoDB.Driver
   

添加实体模型

1. 将 Models 目录添加到项目根。

2. 使用以下代码将 Book 类添加到 Models 目录：

   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   
   namespace BookStoreApi.Models;
   
   public class Book
   {
       [BsonId]
       [BsonRepresentation(BsonType.ObjectId)]
       public string? Id { get; set; }
   
       [BsonElement("Name")]
       public string BookName { get; set; } = null!;
   
       public decimal Price { get; set; }
   
       public string Category { get; set; } = null!;
   
       public string Author { get; set; } = null!;
   }
   

   在前面的类中，Id 属性为：

   • 需要在将公共语言运行时 (CLR) 对象映射到 MongoDB 集合时使用。
   • 使用 [BsonId] 进行批注，以将此属性指定为文档的主键。
   • 使用 [BsonRepresentation(BsonType.ObjectId)] 进行注释，以允许将参数作为类型 string 而非 ObjectId 结构传递。 Mongo 处理从 string 到 ObjectId 的转换。

   BookName 属性使用 [BsonElement] 特性进行注解。 Name 的属性值表示 MongoDB 集合中的属性名称。

添加配置模型

1. 向 appsettings.json 添加以下数据库配置值：

   {
     "BookStoreDatabase": {
       "ConnectionString": "mongodb://localhost:27017",
       "DatabaseName": "BookStore",
       "BooksCollectionName": "Books"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

2. 使用以下代码将 BookStoreDatabaseSettings 类添加到 Models 目录：

   namespace BookStoreApi.Models;
   
   public class BookStoreDatabaseSettings
   {
       public string ConnectionString { get; set; } = null!;
   
       public string DatabaseName { get; set; } = null!;
   
       public string BooksCollectionName { get; set; } = null!;
   }
   

   前面的 BookStoreDatabaseSettings 类用于存储 appsettings.json 文件的 BookStoreDatabase 属性值。 JSON 和 C# 具有相同的属性名称，目的是简化映射过程。

3. 将以下突出显示的代码添加到 Program.cs：

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   

   在前面的代码中，appsettings.json 文件的 BookStoreDatabase 部分绑定到的配置实例在依赖关系注入 (DI) 容器中注册。 例如，BookStoreDatabaseSettings 对象的 ConnectionString 属性使用 BookStoreDatabase:ConnectionString 中的 appsettings.json 属性进行填充。

4. 将以下代码添加到 Program.cs 的顶部以解析 BookStoreDatabaseSettings 引用：

   using BookStoreApi.Models;
   

添加 CRUD 操作服务

1. 将 Services 目录添加到项目根。

2. 使用以下代码将 BooksService 类添加到 Services 目录：

   using BookStoreApi.Models;
   using Microsoft.Extensions.Options;
   using MongoDB.Driver;
   
   namespace BookStoreApi.Services;
   
   public class BooksService
   {
       private readonly IMongoCollection<Book> _booksCollection;
   
       public BooksService(
           IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
       {
           var mongoClient = new MongoClient(
               bookStoreDatabaseSettings.Value.ConnectionString);
   
           var mongoDatabase = mongoClient.GetDatabase(
               bookStoreDatabaseSettings.Value.DatabaseName);
   
           _booksCollection = mongoDatabase.GetCollection<Book>(
               bookStoreDatabaseSettings.Value.BooksCollectionName);
       }
   
       public async Task<List<Book>> GetAsync() =>
           await _booksCollection.Find(_ => true).ToListAsync();
   
       public async Task<Book?> GetAsync(string id) =>
           await _booksCollection.Find(x => x.Id == id).FirstOrDefaultAsync();
   
       public async Task CreateAsync(Book newBook) =>
           await _booksCollection.InsertOneAsync(newBook);
   
       public async Task UpdateAsync(string id, Book updatedBook) =>
           await _booksCollection.ReplaceOneAsync(x => x.Id == id, updatedBook);
   
       public async Task RemoveAsync(string id) =>
           await _booksCollection.DeleteOneAsync(x => x.Id == id);
   }
   

   在上述代码中，通过构造函数注入从 DI 中检索出了一个 BookStoreDatabaseSettings 实例。 使用此方法可访问在appsettings.json部分添加的 配置值。

3. 将以下突出显示的代码添加到 Program.cs：

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   

   上面的代码向 DI 注册了 BooksService 类，以支持消费类中的构造函数注入。 单例服务生命周期是最合适的，因为 BooksService 直接依赖于 MongoClient。 根据官方 Mongo Client 重用准则，应使用单一实例服务生存期在 DI 中注册 MongoClient。

4. 将以下代码添加到 Program.cs 的顶部以解析 BooksService 引用：

   using BookStoreApi.Services;
   

BooksService 类使用以下 MongoDB.Driver 成员对数据库运行 CRUD 操作：

• MongoClient：读取用于运行数据库操作的服务器实例。 此类的构造函数是在 MongoDB 连接字符串中提供的：

  public BooksService(
      IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
  {
      var mongoClient = new MongoClient(
          bookStoreDatabaseSettings.Value.ConnectionString);
  
      var mongoDatabase = mongoClient.GetDatabase(
          bookStoreDatabaseSettings.Value.DatabaseName);
  
      _booksCollection = mongoDatabase.GetCollection<Book>(
          bookStoreDatabaseSettings.Value.BooksCollectionName);
  }
  

• IMongoDatabase：表示用于运行操作的 Mongo 数据库。 本教程在界面上使用泛型 GetCollection<TDocument>(collection) 方法来获取对特定集合中数据的访问权限。 调用此方法后，对集合运行 CRUD 操作。 在 GetCollection<TDocument>(collection) 方法调用中：

  • collection 表示集合名称。
  • TDocument 表示存储在集合中的 CLR 对象类型。

GetCollection<TDocument>(collection) 返回表示集合的 MongoCollection 对象。 在本教程中，对集合调用以下方法：

• DeleteOneAsync：删除与提供的搜索条件匹配的单个文档。
• Find<TDocument>：返回集合中与提供的搜索条件匹配的所有文档。
• InsertOneAsync：插入提供的对象作为集合中的新文档。
• ReplaceOneAsync：将与提供的搜索条件匹配的单个文档替换为提供的对象。

添加控制器

使用以下代码将 BooksController 类添加到 Controllers 目录：

using BookStoreApi.Models;
using BookStoreApi.Services;
using Microsoft.AspNetCore.Mvc;

namespace BookStoreApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly BooksService _booksService;

    public BooksController(BooksService booksService) =>
        _booksService = booksService;

    [HttpGet]
    public async Task<List<Book>> Get() =>
        await _booksService.GetAsync();

    [HttpGet("{id:length(24)}")]
    public async Task<ActionResult<Book>> Get(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        return book;
    }

    [HttpPost]
    public async Task<IActionResult> Post(Book newBook)
    {
        await _booksService.CreateAsync(newBook);

        return CreatedAtAction(nameof(Get), new { id = newBook.Id }, newBook);
    }

    [HttpPut("{id:length(24)}")]
    public async Task<IActionResult> Update(string id, Book updatedBook)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        updatedBook.Id = book.Id;

        await _booksService.UpdateAsync(id, updatedBook);

        return NoContent();
    }

    [HttpDelete("{id:length(24)}")]
    public async Task<IActionResult> Delete(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        await _booksService.RemoveAsync(id);

        return NoContent();
    }
}

前面的 Web API 控制器：

• 使用 BooksService 类运行 CRUD 操作。
• 包含操作方法以支持 GET、POST、PUT 和 DELETE HTTP 请求。
• 在CreatedAtAction操作方法中调用Create，以返回HTTP 201响应。 状态代码 201 是在服务器上创建新资源的 HTTP POST 方法的标准响应。 CreatedAtAction 还会将 Location 标头添加到响应中。 Location 标头指定新建书籍的 URI。

配置 JSON 序列化选项

关于在测试 Web API 部分中返回的 JSON 响应，有两个细节需要更改：

• 应更改属性名称的默认驼峰式大小写风格，以匹配 CLR 对象属性名称的 Pascal 大小写。
• bookName 属性应作为 Name 返回。

为满足上述要求，请进行以下更改：

1. 在 Program.cs 中，将以下突出显示的代码链接到 AddControllers 方法调用：

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   
   builder.Services.AddControllers()
       .AddJsonOptions(
           options => options.JsonSerializerOptions.PropertyNamingPolicy = null);
   

   通过上述更改，Web API 的序列化 JSON 响应中的属性名称与 CLR 对象类型中其相应的属性名称匹配。 例如，Book 类的 Author 属性序列化为 Author，而不是 author。

2. 在 Models/Book.cs 中，使用 BookName 特性批注 [JsonPropertyName] 属性：

   [BsonElement("Name")]
   [JsonPropertyName("Name")]
   public string BookName { get; set; } = null!;
   

   [JsonPropertyName] 属性的 Name 值表示 Web API 的序列化 JSON 响应中的属性名称。

3. 将以下代码添加到 Models/Book.cs 的顶部以解析 [JsonProperty] 特性引用：

   using System.Text.Json.Serialization;
   

4. 重复测试 Web API 部分中定义的步骤。 注意 JSON 属性名称中的区别。

测试 Web API

Visual Studio

本教程使用终结点资源管理器和 .http 文件来测试 API。

1. 生成并运行应用。

2. 在 终结点资源管理器中，右键单击第一个 GET 终结点 /api/books，然后选择“ 生成请求”。

   以下内容将添加到 BookStoreApi.http 文件。 如果这是首次生成请求，则会在项目根目录中创建该文件。

   @BookStoreApi_HostAddress = https://localhost:<port>
   
   GET {{BookStoreApi_HostAddress}}/api/books
   
   ###
   

   端口号应已设置为应用使用的端口，例如 https://localhost:56874。 如果不是这种情况，可以在启动应用时在输出窗口中找到端口号。

3. 选择新请求行上方的GET”链接。

   GET 请求将发送到应用，响应将显示在“响应”窗格中。

4. 响应正文显示JSON格式的结果，其中包含类似于以下内容的书籍条目：

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

5. 若要检索单个书籍，请在/api/books/{id}, params (string id)终结点资源管理器中右键单击 GET 终结点，然后选择“生成请求”。

   以下内容将追加到 BookStoreApi.http 该文件中：

   @id=string
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

6. 将变量替换为 id 先前请求返回的 ID 之一，例如：

   @id="61a6058e6c43f32854e51f52"
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

7. 选择新请求行上方的GET”链接。

   GET 请求将发送到应用，响应将显示在“响应”窗格中。

8. 在响应正文中可以看到类似于以下内容的 JSON：

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. 若要测试 POST 终结点，请/api/books右键单击 POST 终结点并选择“生成请求”。

   将以下内容添加到 BookStoreApi.http 文件中：

   POST {{BookStoreApi_HostAddress}}/api/books
   Content-Type: application/json
   
   {
     //Book
   }
   
   ###
   

10. 将 Book 注释替换为书籍对象作为 JSON 请求正文：

    POST {{BookStoreApi_HostAddress}}/api/books
    Content-Type: application/json
    
     {
       "Name": "The Pragmatic Programmer",
       "Price": 49.99,
       "Category": "Computers",
       "Author": "Andy Hunt"
     }
    
    ###
    

11. 选择请求行上方的POST”链接。

    POST 请求将发送到应用，响应将显示在 “响应 ”窗格中。 响应应包含新创建的书籍及其分配的 ID。

12. 最后，若要删除书籍，请/api/books/{id}, params (string id)右键单击 DELETE 终结点并选择“生成请求”。

    以下内容将追加到 BookStoreApi.http 该文件中：

    DELETE {{BookStoreApi_HostAddress}}/api/Books/{{id}}
    
    ###
    

13. 将 id 变量替换为前面请求返回的 ID 之一，然后单击“ 发送”请求。 例如：

    DELETE {{BookStoreApi_HostAddress}}/api/Books/67f417517ce1b36aeab71236
    
    ###
    

Visual Studio Code

本教程使用 OpenAPI 规范（openapi.json）和 Swagger UI 测试 API。

1. 运行以下命令安装 Swagger UI：

dotnet add package NSwag.AspNetCore

上一个命令添加了 NSwag.AspNetCore 包，其中包含用于生成 Swagger 文档和 UI 的工具。 因为我们的项目使用 OpenAPI，所以我们只使用 NSwag 包来生成 Swagger UI。

1. 配置 Swagger 中间件

在 Program.cs 中，添加以下突出显示的代码：

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });
}

前面的代码使 Swagger 中间件能够使用 Swagger UI 为生成的 JSON 文档提供服务。 Swagger 仅在开发环境中启用。 在生产环境中启用 Swagger 可能会公开有关 API 结构和实现的潜在敏感详细信息。

该应用使用 OpenAPI 生成的 OpenAPI 文档（位于 /openapi/v1.json）来生成 UI。 在项目运行时，通过在浏览器中导航到 WeatherForecast，查看为 https://localhost:<port>/openapi/v1.json API 生成的 OpenAPI 规范。

OpenAPI 规范是一个 JSON 格式的文档，它描述了 API 的结构和功能，包括终结点、请求/响应格式、参数等。 它本质上是 API 的蓝图，各种工具可以使用它来理解 API 并与之交互。

1. 生成并运行应用。

2. 在浏览器中，导航到 https://localhost:<port>/swagger。 Swagger 提供了一个 UI，用于基于 OpenAPI 文档测试所有 API 终结点。

3. 展开 GET /api/books 终结点，然后单击“ 试用” 按钮。

4. 单击“ 执行 ”按钮，将请求发送到 API。

5. “响应正文”部分显示一个 JSON 数组，其中包含类似于以下内容的书籍：

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

6. 接下来，展开 GET /api/books/{id} 端点，然后单击「试用」。

7. 在 ID 字段中输入上一个响应中的书籍 ID，然后单击“ 执行”。

8. “响应正文”部分显示指定书籍的 JSON 对象。 例如，ID 61a6058e6c43f32854e51f52 的结果类似于以下内容：

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. 若要测试创建新书籍，请展开 POST /api/books 终结点，然后单击“ 试用”。

10. 将默认请求正文替换为新的书籍对象：

    {
      "Name": "The Pragmatic Programmer",
      "Price": 49.99,
      "Category": "Computers",
      "Author": "Andy Hunt"
    }
    

11. 单击“ 执行 ”以发送请求。

12. 响应应具有状态代码 201（已创建），并在响应正文中包含新创建的书籍及其分配的 ID。

13. 最后，若要删除书籍记录，请展开 DELETE /api/books/{id} 端点，单击 试用，然后在 ID 字段中输入上一个响应中的书籍 ID。 单击“ 执行 ”以发送请求。

14. 响应应具有状态代码 204（无内容），指示已成功删除书籍。

向 Web API 添加身份验证支持

ASP.NET Core Identity 将用户界面 (UI) 登录功能添加到 ASP.NET Core Web 应用。 若要保护 Web API 和 SPA，请使用以下项之一：

• Microsoft Entra ID
• Azure Active Directory B2C （Azure AD B2C）
• Duende Identity 服务器

Duende Identity Server 是适用于 ASP.NET Core 的 OpenID Connect 和 OAuth 2.0 框架。 Duende Identity Server 支持以下安全功能：

• 身份验证即服务 (AaaS)
• 跨多个应用程序类型的单一登录/注销 (SSO)
• API 的访问控制
• 联盟网关

重要

Duende Software 可能会要求你为 Duende Identity Server 的生产使用支付许可证费用。 有关详细信息，请参阅 从 .NET 5 中的 ASP.NET Core 迁移到 .NET 6。

有关详细信息，请参阅 Duende Identity Server 文档（Duende Software 网站）。

其他资源

• 查看或下载示例代码（如何下载）
• 使用 ASP.NET Core 创建 Web API
• ASP.NET Core Web API 中控制器操作的返回类型
• 使用 ASP.NET Core 创建 Web API