.NET Aspire 柚子 MySQLEntity Framework Core 整合

發行項
12/13/2024

MySQL 是開放原始碼的關係資料庫管理系統（RDBMS），使用結構化查詢語言（SQL）來管理及操作數據。它採用於許多不同的環境中，從小型專案到大型企業系統，也是裝載雲端原生應用程式中微服務基礎的熱門選擇。 Pomelo MySQLEntity Framework Core 整合 .NET Aspire 可讓您連線到現有的 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 資源包含具有 rootusername 的預設認證，以及使用 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 數據保存在其容器生命週期之外。數據磁碟區會掛接在 /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...

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

托管整合健康檢查

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

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

Client 整合

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

.NET CLI
PackageReference

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

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

新增 MySQL 資料庫上下文

在 client取用專案的 Program.cs 檔案中，在任何 IHostApplicationBuilder 上呼叫 AddMySqlDbContext 擴充方法，以註冊 DbContext，以透過相依性插入容器使用。方法會採用連接名稱參數。

builder.AddMySqlDbContext<ExampleDbContext>(connectionName: "mysqldb");

提示

connectionName 參數必須符合在應用程式主專案中新增 SQL Server 資料庫資源時所使用的名稱。換句話說，當您呼叫 AddDatabase 並提供名稱 mysqldb 時，在呼叫 AddMySqlDbContext時應該使用相同的名稱。如需詳細資訊，請參閱新增 MySQLserver 資源和資料庫資源。

若要從服務擷取 ExampleDbContext 物件：

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增一個內容豐富的 MySQL 資料庫上下文

若要透過其他服務來豐富 DbContext，例如自動重試、健康檢查、日誌記錄和遙測，請呼叫 EnrichMySqlDbContext 方法：

builder.EnrichMySqlDbContext<ExampleDbContext>(
    connectionName: "mysqldb",
    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。它會從設定檔，如 appsettings.json，使用 Aspire:Pomelo:EntityFrameworkCore:MySql 金鑰載入 PomeloEntityFrameworkCoreMySqlSettings。

下列範例顯示可設定一些可用選項的 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);

健康檢查

預設狀態下，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.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

共用方式為