SQL 準拠データベースにデータを格納する

15 分

.NET Aspire スタックは、生産性を高め、堅牢でスケーラブルで安全な Web アプリケーションを構築できるように設計されています。サポートされている Aspire コンポーネントのいずれかを追加することで、構造化されたリレーショナルデータをすばやく格納できます。

現時点での SQL 準拠データベースコンポーネントは次のとおりです。

PostgreSQL データベース
SQL Database
Oracle データベース
MySQL データベース

Note

Microsoft では、他のデータベースシステムのサポートを追加する可能性があり、サードパーティの貢献の可能性もあるため、このリストはさらに増える可能性があります。

このユニットでは、これらのコンポーネントのうち 3 つについて、どのデータベースで Entity Framework Core がサポートされているか、およびそれらを使用してデータを格納したり取得したりする方法について説明します。

プロジェクトにデータベースコンポーネントを追加する方法

どのデータベースを選択しても、.NET Aspire データベースコンポーネントをプロジェクトに追加する方法は同じです。

アプリホストプロジェクトで次の手順を実行します。

.NET Aspire ホスティングコンポーネントをアプリホストプロジェクトにインストールします。
データベースを登録し、ソリューションのアプリホストにデータベース用のコンテナーを作成します。
データベースをホストする、作成したコンテナーへのアクセスを必要とするプロジェクトに参照を渡します。

データベースを使用するプロジェクトで、次の手順を実行します。

データアクセスを必要とするプロジェクトに、NuGet パッケージを含む .NET Aspire コンポーネントを追加します。オプションとして、.NET Core Entity Framework (EF) コンポーネントがある場合は、これを代わりに使用できます。
プロジェクトの Program.cs ファイルに、EF のデータソースまたはデータベースコンテキストを登録します。
依存関係の挿入を使用して、サービスにデータソースを挿入します。

サポートされている各データベースについて、これらの手順を実行する方法の詳細を見てみましょう。

.NET PostgreSQL コンポーネントの使用

.NET PostgreSQL コンポーネントでは、アプリホストプロジェクトと、データベースを使用するすべてのマイクロサービスの両方で変更が必要です。

アプリホストの構成

まず、適切なホスティングコンポーネントをアプリホストにインストールします。

dotnet add package Aspire.Hosting.PostgreSQL --prerelease

次に、データベースを登録してそのデータベース用のコンテナーを作成するため、次のコードをアプリホストの Program.cs ファイルに追加します。

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

また、データベースサービスへの参照を、それを使用するすべてのプロジェクトに渡す必要があります。

var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
                                       .WithReference(postgresdb);

使用する側のプロジェクトの構成

.NET Aspire PostgreSQL コンポーネントをインストールするには、.NET Aspire プロジェクトで次のようなコマンドを使用します。

dotnet add package Aspire.Npgsql --prerelease

または、.NET PostgreSQL Entity Framework Core コンポーネントを使用するには、次のコマンドを代わりに使用します。

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL --prerelease

また、Visual Studio で [追加] > [.NET Aspire コンポーネント] ショートカットを使用して、NuGet パッケージマネージャーからコンポーネントをインストールすることもできます。

*.AppHost プロジェクトの Program.cs ファイルによってデータベースが作成され、それを使用するプロジェクトに渡されます。

var postgres = builder.AddPostgres("pg")
                      .AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.SampleProject>()
                            .WithReference(postgres);

一部の .NET Aspire データベースコンポーネントでは、データベース管理ツール用のコンテナーを作成することもできます。ソリューションに PgAdmin を追加して PostgreSQL データベースを管理するには、次のコードを使用します。

var postgresdb = builder.AddPostgres("pg")
                        .AddDatabase("postgresdb")
                        .WithPgAdmin();

.NET Aspire にコンテナーを作成させることの利点は、PgAdmin を PostgreSQL データベースに接続するための構成を行う必要がなく、すべて自動であるということです。

PostgreSQL データベースの使用

データベースを使用するすべてのプロジェクトで、PostgreSQL への接続を表すデータソースを追加します。 Program.cs ファイルで、次のコードを使用してデータベースを登録します。

builder.AddNpgsqlDataSource("postgresdb");

または、Entity Framework Core コンポーネントを使用するには、データベースコンテキストを登録します。

builder.AddNpgsqlDbContext<YourDbContext>("postgresdb");

データベースが使用側プロジェクトに登録された後は、依存関係の挿入を使用して、必要なときにいつでもデータソースを操作できます。

public class YourService(NpgsqlDataSource dataSource)
{
    public async Task<IEnumerable<Catalog>> GetCatalog()
	{
        const string query = "SELECT * FROM catalog";
        using var dbConnection = dataSource.OpenConnection();
        var results = await dbConnection.QueryAsync<Catalog>(command);
        return queryResult.ToArray();
	}
}

または、データベースコンテキスト YourDbContext を取得してデータベースを操作することもできます。

public class YourService(YourDbContext context)
{
    public async Task<IEnumerable<Catalog>> GetCatalog()
	{
        var items = await context.ObjectItems;
        if (item is null)
        {
            return Results.NotFound();
        }
		else
		{
		    return items;
		}
	}
}

PostgreSQL コンポーネントの構成

.NET Aspire スタックは、必要な構成の量を削減しようとします。依存関係の挿入とサービス検出を使用すると、プロジェクトで接続文字列を構成する必要なくデータベースにアクセスできます。

アプリホストプロジェクトを使用してデータベースコンテナーを作成し、それをプロジェクトへの参照として渡すことで、受信側のプロジェクトがデータベースの場所、接続文字列、およびポートにアクセスできるようになります。環境変数や appsettings.json ファイルを管理する必要はありません。

ただし、必要がある場合や、データベースの構成方法をより詳細に制御する必要がある場合は、さらに多くのオプションがあります。

接続文字列の使用

データベースを必要とするプロジェクトでは、接続文字列を使用してデータベースに接続します。この方法は、アプリホストに登録されていないデータベースに接続する必要がある場合に便利です。

builder.AddNpgsqlDataSource("NpgsqlConnectionString");

続いて、構成ファイルで接続文字列を追加できます。

{
  "ConnectionStrings": {
    "NpgsqlConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword"
  }
}

構成プロバイダーの使用

.NET Aspire には、Microsoft.Extensions.Configuration をサポートできるコンポーネントの機能があります。 PostgreSQL コンポーネントではこの機能がサポートされており、既定では、Aspire:Npgsql キーを使用して設定が検索されます。 appsettings.json を使用するプロジェクトでは、構成の例は次のようになります。

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
      "HealthChecks": true,
      "Tracing": true,
      "Metrics": true
    }
  }
}

以前の構成では、接続文字列を設定し、PostgreSQL コンポーネントの正常性チェック、トレース、メトリックを有効にしています。その後、コードで接続文字列を指定する必要がなくなりました。builder.AddNpgsqlDataSource(); を使用するだけです。

PostgreSQL Entity Framework Core コンポーネントを使用している場合は、Aspire:Npgsql:EntityFrameworkCore:PostgreSQL キーを使用してデータベースコンテキストを構成できます。

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
          "MaxRetryCount": 0,
          "HealthChecks": false,
          "Tracing": false
        }
      }
    }
  }
}

Entity Framework の構成オプションの詳細については、「.NET Aspire のドキュメント」を参照してください。

インラインデリゲートの使用

最後のオプションは、configureSettings インラインデリゲートを AddNpgsqlDataSource メソッドに渡すことです。このデリゲートを使用すると、コードを使用してデータベースコンポーネントの設定を直接構成できます。

builder.AddNpgsqlDataSource(
    "postgresdb", static settings => settings.HealthChecks = false);

.NET Aspire SQL Database コンポーネントの使用

上記のパターンは、SQL Database コンポーネントでも同じです。アプリホストプロジェクトと、データベースサービスを使用するマイクロサービスの両方で変更を行います。

アプリホストの構成

SQL データベースホスティングコンポーネントをインストールするには、次のコマンドを使用します。

dotnet add package Aspire.Hosting.SqlServer --prerelease

コンテナーとデータベースを登録するため、次のコードをアプリホストの Program.cs ファイルに追加します。

var sql = builder.AddSqlServer("sql");
var sqldb = sql.AddDatabase("sqldb");

続いて、データベースサービスへの参照を、それを使用するすべてのプロジェクトに渡します。

var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
                                       .WithReference(sqldb);

使用する側のプロジェクトの構成

.NET Aspire SQL Database コンポーネントをインストールするには、.NET Aspire プロジェクトで次のようなコマンドを使用します。

dotnet add package Aspire.Microsoft.Data.SqlClient --prerelease

または、.NET Aspire SqlServer Entity Framework Core コンポーネントを使用するには、次のコマンドを代わりに使用します。

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer --prerelease

これらの NuGet パッケージは、Visual Studio の Add > .NET Aspire Component ショートカットを使用して追加することもできます。

データベースにアクセスするための *.AppHost プロジェクトの Program.cs ファイルコードは、PostgreSQL の例に似ています。

var sqlServer = builder.AddSqlServer("sql")
                       .AddDatabase("sqldata");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(sqlServer);

SQL Server データベースの使用

SQL アクセスを必要とするプロジェクトでは、Program.cs ファイルで、次のコードによって Entity Framework データベースコンテキストが登録されます。

builder.AddSqlServerDbContext<YourDbContext>("sqldata");

データベースが使用側プロジェクトに登録された後は、依存関係の挿入を使用して、データベースコンテキスト YourDbContext を使用してデータソースを操作できます。次のコード例では、データベースから天気予報を取得し、1 つをランダムに選択して返します。

app.MapGet("/weatherforecast", async (YourDbContext context) =>
{
  var rng = new Random();
  var forecasts = await context.Forecasts.ToListAsync();
  var forecast = forecasts[rng.Next(forecasts.Count)];
  return forecast;
});

SQL Server コンポーネントの構成

これまでと同様に、アプリホストと使用側のプロジェクトで同じデータベース名を使用する場合、SQL Server データベースとプロジェクトの間の接続を構成する必要はありません。 .NET Aspire SQL Server コンポーネントでは、コンポーネントを構成する他の方法もサポートされています。

構成プロバイダーの使用

SQL Server コンポーネントでは Microsoft.Extensions.Configuration もサポートされています。既定では、Aspire:SqlServer:SqlClient キーを使用して設定の検索が行われます。 appsettings.json を使用するプロジェクトでは、構成の例は次のようになります。

{
  "Aspire": {
    "SqlServer": {
      "SqlClient": {
        "ConnectionString": "YOUR_CONNECTIONSTRING",
        "HealthChecks": true,
        "Tracing": false,
        "Metrics": false
      }
    }
  }
}

インライン構成の使用

SQL Server コンポーネントを追加するときに、configureSettings インラインデリゲートを AddSqlServerClient メソッドに渡すことができます。このデリゲートを使用すると、コードを使用してデータベースコンポーネントの設定を直接構成できます。

builder.AddSqlServerClient("sqldata", static settings => settings.HealthChecks = false);

サポートされているオプションのいずれかを渡すことができます。

ConnectionString:SQL Server データベースの接続文字列
HealthChecks:データベースの正常性チェックが有効になっているかどうかを示すブール値
Tracing:OpenTelemetry トレースが有効になっているかどうかを示すブール値
Metrics:OpenTelemetry メトリックが有効になっているかどうかを示すブール値

複数のデータベースに接続する

SQL Server コンポーネントは、名前付きインスタンスを介した複数の接続をサポートしています。たとえば、同じプロジェクト内の 2 つの異なる SQL Server データベースに接続できます。

{
  "Aspire": {
    "SqlServer": {
      "SqlClient": {
        "INSTANCE_1": {
          "ServiceUri": "YOUR_URI",
          "HealthChecks": false
        },
        "INSTANCE_2": {
          "ServiceUri": "YOUR_URI",
          "HealthChecks": false
        }
      }
    }
  }
}

この構成を使用すると、同じプロジェクト内の 2 つの異なるデータベースに接続できます。

builder.AddSqlServerClient("INSTANCE_1");
builder.AddSqlServerClient("INSTANCE_2");

MySQL コンポーネントの使用

.NET Aspire MySQL コンポーネントをインストールするには、データアクセスを必要とする .NET Aspire プロジェクトで次のようなコマンドを使用します。

dotnet add package Aspire.MySqlConnector --prerelease

または、Visual Studio で [追加] > [.NET Aspire コンポーネント] ショートカットを使用して、NuGet パッケージマネージャーからコンポーネントをインストールします。

データベースにアクセスするための *.AppHost プロジェクトの Program.cs ファイルコードは、PostgreSQL の例に似ています。

var mysqldb = builder.AddMySql("mysql")
                     .AddDatabase("mysqldb")
                     .WithPhpMyAdmin();

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(mysqldb);

PostgreSQL コンポーネントと同様に、MySQL コンポーネントでも、データベース管理ツール用のコンテナーを作成することができます。前の例では、PhpMyAdmin ソリューションに追加します。

MySQL データベースの使用

このパターンは、MySQL アクセスを必要とするプロジェクトでも同じです。 Program.cs ファイルで、次のコードを使用してデータベースを登録します。

builder.AddMySqlDataSource("mysqldb");

データベースが使用側プロジェクトに登録された後は、依存関係の挿入を使用して、必要なときにいつでもデータソースを操作できます。

app.MapGet("/catalog", async (MySqlConnection db) =>
{
    const string sql = """
        SELECT Id, Name, Description, Price
        FROM catalog
        """;

    // the db object is a connection to the MySQL database registered with AddMySqlDataSource
    return await db.QueryAsync<CatalogItem>(sql);
});

MySQL コンポーネントの構成

MySQL コンポーネントでは、構成を管理するための同じ 3 つのオプションがサポートされています。

Connection strings

appsettings.json ファイルには、MySQL データベースの接続文字列を含めることができます。

{
  "ConnectionStrings": {
    "MySqConnection": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword"
  }
}

次に、プロジェクトで、次のようなコードを使用して接続文字列を使用してデータベースに接続できます。

builder.AddMySqlDataSource("MySqConnection");

コンフィギュレーション提供者

Aspire:MySqlConnector キーは、MySQL コンポーネントの構成に使用されます。

{
  "Aspire": {
    "MySqlConnector": {
      "ConnectionString": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword",
      "HealthChecks": true,
      "Tracing": false,
      "Metrics": false
    }
  }
}

インライン構成

builder.AddMySqlDataSource("mysqldb", static settings => settings.HealthChecks = false);

データベースに対するシード処理を実行する

.NET Aspire スタックではコンテナーが使用され、一貫性のある環境と簡単なデプロイという利点が得られます。欠点は、コンテナーがステートレスであるということです。コンテナーが破棄されると、データベースに追加されたデータやスキーマは失われます。 .NET Aspire には、コンテナーの作成時にデータベースにデータをシード処理する方法が用意されています。

ボリュームとスクリプトの使用

データベースをシード処理する最も簡単な方法は、ボリュームと SQL スクリプトを使用することです。ボリュームには、一度に複数のコンテナーのデータを格納することができ、高いパフォーマンスが提供され、バックアップや移行が簡単です。これらのボリュームに格納されているスクリプトは、コンテナーの作成時に実行され、データベースにデータが入力されます。スクリプトは、データベースに必要なデータとスキーマを含む SQL ファイルにすることができます。

たとえば、Service.API/Seed フォルダー内の postgres-backup.sql という名前のファイルに格納されている SQL スクリプトがある場合は、次のようになります。

CREATE TABLE catalog (
  Id INT PRIMARY KEY,
  Name VARCHAR(50),
  Description VARCHAR(255),
  Price DECIMAL(18, 2)
);

INSERT INTO catalog (Id, Name, Description, Price)
VALUES (1, 'Item 1', 'Description of item 1', 10.99),
      (2, 'Item 2', 'Description of item 2', 20.99),
      (3, 'Item 3', 'Description of item 3', 30.99);

ソリューションのアプリホストでは、Service.API/Seed フォルダーをコンテナーの /docker-entrypoint-initdb.d フォルダーにバインドできます。このフォルダーは、コンテナーの作成時に検出されたすべての SQL スクリプトを実行する、PostgreSQL コンテナー内の特別なフォルダーです。

    var catalogDB = builder.AddPostgres("postgres")
      .WithPgAdmin()
      .WithEnvironment("POSTGRES_DB", "backendDB")
      .WithBindMount("../Service.API/Seed", "/docker-entrypoint-initdb.d")
      .AddDatabase("backendDB");

SQL スクリプトをスキーマ作成スクリプトとデータシード処理スクリプトに分割することもできます。それらがすべて Service.API/Seed フォルダーに含まれている場合、.NET Aspire がデータベースを作成するときに実行されます。

Entity Framework Core を使用したデータのシード処理

Entity Framework Core をサポートするコンポーネントについては、DbContext クラスと Entity Framework コアの移行を使用してデータベースをシード処理できます。このメソッドでは、C# コードを使用してデータベースをシード処理します。ただし、このシード処理は、運用環境ではなく、開発中またはテスト中にのみ行うようにします。

// Register DbContext class
builder.AddNpgsqlDbContext<CatalogContext>("sqldata");

var app = builder.Build();

app.MapDefaultEndpoints();

if (app.Environment.IsDevelopment())
{
    // Retrieve an instance of the DbContext class and manually run migrations during development
    using (var scope = app.Services.CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<CatalogContext>();
        context.Database.EnsureCreated();
    }
}

上記のコードでは、アプリ環境の状態の確認が行われます。開発中の場合、コードは CatalogContext クラスを取得し、EnsureCreated メソッドを実行します。このメソッドは、データベースを作成し、保留中のすべての移行を実行します。

さまざまなデータベースコンポーネントをシード処理する方法の詳細については、「.NET Aspire のドキュメント」を参照してください。

続行

SQL 準拠データベースにデータを格納する

プロジェクトにデータベース コンポーネントを追加する方法

.NET PostgreSQL コンポーネントの使用

アプリ ホストの構成

使用する側のプロジェクトの構成

PostgreSQL データベースの使用

PostgreSQL コンポーネントの構成

接続文字列の使用

構成プロバイダーの使用

インライン デリゲートの使用

.NET Aspire SQL Database コンポーネントの使用

アプリ ホストの構成

使用する側のプロジェクトの構成

SQL Server データベースの使用

SQL Server コンポーネントの構成

構成プロバイダーの使用

インライン構成の使用

複数のデータベースに接続する

MySQL コンポーネントの使用

MySQL データベースの使用

MySQL コンポーネントの構成

Connection strings

コンフィギュレーション提供者

インライン構成

データベースに対するシード処理を実行する

ボリュームとスクリプトの使用

Entity Framework Core を使用したデータのシード処理

フィードバック

プロジェクトにデータベースコンポーネントを追加する方法

アプリホストの構成

インラインデリゲートの使用

アプリホストの構成