.NET Aspire Pomelo MySQLEntity Framework Core 集成

项目
12/15/2024

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

托管集成

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MySql

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

有关详细信息，请参阅使用 dotnet 添加包或管理 .NET 应用程序中的包依赖项。

添加 MySQLserver 资源和数据库资源

在应用主机项目中，调用 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，并且使用 CreateDefaultPasswordParameter 方法生成了随机的 password。

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

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

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

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

提示

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

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

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

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...

数据卷用于在容器的生命周期之外保留 MySQLserver 数据。数据卷装载在 SQL Server 容器的 /var/lib/mysql 路径，当未提供 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（或 Unix上的 /MySql/Data）路径，在主机的 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 资源添加运行状况检查。对运行状况的检查会验证 MySQLserver 是否正在运行，并且是否能够建立连接。

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

Client 集成

若要开始使用 .NET Aspire Pomelo MySQL Entity Framework 集成，请安装 📦Aspire。Pomelo.EntityFrameworkCore。MySql 使用 client项目中的 NuGet 包，即使用 MySQLEntity Framework Coreclient的应用程序的项目。

.NET CLI
PackageReference

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

有关详细信息，请参阅使用 dotnet 添加包或管理 .NET 应用程序中的包依赖项。

添加 MySQL 数据库上下文

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

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

提示

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

从服务检索 ExampleDbContext 对象：

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

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

使用扩充添加 MySQL 数据库上下文

若要通过附加服务（例如自动重试、运行状况检查、日志记录和遥测）充实 DbContext，请调用 EnrichMySqlDbContext 方法：

builder.EnrichMySqlDbContext<ExampleDbContext>(
    connectionName: "mysqldb",
    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。它通过使用 Aspire:Pomelo:EntityFrameworkCore:MySql 键从配置文件（例如 appsettings.json）中加载 PomeloEntityFrameworkCoreMySqlSettings。

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

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

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

使用内联委托功能

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

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

或

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

健康检查

默认情况下，.NET.NET Aspire 集成为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.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

通过