.NET Aspire MySQL 整合

發行項
01/22/2025

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

主機整合

MySQL 的托管整合將伺服器模型化為 MySqlServerResource 類型，並將資料庫模型化為 MySqlDatabaseResource 類型。若要存取這些類型和 API，請新增 📦Aspire。Hosting.MySql 應用程式主機專案中的 NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MySql

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

如需詳細資訊，請參閱使用 dotnet 新增套件或在 .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，還有使用 CreateDefaultPasswordParameter 方法產生的隨機 password。

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

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

參數的名稱是 mysql-password，但實際上只是使用 -password 後綴來格式化資源名稱。如需詳細資訊，請參閱中開發環境下應用程式秘密的安全儲存，亦可參閱 ASP.NET Core 和關於使用參數新增 MySQL 資源的資訊。

WithReference 方法會在名為 mysqldb的 ExampleProject 中設定連接。

提示

如果您想要連線到現有的 MySQL 伺服器，請改為呼叫 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...

數據磁碟區用來將 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 數據。資料綁定掛載會在 MySQL 容器中掛載於主機的 C:\MySql\Data 路徑上（或 Unix的 /MySql/Data 路徑上）。如需資料系結掛接的詳細資訊，請參閱 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...

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

主機託管整合健康檢測

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

裝載整合依賴 📦 AspNetCore.HealthChecks.MySql NuGet 套件。

Client 整合

若要開始使用 .NET AspireMySQL 資料庫整合，請安裝 📦Aspire。MySqlConnector 用戶端取用專案中的 NuGet 套件，也就是使用 MySQL 用戶端的應用程式專案。 MySQL 用戶端整合會註冊可用來與 MySQL 伺服器互動的 MySqlConnector.MySqlDataSource 實例。

.NET CLI
PackageReference

dotnet add package Aspire.MySqlConnector

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

如需詳細資訊，請參閱使用 dotnet 新增套件或在 .NET 應用程式中管理套件相依性。

新增 MySQL 數據源

在用戶端取用專案的 Program.cs 檔案中，呼叫 AddMySqlDataSource 擴充方法來註冊 MySqlDataSource，以透過相依性插入容器使用。方法會採用 connectionName 參數。

builder.AddMySqlDataSource(connectionName: "mysqldb");

提示

connectionName 參數必須符合在應用程式主專案中新增 MySQL 資料庫資源時所使用的名稱。換句話說，當您呼叫 AddDatabase 並提供名稱 mysqldb 時，呼叫 AddMySqlDataSource時應該使用相同的名稱。如需進一步的資訊，請參閱添加 MySQL 伺服器資源及資料庫資源。

接著，您可以使用依賴注入來擷取 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

共用方式為