次の方法で共有

.NET Aspire Pomelo MySQLEntity Framework Core の統合

  • [アーティクル]

含まれるもの:ホスティングインテグレーション と Client 連携

MySQL は、構造化クエリ言語 (SQL) を使用してデータを管理および操作するオープンソースのリレーショナル データベース管理システム (RDBMS) です。 小規模プロジェクトから大規模なエンタープライズ システムまで、さまざまな環境で採用されており、クラウドネイティブ アプリケーションでマイクロサービスを支えるデータをホストすることが一般的な選択肢です。 .NET Aspire Pomelo MySQLEntity Framework Core 統合を使用すると、既存の MySQL データベースに接続したり、.NETを使用して mysql から新しいインスタンスを作成したりできます。

ホスティング統合

MySQL ホスティング統合は、サーバーを MySqlServerResource の種類として、データベースを MySqlDatabaseResource の種類としてモデル化します。 これらの型と API にアクセスするには、📦Aspireを追加します。アプリ ホスト プロジェクト内の Hosting.MySql NuGet パッケージ。

dotnet add package Aspire.Hosting.MySql

詳細については、「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 リソースには、username の root を持つ既定の資格情報と、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 コンテナー内のホスト コンピューター上の Windows 上の /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...

ソリューションを実行すると、.NET.NET Aspire ダッシュボードに、エンドポイントを含む phpMyAdmin リソースが表示されます。 エンドポイントへのリンクを選択して、新しいブラウザー タブで phpMyAdmin を表示します。

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

MySQL ホスティング統合により、MySQL リソースの正常性チェックが自動的に追加されます。 正常性チェックでは、MySQL サーバーが実行されていること、およびサーバーへの接続を確立できることを確認します。

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

Client 統合

.NET Aspire Pomelo MySQL Entity Framework の統合を開始するには、📦Aspire.Pomelo.EntityFrameworkCore.MySql NuGet パッケージを、クライアントを使用するプロジェクト、つまり MySQLEntity Framework Core クライアントを使用するアプリケーションのプロジェクトにインストールします。

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

詳細については、「dotnet パッケージ の追加」または「.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 の ドキュメントを参照してください。

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

Pomelo .NET AspireMySQL 統合 Entity 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 Aspire、Pomelo、MySQL、Entity Framework Core の統合:

  • PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks が falseされたときに正常性チェックを追加し、EF Core's CanConnectAsync メソッドを呼び出します。
  • /health HTTP エンドポイントと統合されます。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

Pomelo .NET AspireMySQL 統合 Entity 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

関連項目