.NET Aspire MySQL 統合

[アーティクル]
12/13/2024

MySQL は、構造化クエリ言語 (SQL) を使用してデータを管理および操作するオープンソースのリレーショナルデータベース管理システム (RDBMS) です。小規模プロジェクトから大規模なエンタープライズシステムまで、さまざまな環境で採用されており、クラウドネイティブアプリケーションでマイクロサービスを支えるデータをホストすることが一般的な選択肢です。 .NET Aspire MySQL データベース統合を使用すると、既存の 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 パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

MySQL server リソースとデータベースリソースを追加する

アプリホストプロジェクトで、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 サフィックスで書式設定するだけです。詳細については、の「開発中のアプリシークレットの安全なストレージ」と、の「パラメーターを使用したリソースの追加」を参照してください。

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 コンテナー内のホストコンピューター上の Windows 上の 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 が実行されていることと、MySQLserver への接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks NuGet パッケージMySql に依存します。

Client 統合

.NET Aspire MySQL データベース統合を開始するには、📦Aspireをインストールします。MySqlConnector、clientを使用するプロジェクト、つまり、MySQLclientを使用するアプリケーションのプロジェクト内の NuGet パッケージです。 MySQL client 統合により、MySQLserverとの対話に使用できる MySqlConnector.MySqlDataSource インスタンスが登録されます。

.NET CLI
PackageReference

dotnet add package Aspire.MySqlConnector

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

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

MySQL データソースを追加する

client-consuming プロジェクトの 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用の 2 つの名前付きデータベースが構成されている必要があります。

その後、依存関係の挿入を使用して 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 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

次の方法で共有

.NET Aspire MySQL 統合

ホスティング統合

MySQL server リソースとデータベースリソースを追加する

データボリュームを持つ MySQL リソースを追加する

データバインドマウントを使用して MySQL リソースを追加する

パラメーター付きのMySQLリソースを追加する

PhpMyAdmin リソースを追加する

ホスティング統合の正常性チェック

Client 統合

MySQL データソースを追加する

キー付き MySQL データソースを追加する

構成

接続文字列を使用する

構成プロバイダーを使用する

インラインデリゲートを使用する

Client統合のヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

参照

その他のリソース

次の方法で共有

.NET Aspire MySQL 統合

ホスティング統合

MySQL server リソースとデータベース リソースを追加する

データ ボリュームを持つ MySQL リソースを追加する

データ バインド マウントを使用して MySQL リソースを追加する

パラメーター付きのMySQLリソースを追加する

PhpMyAdmin リソースを追加する

ホスティング統合の正常性チェック

Client 統合

MySQL データ ソースを追加する

キー付き MySQL データ ソースを追加する

構成

接続文字列を使用する

構成プロバイダーを使用する

インライン デリゲートを使用する

Client統合のヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

参照

その他のリソース

MySQL server リソースとデータベースリソースを追加する

データボリュームを持つ MySQL リソースを追加する

データバインドマウントを使用して MySQL リソースを追加する

MySQL データソースを追加する

キー付き MySQL データソースを追加する

インラインデリゲートを使用する