.NET Aspire SQL Server Entity Framework Core 統合

含まれているもの: ホスティング統合 —および— Client 統合

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

ホスティング統合

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

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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

.NET .NET Aspire 前の例で示したように、mcr.microsoft.com/mssql/server イメージでコンテナー イメージをアプリ ホストに追加すると、ローカル コンピューターに新しい SQL Server インスタンスが作成されます。 データベースの追加には、SQL Server リソース ビルダー (sql 変数) への参照が使用されます。 データベースには database という名前が付けられ、ExampleProjectに追加されます。

データベース リソースをアプリ モデルに追加すると、データベースがまだ存在しない場合は作成されます。 データベースの作成は、 アプリ ホストイベント API (特に ResourceReadyEvent) に依存します。 つまり、 sql リソースの 準備ができたら、イベントが発生し、データベース リソースが作成されます。

SQL Server リソースには、username の sa を持つ既定の資格情報と、password メソッドを使用して生成されたランダムな CreateDefaultPasswordParameter が含まれます。

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

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

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

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

SQL Server リソースをデータベース スクリプトとともに追加する

既定では、 SqlServerDatabaseResourceを追加すると、次の SQL スクリプトに依存してデータベースが作成されます。

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

既定のスクリプトを変更するには、データベース リソース ビルダーで WithCreationScript メソッドの呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

前の例では、単一のapp_db テーブルで todos という名前のデータベースを作成します。 SQL スクリプトは、データベース リソースの作成時に実行されます。 スクリプトは文字列として WithCreationScript メソッドに渡され、 SQL Server リソースのコンテキストで実行されます。

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

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

データ ボリュームは、SQL Server データをコンテナーのライフサイクル外に保持するために使用されます。 データ ボリュームは、/var/opt/mssql コンテナー内の SQL Server パスにマウントされ、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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

データ バインド マウントは、ホスト マシンのファイルシステムに依存して、コンテナーの再起動間に SQL Server データを保持します。 データ バインド マウントは、C:\SqlServer\Data コンテナー内のホスト コンピューター上の Windows 上の /SqlServer/Data (または Unixの SQL Server) パスにマウントされます。 データ バインド マウントの詳細については、「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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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

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

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

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

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 パッケージは、クライアントを使用するプロジェクト、つまり、SQL ServerEntity Framework Core クライアントを使用するアプリケーションのプロジェクトです。

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

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

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

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

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

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

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

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

SQL Server データベース コンテキストを強化する

標準の Entity Framework メソッドを使用してデータベース コンテキストを取得し、依存関係挿入コンテナーに追加することもできます。

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("database")
        ?? throw new InvalidOperationException("Connection string 'database' not found.")));

次に例を示すように、この方法でデータベース コンテキストを作成する際の柔軟性が向上します。

• データベース コンテキストの既存の構成コードは、.NET.NET Aspire用に書き換えることなく再利用できます。
• Entity Framework Core インターセプターを使用して、データベース操作を変更できます。
• コンテキスト プール Entity Framework Core 使用しないことを選択できます。状況によってはパフォーマンスが向上する可能性があります。

このメソッドを使用する場合は、.NET メソッドを呼び出すことで、.NET AspireEnrichSqlServerDbContextスタイルの再試行、正常性チェック、ログ記録、テレメトリ機能を使用してデータベース コンテキストを拡張できます。

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    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 では、呼び出された時点で ConnectionStrings が登録されることを想定しているため、DbContext 構成セクションは使用されません。

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

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

.NET Aspire SQL Server Entity Framework Core 統合では、Microsoft.Extensions.Configurationがサポートされています。 MicrosoftEntityFrameworkCoreSqlServerSettings キーを使用して、appsettings.json などの構成ファイルから Aspire:Microsoft:EntityFrameworkCore:SqlServer を読み込みます。 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
          }
        }
      }
    }
  }
}

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

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

構成オプション

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

Client 統合ヘルスチェック

既定では、.NET.NET Aspireクライアント統合 すべてのサービスで 正常性チェック 有効になっています。 同様に、多くの .NET.NET Aspireホスティング統合 もヘルスチェックエンドポイントを有効にします。 詳細については、以下を参照してください。

• C#でのアプリ正常性チェック .NET
• ASP.NET Core での正常性チェック

既定では、.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

ご参照ください

• Azure SQL Database のドキュメント
• .NET .NET Aspire 統合
• .NET Aspire GitHub リポジトリ