.NET Aspire MySQL 整合

包括：主機整合 和 Client 整合

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

主機整合

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

.NET CLI

dotnet add package Aspire.Hosting.MySql

PackageReference

<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 資源包含預設憑證，其中root 為 username，並且使用 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 數據。 資料綁定掛載會在 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 資源新增健康檢查。 健康檢查會確認 MySQLserver 正在執行狀態，而且可以建立連線。

主控整合依賴 📦 AspNetCore.HealthChecks。MySql NuGet 套件。

Client 整合

若要開始進行 .NET AspireMySQL 資料庫整合，請在 client消費專案中安裝 📦Aspire的 MySqlConnector NuGet 套件，也就是該專案應用程式所使用的 MySQLclient。 MySQL client 整合會註冊 MySqlConnector.MySqlDataSource 實例，讓您可用來與 MySQLserver互動。

.NET CLI

dotnet add package Aspire.MySqlConnector

PackageReference

<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

另請參閱

• MySQL 資料庫
• .NET .NET Aspire 資料庫容器範例
• .NET .NET Aspire 整合
• .NET Aspire GitHub 存放庫