.NET Aspire MySQL 集成

项目
12/16/2024

MySQL 是一种开源关系数据库管理系统（RDBMS），它使用结构化查询语言（SQL）管理和操作数据。它在许多不同的环境中使用，从小型项目到大型企业系统，也是在云原生应用程序中托管微服务的基础数据的常用选择。通过 .NET AspireMySQL 数据库集成，可以连接到现有 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 add package 或在 .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 AspireMySQL 数据库集成，请在 client消费项目中安装 📦Aspire.MySqlConnector NuGet 包，即应用程序使用 MySQLclient的项目。 MySQL client 集成注册了一个 MySqlConnector.MySqlDataSource 实例，您可以用它来与 MySQLserver交互。

.NET CLI
PackageReference

dotnet add package Aspire.MySqlConnector

<PackageReference Include="Aspire.MySqlConnector"
                  Version="*" />

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

添加 MySQL 数据源

在 client使用项目的 Program.cs 文件中，调用 AddMySqlDataSource 扩展方法以注册 MySqlDataSource，以便通过依赖项注入容器使用。该方法采用 connectionName 参数。

builder.AddMySqlDataSource(connectionName: "mysqldb");

提示

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

然后，可以使用依赖项注入检索 MySqlConnector.MySqlDataSource 实例。例如，若要从示例服务检索数据源：

public class ExampleService(MySqlDataSource dataSource)
{
    // Use dataSource...
}

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

添加键 MySQL 数据源

在某些情况下，可能需要使用不同的连接名称注册多个 MySqlDataSource 实例。若要注册密钥 MySQL 数据源，请调用 AddKeyedMySqlDataSource 方法：

builder.AddKeyedMySqlDataSource(name: "mainDb");
builder.AddKeyedMySqlDataSource(name: "loggingDb");

重要

当使用密钥服务时，预计您的 MySQL 资源配置了两个命名数据库，一个用于 mainDb，一个用于 loggingDb。

然后，可以使用依赖项注入检索 MySqlDatSource 实例。例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("mainDb")] MySqlDataSource mainDbConnection,
    [FromKeyedServices("loggingDb")] MySqlDataSource loggingDbConnection)
{
    // Use connections...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

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

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddMySqlDataSource 方法时提供连接字符串的名称：

builder.AddMySqlDataSource(connectionName: "mysql");

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

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

有关如何设置此连接字符串的格式的详细信息，请参阅 MySqlConnector：ConnectionString 文档。

使用配置提供程序

.NET Aspire MySQL 数据库集成支持 Microsoft.Extensions.Configuration。它使用 Aspire:MySqlConnector 键来从配置中加载 MySqlConnectorSettings。以下代码片段是用于配置一些选项的 appsettings.json 文件示例。

{
  "Aspire": {
    "MySqlConnector": {
      "ConnectionString": "YOUR_CONNECTIONSTRING",
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}

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

使用内联委托

您还可以传递 Action<MySqlConnectorSettings> 委托，在代码中设置一些或所有选项，例如禁用健康检查：

builder.AddMySqlDataSource(
    "mysql",
    static settings => settings.DisableHealthChecks  = true);

Client 集成健康检查

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

.NET Aspire MySQL 数据库集成：

当 MySqlConnectorSettings.DisableHealthChecks 是 false时，添加运行状况检查，以验证是否能够建立连接，并且能对 MySQL 数据库执行命令。
与 /health HTTP 终结点集成，该终结点指定所有已注册的运行状况检查都必须通过，才能让应用被视为可以接受流量。

可观测性和遥测

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

伐木

.NET Aspire MySQL 集成使用以下日志类别：

MySqlConnector.ConnectionPool
MySqlConnector.MySqlBulkCopy
MySqlConnector.MySqlCommand
MySqlConnector.MySqlConnection
MySqlConnector.MySqlDataSource

追踪

.NET Aspire MySQL 集成使用 OpenTelemetry发出以下跟踪活动：

MySqlConnector

指标

.NET Aspire MySQL 集成将使用 OpenTelemetry发出以下指标：

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

通过