.NET Aspire SQL Server 統合

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

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

ホスティング統合

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

.NET コマンドラインインターフェース
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 サフィックスで書式設定するだけです。詳細については、「開発中のアプリシークレットの安全なストレージ」についてASP.NET Core を参照し、および「パラメーターを使用した SQL Server リソースの追加」について参照してください。

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 client 統合を始めるには、📦Aspireをインストールします。 Microsoft.Data.SqlClient NuGet パッケージを、clientを消費するプロジェクト、すなわち、アプリケーションが SQL Serverclientを使用するプロジェクトでインストールします。 SQL Server client 統合により、SQL Serverとの対話に使用できる SqlConnection インスタンスが登録されます。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

SQL Server client の追加

clientを使用するプロジェクトの Program.cs ファイルで、任意の IHostApplicationBuilder に対して AddSqlServerClient 拡張メソッドを呼び出し、依存性注入コンテナーを介して使用する SqlConnection を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddSqlServerClient(connectionName: "database");

ヒント

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

その後、依存関係の挿入を使用して SqlConnection インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

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

キー付き SQL Serverclient を追加する

接続名が異なる複数の SqlConnection インスタンスを登録する場合があります。キー付き SQL Server クライアントを登録するには、AddKeyedSqlServerClient メソッドを呼び出します。

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

大事な

キー付きサービスを使用する場合、SQL Server リソースで、mainDb 用と loggingDb用の 2 つの名前付きデータベースが構成されている必要があります。

その後、依存関係の挿入を使用して SqlConnection インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

設定

.NET Aspire SQL Server 統合には、プロジェクトの要件と規則に基づいて接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddSqlServerClient メソッドを呼び出すときに接続文字列の名前を指定できます。

builder.AddSqlServerClient(connectionName: "sql");

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

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

この接続文字列の書式を設定する方法の詳細については、ConnectionStringを参照してください。

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

.NET Aspire SQL Server 統合では、Microsoft.Extensions.Configurationがサポートされます。 Aspire:Microsoft:Data:SqlClient キーを使用して、構成から MicrosoftDataSqlClientSettings を読み込みます。次のスニペットは、いくつかのオプションを構成する appsettings.json ファイルの例です。

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

完全な SQL Serverclient 統合 JSON スキーマについては、Aspireを参照してください。Microsoft.Data.SqlClient/ConfigurationSchema。json.

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

また、Action<MicrosoftDataSqlClientSettings> configureSettings デリゲートを渡して、一部またはすべてのオプションをインラインで設定できます。たとえば、コードから正常性チェックを無効にすることができます。

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client 統合の正常性チェック

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

.NET Aspire SQL Server 統合:

MicrosoftDataSqlClientSettings.DisableHealthChecks が falseされたときに正常性チェックを追加し、SQL Serverへの接続を試みます。
/health HTTP エンドポイントと統合されます。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります。

可観測性とテレメトリ

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

伐採

現在、.NET AspireSQL Server 統合では、Microsoft.Data.SqlClientの制限により、既定ではログ記録は有効になりません。

トレース

.NET Aspire SQL Server 統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

OpenTelemetry.Instrumentation.SqlClient

メトリック

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

Microsoft.Data.SqlClient.EventSource
- active-hard-connections
- hard-connects
- hard-disconnects
- active-soft-connects
- soft-connects
- soft-disconnects
- number-of-non-pooled-connections
- number-of-pooled-connections
- number-of-active-connection-pool-groups
- number-of-inactive-connection-pool-groups
- number-of-active-connection-pools
- number-of-inactive-connection-pools
- number-of-active-connections
- number-of-free-connections
- number-of-stasis-connections
- number-of-reclaimed-connections

次の方法で共有

.NET Aspire SQL Server 統合

ホスティング統合

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

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

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

パラメーターを伴う SQL Server リソースを追加する

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

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

Client 統合

SQL Server client の追加

キー付き SQL Serverclient を追加する

設定

接続文字列を使用する

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

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

Client 統合の正常性チェック

可観測性とテレメトリ

伐採

トレース

メトリック

参照

その他のリソース

次の方法で共有

.NET Aspire SQL Server 統合

ホスティング統合

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

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

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

パラメーターを伴う SQL Server リソースを追加する

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

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

Client 統合

SQL Server client の追加

キー付き SQL Serverclient を追加する

設定

接続文字列を使用する

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

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

Client 統合の正常性チェック

可観測性とテレメトリ

伐採

トレース

メトリック

参照

その他のリソース

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

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

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