.NET Aspire SQL Server Entity Framework Core 統合

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

SQL Server は、Microsoft によって開発されたリレーショナルデータベース管理システムです。 .NET Aspire SQL Server Entity Framework Core 統合を使用すると、既存の SQL Server インスタンスに接続したり、mcr.microsoft.com/mssql/server コンテナーイメージを使用して .NET から新しいインスタンスを作成したりできます。

ホスティング統合

SQL Server ホスティング統合では、server が SqlServerServerResource の種類として、データベースが SqlServerDatabaseResource の種類としてモデル化されます。これらの型と API にアクセスするには、📦Aspireを追加します。Hosting.SqlServer NuGet パッケージをアプリホストプロジェクトに含めます。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

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

SQL Serverリソースとデータベースリソースを追加する

アプリホストプロジェクトで、AddSqlServer を呼び出して、SQL Server リソースビルダーを追加して返します。返されたリソースビルダーを使って呼び出しをチェーンし、AddDatabaseを通じてデータベースリソース SQL Server を追加します。

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

手記

SQL Server コンテナーの起動に時間がかかるため、不要な再起動を避けるために、永続的な の有効期間を使用することをお勧めします。詳細については、「コンテナーリソースの有効期間」を参照してください。

.NET .NET Aspire 前の例で示したように、mcr.microsoft.com/mssql/server イメージでコンテナーイメージをアプリホストに追加すると、ローカルコンピューターに新しい SQL Server インスタンスが作成されます。データベースの追加には、SQL Server リソースビルダー (sql 変数) への参照が使用されます。データベースには database という名前が付けられ、ExampleProjectに追加されます。 SQL Server リソースには、sa の username を持つ既定の資格情報と、CreateDefaultPasswordParameter メソッドを使用して生成されたランダムな password が含まれます。

アプリホストを実行すると、パスワードはアプリホストのシークレットストアに格納されます。次のように、Parameters セクションに追加されます。

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

パラメーターの名前は sql-passwordですが、実際にはリソース名を -password サフィックスで書式設定するだけです。詳細については、「開発中のアプリシークレットの安全なストレージ」に関すると、「パラメーター付きのリソースを追加」に関するを参照してください。

WithReference メソッドは、databaseという名前の ExampleProject で接続を構成します。

ヒント

既存の SQL Serverに接続する場合は、代わりに AddConnectionString 呼び出します。詳細については、「既存のリソースを参照する」を参照してください。

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

SQL Server リソースにデータボリュームを追加するには、SQL Server リソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

データボリュームは、SQL Server データをコンテナーのライフサイクル外に保持するために使用されます。データボリュームは、SQL Server コンテナー内の /var/opt/mssql パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。データボリュームに関する詳細およびなぜよりものバインドマウントが好まれるかについては、Docker ドキュメント: ボリュームを参照してください。

警告

パスワードはデータボリュームに格納されます。データボリュームを使用していて、パスワードが変更された場合は、ボリュームを削除するまで機能しません。

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

SQL Server リソースにデータバインドマウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

大事な

データバインドマウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適したボリュームと比較して機能が制限されています。ただし、バインドマウントを使用すると、ホストシステム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データバインドマウントは、ホストマシンのファイルシステムに依存して、コンテナーの再起動間に SQL Server データを保持します。データバインドマウントは、SQL Server コンテナー内のホストコンピューター上の Windows 上の C:\SqlServer\Data (または Unixの /SqlServer/Data) パスにマウントされます。データバインドマウントの詳細については、「Docker ドキュメント: バインドマウント」を参照してください。

パラメーターを持つ SQL Server リソースを追加する

コンテナーイメージで使用されるパスワードを明示的に指定する場合は、これらの資格情報をパラメーターとして指定できます。次の代替例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

パラメーターの指定の詳細については、「外部パラメーターの」を参照してください。

データベースリソースへの接続

アプリホストを実行すると、 Management Studio (SSMS) や Data Studioなどの外部ツールからのデータベースリソースアクセスできます。データベースリソースの接続文字列は依存リソース環境変数で使用でき、.NET.NET Aspire ダッシュボードの [リソースの詳細] ペインを使用してアクセスします。環境変数の名前は ConnectionStrings__{name}{name} データベースリソースの名前です。この例では、databaseです。接続文字列を使用して、外部ツールからデータベースリソースに接続します。 1 つの dbo.Todos テーブルを持つ todos という名前のデータベースがあるとします。

SQL Server 管理スタジオ
Azure Data Studio

SQL Server Management Studio からデータベースリソースに接続するには、次の手順に従います。

SSMS を開きます。
[ に接続する ] ダイアログで、[追加の接続パラメータータブを選択します。
接続文字列を [追加の接続パラメーター] フィールドに貼り付け、[接続] を選択します。
接続されている場合は、オブジェクトエクスプローラーのにデータベースリソースが表示されます。

詳細については、「SQL Server Management Studio: serverに接続する」を参照してください。

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

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

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

Client 統合

.NET Aspire SQL Server Entity Framework Core 統合を開始するには、📦Aspireをインストールします。Microsoft.EntityFrameworkCore.SqlServer NuGet パッケージを、clientを使用するプロジェクト、つまり、SQL ServerEntity Framework Coreclientを使用するアプリケーションのプロジェクトです。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

<PackageReference Include="Aspire.Microsoft.EntityFrameworkCore.SqlServer"
                  Version="*" />

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

SQL Serverのデータベースコンテキストを追加する

clientを使用するプロジェクトの Program.cs ファイルで、IHostApplicationBuilder のいずれかに対して AddSqlServerDbContext 拡張メソッドを呼び出し、依存関係注入コンテナ経由で使用するための DbContext を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");

ヒント

connectionName パラメーターは、SQL Server データベースリソースをアプリホストプロジェクトに追加するときに使用する名前と一致する必要があります。つまり、AddDatabase を呼び出す際に指定した database の名前を、AddSqlServerDbContextを呼び出す際にも同じ名前として使用する必要があります。詳細については、「リソース SQL Server とデータベースリソースを追加する」を参照してください。

サービスからExampleDbContextオブジェクトを取得するには:

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

依存性注入について詳しくは .NET 依存関係の挿入を参照してください。

データベースコンテキスト SQL Server をエンリッチメントと共に追加する

自動再試行、正常性チェック、ログ記録、テレメトリなどの追加のサービスで DbContext を強化するには、EnrichSqlServerDbContext メソッドを呼び出します。

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    connectionName: "database",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

settings パラメーターは、MicrosoftEntityFrameworkCoreSqlServerSettings クラスのインスタンスです。

構成

.NET Aspire SQL Server Entity Framework Core 統合では、プロジェクトの要件と規則を満たす複数の構成アプローチとオプションが提供されます。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、builder.AddSqlServerDbContext<TContext>()を呼び出すときに接続文字列の名前を指定します。

builder.AddSqlServerDbContext<ExampleDbContext>("sql");

接続文字列は、ConnectionStrings 構成セクションから取得されます。

{
  "ConnectionStrings": {
    "sql": "Data Source=myserver;Initial Catalog=master"
  }
}

EnrichSqlServerDbContext では、呼び出された時点で DbContext が登録されることを想定しているため、ConnectionStrings 構成セクションは使用されません。

詳細については、ConnectionStringを参照してください。

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

.NET Aspire SQL Server Entity Framework Core 統合では、Microsoft.Extensions.Configurationがサポートされています。 Aspire:Microsoft:EntityFrameworkCore:SqlServer キーを使用して、appsettings.json などの構成ファイルから MicrosoftEntityFrameworkCoreSqlServerSettings を読み込みます。 Aspire:Microsoft:EntityFrameworkCore:SqlServer セクションで構成を設定した場合は、パラメーターを渡さずにメソッドを呼び出すことができます。

使用可能なオプションの一部を構成する appsettings.json ファイルの例を次に示します。

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "SqlServer": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "DisableMetrics": false
        }
      }
    }
  }
}

インライン構成を使用する

また、Action<MicrosoftEntityFrameworkCoreSqlServerSettings> デリゲートを渡して、メトリックをオフにするなど、一部またはすべてのオプションをインラインで設定することもできます。

builder.AddSqlServerDbContext<YourDbContext>(
    "sql",
    static settings =>
        settings.DisableMetrics = true);

複数の DbContext 接続を構成する

複数の DbContext を異なる構成に登録する場合は、構成セクション名 $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" 使用できます。 json 構成は次のようになります。

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
          "SqlServer": {
            "ConnectionString": "YOUR_CONNECTIONSTRING",
            "DbContextPooling": true,
            "DisableHealthChecks": true,
            "DisableTracing": true,
            "DisableMetrics": false,
          "AnotherDbContext": {
            "ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

次に、AnotherDbContext 型パラメーターを使用して AddSqlServerDbContext メソッドを呼び出すと、Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext セクションから設定が読み込まれます。

builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");

構成オプション

対応する既定値を使用して構成可能なオプションを次に示します。

名前	説明
`ConnectionString`	接続する SQL Server データベースの接続文字列。
`DbContextPooling`	db コンテキストがプールされるか、要求されるたびに個別に作成されるかを示すブール値
`MaxRetryCount`	再試行の最大数。既定値は 6 で、再試行メカニズムを無効にするには 0 に設定します。
`DisableHealthChecks`	データベースの正常性チェックが無効かどうかを示すブール値。
`DisableTracing`	OpenTelemetry トレースが無効かどうかを示すブール値。
`DisableMetrics`	OpenTelemetry メトリックが無効かどうかを示すブール値。
`Timeout`	コマンドの実行を待機する秒数。

健康診断

既定では、.NET.NET Aspire 統合により、すべてのサービス正常性チェックが有効になります。詳細については、.NET.NET Aspire 統合の概要を参照してください。

既定では、.NET Aspire Sql ServerEntity Framework Core 統合によって次の処理が行われます。

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

可観測性とテレメトリ

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

伐採

.NET Aspire SQL Server 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 SQL Server Entity Framework Core 統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

"OpenTelemetry.Instrumentation.EntityFrameworkCore"

メトリック

.NET Aspire SQL Server Entity Framework Core 統合では、OpenTelemetryを使用して次のメトリックが出力されます。

Microsoft.EntityFrameworkCore:
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

次の方法で共有

.NET Aspire SQL Server Entity Framework Core 統合

ホスティング統合

SQL Serverリソースとデータベースリソースを追加する

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

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

パラメーターを持つ SQL Server リソースを追加する

データベースリソースへの接続

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

Client 統合

SQL Serverのデータベースコンテキストを追加する

データベースコンテキスト SQL Server をエンリッチメントと共に追加する

構成

接続文字列を使用する

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

インライン構成を使用する

複数の DbContext 接続を構成する

構成オプション

健康診断

可観測性とテレメトリ

伐採

追跡

メトリック

関連項目

その他のリソース

次の方法で共有

.NET Aspire SQL Server Entity Framework Core 統合

ホスティング統合

SQL Serverリソースとデータベースリソースを追加する

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

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

パラメーターを持つ SQL Server リソースを追加する

データベース リソースへの接続

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

Client 統合

SQL Serverのデータベースコンテキストを追加する

データベースコンテキスト SQL Server をエンリッチメントと共に追加する

構成

接続文字列を使用する

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

インライン構成を使用する

複数の DbContext 接続を構成する

構成オプション

健康診断

可観測性とテレメトリ

伐採

追跡

メトリック

関連項目

その他のリソース

データベースリソースへの接続