.NET Aspire Pomelo MySQLEntity Framework Core 集成

包含： - Client 集成

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

托管集成

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

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

当 .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 资源

若要将数据卷添加到 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客户端的应用程序项目中安装 NuGet 包。

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");

从服务检索 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.")));

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

• 可以重复使用数据库上下文的现有配置代码，而无需为 .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

另请参阅

• MySQL 数据库
• Entity Framework Core 文档
• .NET .NET Aspire 集成
• .NET Aspire GitHub 回购