.NET Aspire Pomelo MySQLEntity Framework Core 集成

2025-05-20

包含： - Client 集成

MySQL 是一种开源关系数据库管理系统（RDBMS），它使用结构化查询语言（SQL）管理和操作数据。它在许多不同的环境中使用，从小型项目到大型企业系统，也是在云原生应用程序中托管微服务的基础数据的常用选择。 .NET Aspire Pomelo MySQLEntity Framework Core 集成使你能够连接到现有的 MySQL 数据库，或使用 .NET从 mysql 创建新实例。

托管集成

托管集成 MySQL 将服务器建模为 MySqlServerResource 类型和数据库作为 MySqlDatabaseResource 类型。若要访问这些类型和 API，请在📦项目中添加Aspire .Hosting.MySql NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.MySql

<PackageReference Include="Aspire.Hosting.MySql"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或在.NET应用中管理包依赖项。

添加 MySQL 服务器资源和数据库资源

在应用主机项目中，调用 AddMySql 添加并返回 MySQL 资源生成器。将返回的资源生成器的调用链接到 AddDatabase，以添加 MySQL 数据库资源。

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithLifetime(ContainerLifetime.Persistent);

var mysqldb = mysql.AddDatabase("mysqldb");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(mysqldb)
                       .WaitFor(mysqldb);

// After adding all resources, run the app...

注意

容器 SQL Server 启动速度较慢，因此最好使用 持久性 生存期以避免不必要的重启。有关详细信息，请参阅容器资源生存期。

当 .NET.NET Aspire 向应用主机添加容器映像时，如前例中提到的 mysql 映像所示，它会在你的本地计算机上创建新的 MySQL 实例。对 MySQL 资源生成器（mysql 变量）的引用用于添加数据库。数据库命名为 mysqldb，然后添加到 ExampleProject。 MySQL 资源包括默认凭据，其中username 为 root，并且使用 password 方法生成了随机的 CreateDefaultPasswordParameter。

应用主机运行时，密码存储在应用主机的机密存储中。它已添加到 Parameters 部分，例如：

{
  "Parameters:mysql-password": "<THE_GENERATED_PASSWORD>"
}

参数的名称是 mysql-password，但实际上只是将资源名称格式化为带有 -password 后缀的形式。有关详细信息，请参阅在开发中安全存储应用机密，以及使用参数添加资源。

WithReference 方法在名为 ExampleProject的 mysqldb 中配置连接。

提示

如果想要连接到现有 MySQL 服务器，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

添加一个带数据卷的 MySQL 资源

若要将数据卷添加到 SQL Server 资源，请在 WithDataVolume 资源上调用 SQL Server 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithDataVolume();

var mysqldb = mysql.AddDatabase("mysqldb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mysqldb)
       .WaitFor(mysqldb);

// After adding all resources, run the app...

数据卷用于在其容器生命周期之外保留 MySQL 服务器数据。数据卷装载在 /var/lib/mysql 容器的 SQL Server 路径，当未提供 name 参数时，名称会被随机生成。有关数据卷的更多信息，以及它们为何比绑定装载更受欢迎，请参阅Docker文档：卷。

警告

密码存储在数据卷中。使用数据卷时，如果密码发生更改，则在删除卷之前，它将无法正常工作。

添加一个带数据绑定装载的 MySQL 资源

若要将数据绑定装载添加到 MySQL 资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithDataBindMount(source: @"C:\MySql\Data");

var db = sql.AddDatabase("mysqldb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mysqldb)
       .WaitFor(mysqldb);

// After adding all resources, run the app...

重要

与卷相比，绑定装载的数据功能有限，从而提供更好的性能、可移植性和安全性，使它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定挂载依赖于主机的文件系统在容器重启期间持久化 MySQL 数据。数据绑定装载在 Windows 上的 C:\MySql\Data（或 /MySql/Data上的 Unix）路径，在主机的 MySQL 容器中。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

使用参数添加 MySQL 资源

如果要显式提供根 MySQL 密码，则可以将其作为参数传递。请考虑以下替代示例：

var password = builder.AddParameter("password", secret: true);

var mysql = builder.AddMySql("mysql", password)
                   .WithLifetime(ContainerLifetime.Persistent);

var mysqldb = mysql.AddDatabase("mysqldb");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(mysqldb)
                       .WaitFor(mysqldb);

有关详细信息，请参阅外部参数。

添加 PhpMyAdmin 资源

phpMyAdmin 是一种常用的基于 Web 的 MySQL管理工具。可以使用它浏览和修改 MySQL 对象，例如数据库、表、视图和索引。若要在 .NET.NET Aspire 解决方案中使用 phpMyAdmin，请调用 WithPhpMyAdmin 方法。此方法将新的容器资源添加到托管 phpMyAdmin 的解决方案，并将其连接到 MySQL 容器：

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithPhpMyAdmin();

var db = sql.AddDatabase("mysqldb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mysqldb)
       .WaitFor(mysqldb);

// After adding all resources, run the app...

运行解决方案时，.NET.NET Aspire 仪表板会显示 phpMyAdmin 资源及其终结点。选择指向终结点的链接，在新浏览器选项卡中查看 phpMyAdmin。

托管环境集成运行状况检查

托管集成 MySQL 会自动为 MySQL 资源添加运行状况检查。运行状况检查验证 MySQL 服务器是否正在运行，并且可以建立与服务器的连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.MySql NuGet 包。

Client 集成

若要开始使用 .NET Aspire Pomelo MySQL Entity Framework 集成，请在使用📦Aspire客户端的应用程序项目中安装 Entity Framework Core NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

<PackageReference Include="Aspire.Pomelo.EntityFrameworkCore.MySql"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或在.NET应用中管理包依赖项。

添加 MySQL 数据库上下文

在客户端使用项目的 Program.cs 文件中，对任何 AddMySqlDbContext 调用 IHostApplicationBuilder 扩展方法，以注册 DbContext，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddMySqlDbContext<ExampleDbContext>(connectionName: "mysqldb");

提示

connectionName 参数必须与在应用主机项目中添加 SQL Server 数据库资源时使用的名称匹配。换句话说，当调用 AddDatabase 时，提供的 mysqldb 名称应该在调用 AddMySqlDbContext时使用。有关详细信息，请参阅添加 MySQL 服务器资源和数据库资源。

从服务检索 ExampleDbContext 对象：

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

充实 MySQL 数据库上下文

你可能更喜欢使用标准 Entity Framework 方法获取数据库上下文并将其添加到依赖项注入容器：

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseMySql(builder.Configuration.GetConnectionString("mysqldb")
        ?? throw new InvalidOperationException("Connection string 'mysqldb' not found.")));

注意

传递给 GetConnectionString 方法的连接字符串名称必须与在应用主机项目中添加 MySQL 资源时使用的名称匹配。有关详细信息，请参阅添加 MySQL 服务器资源和数据库资源。

以这种方式创建数据库上下文时具有更大的灵活性，例如：

可以重复使用数据库上下文的现有配置代码，而无需为 .NET.NET Aspire重写它。
可以使用 Entity Framework Core 拦截器来修改数据库操作。
可以选择不使用 Entity Framework Core 上下文池，在某些情况下性能可能更好。

如果使用此方法，可以通过调用 .NET 方法来增强数据库上下文，增强功能包括 .NET AspireEnrichMySqlDbContext样式的重试、运行状况检查、日志记录和遥测功能。

builder.EnrichMySqlDbContext<ExampleDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

settings 参数是 PomeloEntityFrameworkCoreMySqlSettings 类的实例。

配置

.NET Aspire Pomelo MySQLEntity Framework Core 集成提供了多个选项，用于根据项目的要求和约定配置数据库连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 builder.AddMySqlDatabaseDbContext<TContext>()时提供连接字符串的名称：

builder.AddMySqlDatabaseDbContext<MyDbContext>("mysql");

然后，将从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "mysql": "Server=mysql;Database=mysqldb"
  }
}

EnrichMySqlDbContext 不会使用 ConnectionStrings 配置部分，因为当调用时，它需要 DbContext 已经被注册。

有关详细信息，请参阅 MySqlConnector：ConnectionString 文档。

使用配置提供程序

.NET Aspire Pomelo MySQLEntity Framework Core 集成支持 Microsoft.Extensions.Configuration。它通过使用 PomeloEntityFrameworkCoreMySqlSettings 键从配置文件（例如 appsettings.json）中加载 Aspire:Pomelo:EntityFrameworkCore:MySql。

以下示例展示了一个 appsettings.json，它配置了一些可用选项。

{
  "Aspire": {
    "Pomelo": {
      "EntityFrameworkCore": {
        "MySql": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

有关完整的 MySQL 集成 JSON 架构，请参阅 Aspire。Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json。

使用内联委托功能

还可以传递 Action<PomeloEntityFrameworkCoreMySqlSettings> 委托来设置一些或所有内联选项，例如禁用代码中的运行状况检查：

builder.AddMySqlDbContext<MyDbContext>(
    "mysqldb",
    static settings => settings.DisableHealthChecks = true);

或

builder.EnrichMySqlDbContext<MyDbContext>(
    static settings => settings.DisableHealthChecks = true);

Client 整合健康检查

默认情况下， .NET.NET Aspire客户端集成为所有服务启用了运行状况检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# .NET 应用运行状况检查
健康检查 ASP.NET Core

.NET Aspire Pomelo MySQLEntity Framework Core 集成：

当 PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks 为 false时，添加运行状况检查，该检查调用 EF Core的 CanConnectAsync 方法。
与 /health HTTP 端点集成，该端点规定所有注册的健康检查必须通过，应用才能被视为已准备好接收流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Pomelo MySQLEntity Framework Core 集成使用以下日志类别：

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Model
Microsoft.EntityFrameworkCore.Model.Validation
Microsoft.EntityFrameworkCore.Query
Microsoft.EntityFrameworkCore.Update

追踪

.NET Aspire Pomelo MySQLEntity Framework Core 集成将使用 OpenTelemetry发出以下跟踪活动：

MySqlConnector

指标

.NET Aspire Pomelo MySQLEntity Framework Core 集成目前支持以下指标：

MySqlConnector：
- db.client.connections.create_time
- db.client.connections.use_time
- db.client.connections.wait_time
- db.client.connections.idle.max
- db.client.connections.idle.min
- db.client.connections.max
- db.client.connections.pending_requests
- db.client.connections.timeouts
- db.client.connections.usage

通过