.NET Aspire 柚子 MySQLEntity Framework Core 整合

發行項
02/21/2025

MySQL 是開放原始碼的關係資料庫管理系統（RDBMS），使用結構化查詢語言（SQL）來管理及操作數據。它採用於許多不同的環境中，從小型專案到大型企業系統，也是裝載雲端原生應用程式中微服務基礎的熱門選擇。 Pomelo .NET AspireMySQL 整合 Entity Framework Core 可讓您連線到現有的 MySQL 資料庫，或使用 .NET從 mysql 建立新的實例。

主機整合

託管整合 MySQL 會將伺服器模型化為 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 應用程式中管理套件相依性。

新增 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 資源包含具有 usernameroot 的預設認證，以及使用 password 方法產生的隨機 CreateDefaultPasswordParameter。

當應用程式主機執行時，密碼會儲存在應用程式主機的秘密存放區中。它會被添加到 Parameters 區段，例如：

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

參數的名稱是 mysql-password，但實際上只是使用 -password 後綴來格式化資源名稱。如需詳細資訊，請參閱在開發中安全儲存應用程式機密的方式，以及 ASP.NET Core 和中如何使用參數新增 MySQL 資源。

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 數據。數據綁定會掛載在 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 是適用於 MySQL的熱門 Web 管理工具。您可以使用它來流覽和修改 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...

當您執行解決方案時，phpMyAdmin 資源以及端點會顯示在 .NET.NET Aspire 儀錶板上。選取端點的連結，以在新瀏覽器索引標籤中檢視 phpMyAdmin。

托管整合健康檢查

MySQL 裝載整合會自動新增 MySQL 資源的健康檢查。健康檢查會確認 MySQL 伺服器正在運行，而且可以建立連線。

託管整合依賴 📦 AspNetCore.HealthChecks.MySql NuGet 套件。

Client 整合

若要開始使用 .NET Aspire Pomelo MySQL Entity Framework 整合，請安裝 📦Aspire。Pomelo.EntityFrameworkCore.MySql 用戶端取用專案中的 NuGet 套件，也就是使用 MySQLEntity Framework Core 客戶端的應用程式專案。

.NET CLI
PackageReference

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代管整合也會啟用健康檢查端點。如需詳細資訊，請參閱：

.NET 在 C# 中應用程式健康情況檢查
中的健康情況檢查

.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

共用方式為