From 5dae60735dec5321298174f78407577c8b148999 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 01:42:41 +0000 Subject: [PATCH 1/2] docs: add Aspire.Hosting.EntityFrameworkCore hosting integration doc Documents the new EF Core migrations hosting integration introduced in microsoft/aspire#13481, including: - AddEFMigrations extension method usage - RunDatabaseUpdateOnStart with WaitFor support - PublishAsMigrationScript and PublishAsMigrationBundle - Dashboard resource commands reference - WithMigrationsProject for separate migrations projects - Sidebar entry under Entity Framework Core section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../config/sidebar/integrations.topics.ts | 4 + .../efcore/ef-migrations-hosting.mdx | 181 ++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 1fb6789de..e866c8cb7 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -940,6 +940,10 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { label: 'Apply migrations', slug: 'integrations/databases/efcore/migrations', }, + { + label: 'EF migrations hosting integration', + slug: 'integrations/databases/efcore/ef-migrations-hosting', + }, { label: 'Seed data', slug: 'integrations/databases/efcore/seed-database', diff --git a/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx b/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx new file mode 100644 index 000000000..eba06c0ef --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx @@ -0,0 +1,181 @@ +--- +title: Manage EF Core migrations with Aspire.Hosting.EntityFrameworkCore +description: Learn how to use the Aspire.Hosting.EntityFrameworkCore hosting integration to manage Entity Framework Core database migrations from your AppHost project. +--- + +import { Steps } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import LearnMore from '@components/LearnMore.astro'; + +The `Aspire.Hosting.EntityFrameworkCore` hosting integration lets you manage Entity Framework Core (EF Core) database migrations directly from your Aspire AppHost project. Rather than writing a separate migration worker service, you call `AddEFMigrations` on an existing project resource to register migration management capabilities, then use the fluent API to control how and when migrations run. + +Key capabilities include: + +- **Automatic migration at startup** — run `dotnet ef database update` automatically when the app starts, with full health-check integration so dependent resources wait until migrations complete. +- **Publish-time migration artifacts** — generate SQL migration scripts or self-contained migration bundles as part of the `aspire publish` pipeline. +- **Dashboard resource commands** — interactive commands appear on the project resource in the Aspire dashboard: *Update Database*, *Drop Database*, *Reset Database*, *Add Migration*, *Remove Migration*, and *Get Database Status*. +- **Multiple DbContext support** — call `AddEFMigrations` multiple times on the same project to manage separate DbContext types independently. +- **Separate migrations project** — use `WithMigrationsProject` when migrations live in a different project than the startup project. + +:::note +The `Aspire.Hosting.EntityFrameworkCore` package requires your project to reference `Microsoft.EntityFrameworkCore.Design`. The hosting integration validates this at startup and shows a diagnostic message if it is missing. +::: + +## Install the hosting integration + +In your AppHost project, install the `Aspire.Hosting.EntityFrameworkCore` NuGet package: + + + +## Add EF migrations to a project resource + +Call `AddEFMigrations` on an existing project resource: + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var api = builder.AddProject("api"); + +api.AddEFMigrations(); + +builder.Build().Run(); +``` + +When the AppHost runs, the dashboard shows additional resource commands on the `api` resource — one set for each registered DbContext. + +### Specify a DbContext type + +By default, `AddEFMigrations` discovers all DbContext types in the project. To target a specific context, use the generic overload: + +```csharp title="AppHost.cs" +api.AddEFMigrations(); +``` + +Or use the string-based overload to specify the context type name and a custom command name: + +```csharp title="AppHost.cs" +api.AddEFMigrations("app-migrations", contextTypeName: "AppDbContext"); +``` + +### Multiple DbContext types + +Call `AddEFMigrations` once per DbContext when your project has more than one: + +```csharp title="AppHost.cs" +api.AddEFMigrations(); +api.AddEFMigrations(); +``` + +Each call registers its own set of dashboard resource commands, named with the DbContext type as a suffix (for example, *Update Database (AppDbContext)*) to avoid confusion. + +## Run migrations automatically at startup + +Call `RunDatabaseUpdateOnStart()` to apply pending migrations when the AppHost starts: + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var db = builder.AddPostgres("postgres").AddDatabase("appdb"); + +var api = builder.AddProject("api") + .WithReference(db); + +var migrations = api.AddEFMigrations() + .RunDatabaseUpdateOnStart(); + +builder.Build().Run(); +``` + +`RunDatabaseUpdateOnStart` registers a health check on the migration resource. The migration runs after the `api` project resource becomes healthy (that is, after the project has started and its dependencies are ready). Other resources that call `WaitFor(migrations)` will not start until the migration completes successfully. + +### Wait for migrations before starting a dependent resource + +```csharp title="AppHost.cs" +var migrations = api.AddEFMigrations() + .RunDatabaseUpdateOnStart(); + +var worker = builder.AddProject("worker") + .WaitFor(migrations); +``` + +The `worker` project starts only after the database schema has been brought up to date. + +## Publish migration artifacts + +The hosting integration hooks into the `aspire publish` pipeline to generate migration artifacts automatically. + +### SQL migration script + +Generate a SQL script from pending migrations: + +```csharp title="AppHost.cs" +api.AddEFMigrations() + .PublishAsMigrationScript(); +``` + +The script is placed in the publish output directory next to the other published artifacts. + +### Migration bundle + +Generate a self-contained EF Core migration bundle executable: + +```csharp title="AppHost.cs" +api.AddEFMigrations() + .PublishAsMigrationBundle(); +``` + +The bundle includes the EF Core tooling and can be run as part of your deployment pipeline without requiring the .NET SDK on the target machine. + +### Customize output directory and namespace + +```csharp title="AppHost.cs" +api.AddEFMigrations() + .PublishAsMigrationScript() + .WithMigrationOutputDirectory("db/migrations") + .WithMigrationNamespace("MyApp.Migrations"); +``` + +## Use a separate migrations project + +When your migrations are defined in a dedicated project rather than the startup project, use `WithMigrationsProject`: + +```csharp title="AppHost.cs" +api.AddEFMigrations() + .WithMigrationsProject(); +``` + +Both the startup assembly and the migrations assembly are loaded together in the same `AssemblyLoadContext`, so EF Core tooling can resolve all required types. + +## Dashboard resource commands + +When `AddEFMigrations` is called, the following commands become available on the project resource in the Aspire dashboard: + +| Command | Equivalent CLI operation | +|---|---| +| **Update Database** | `dotnet ef database update` | +| **Drop Database** | `dotnet ef database drop` | +| **Reset Database** | `dotnet ef database drop` then `dotnet ef database update` | +| **Add Migration** | `dotnet ef migrations add ` (prompts for a migration name) | +| **Remove Migration** | `dotnet ef migrations remove` | +| **Get Database Status** | Shows applied migrations and pending model changes | + +:::tip +After running **Add Migration** or **Remove Migration**, the project must be recompiled for the changes to take effect. The dashboard displays a notification reminding you to rebuild. +::: + +## Configuration reference + +The following extension methods are available on `EFMigrationResourceBuilder`: + +| Method | Description | +|---|---| +| `RunDatabaseUpdateOnStart()` | Apply pending migrations when the AppHost starts | +| `PublishAsMigrationScript()` | Generate a SQL script during `aspire publish` | +| `PublishAsMigrationBundle()` | Generate a migration bundle during `aspire publish` | +| `WithMigrationOutputDirectory(path)` | Override the output directory for generated artifacts | +| `WithMigrationNamespace(ns)` | Set the namespace for the generated migration script | +| `WithMigrationsProject()` | Specify a separate project that contains the migration files | + + +For the manual migration service approach (without the hosting integration), see [Apply EF Core migrations in Aspire](/integrations/databases/efcore/migrations/). + From 58637b4c5ad62256bca69c242d8b684ac6a013a8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 5 May 2026 13:20:29 +0000 Subject: [PATCH 2/2] docs: remove duplicate ef-migrations-hosting.mdx (content already exists in migrations.mdx) Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/b593f89b-ce0d-4cb8-9574-f3ff93d35f53 Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../config/sidebar/integrations.topics.ts | 4 - .../efcore/ef-migrations-hosting.mdx | 181 ------------------ 2 files changed, 185 deletions(-) delete mode 100644 src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index e866c8cb7..1fb6789de 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -940,10 +940,6 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { label: 'Apply migrations', slug: 'integrations/databases/efcore/migrations', }, - { - label: 'EF migrations hosting integration', - slug: 'integrations/databases/efcore/ef-migrations-hosting', - }, { label: 'Seed data', slug: 'integrations/databases/efcore/seed-database', diff --git a/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx b/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx deleted file mode 100644 index eba06c0ef..000000000 --- a/src/frontend/src/content/docs/integrations/databases/efcore/ef-migrations-hosting.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Manage EF Core migrations with Aspire.Hosting.EntityFrameworkCore -description: Learn how to use the Aspire.Hosting.EntityFrameworkCore hosting integration to manage Entity Framework Core database migrations from your AppHost project. ---- - -import { Steps } from '@astrojs/starlight/components'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import LearnMore from '@components/LearnMore.astro'; - -The `Aspire.Hosting.EntityFrameworkCore` hosting integration lets you manage Entity Framework Core (EF Core) database migrations directly from your Aspire AppHost project. Rather than writing a separate migration worker service, you call `AddEFMigrations` on an existing project resource to register migration management capabilities, then use the fluent API to control how and when migrations run. - -Key capabilities include: - -- **Automatic migration at startup** — run `dotnet ef database update` automatically when the app starts, with full health-check integration so dependent resources wait until migrations complete. -- **Publish-time migration artifacts** — generate SQL migration scripts or self-contained migration bundles as part of the `aspire publish` pipeline. -- **Dashboard resource commands** — interactive commands appear on the project resource in the Aspire dashboard: *Update Database*, *Drop Database*, *Reset Database*, *Add Migration*, *Remove Migration*, and *Get Database Status*. -- **Multiple DbContext support** — call `AddEFMigrations` multiple times on the same project to manage separate DbContext types independently. -- **Separate migrations project** — use `WithMigrationsProject` when migrations live in a different project than the startup project. - -:::note -The `Aspire.Hosting.EntityFrameworkCore` package requires your project to reference `Microsoft.EntityFrameworkCore.Design`. The hosting integration validates this at startup and shows a diagnostic message if it is missing. -::: - -## Install the hosting integration - -In your AppHost project, install the `Aspire.Hosting.EntityFrameworkCore` NuGet package: - - - -## Add EF migrations to a project resource - -Call `AddEFMigrations` on an existing project resource: - -```csharp title="AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var api = builder.AddProject("api"); - -api.AddEFMigrations(); - -builder.Build().Run(); -``` - -When the AppHost runs, the dashboard shows additional resource commands on the `api` resource — one set for each registered DbContext. - -### Specify a DbContext type - -By default, `AddEFMigrations` discovers all DbContext types in the project. To target a specific context, use the generic overload: - -```csharp title="AppHost.cs" -api.AddEFMigrations(); -``` - -Or use the string-based overload to specify the context type name and a custom command name: - -```csharp title="AppHost.cs" -api.AddEFMigrations("app-migrations", contextTypeName: "AppDbContext"); -``` - -### Multiple DbContext types - -Call `AddEFMigrations` once per DbContext when your project has more than one: - -```csharp title="AppHost.cs" -api.AddEFMigrations(); -api.AddEFMigrations(); -``` - -Each call registers its own set of dashboard resource commands, named with the DbContext type as a suffix (for example, *Update Database (AppDbContext)*) to avoid confusion. - -## Run migrations automatically at startup - -Call `RunDatabaseUpdateOnStart()` to apply pending migrations when the AppHost starts: - -```csharp title="AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var db = builder.AddPostgres("postgres").AddDatabase("appdb"); - -var api = builder.AddProject("api") - .WithReference(db); - -var migrations = api.AddEFMigrations() - .RunDatabaseUpdateOnStart(); - -builder.Build().Run(); -``` - -`RunDatabaseUpdateOnStart` registers a health check on the migration resource. The migration runs after the `api` project resource becomes healthy (that is, after the project has started and its dependencies are ready). Other resources that call `WaitFor(migrations)` will not start until the migration completes successfully. - -### Wait for migrations before starting a dependent resource - -```csharp title="AppHost.cs" -var migrations = api.AddEFMigrations() - .RunDatabaseUpdateOnStart(); - -var worker = builder.AddProject("worker") - .WaitFor(migrations); -``` - -The `worker` project starts only after the database schema has been brought up to date. - -## Publish migration artifacts - -The hosting integration hooks into the `aspire publish` pipeline to generate migration artifacts automatically. - -### SQL migration script - -Generate a SQL script from pending migrations: - -```csharp title="AppHost.cs" -api.AddEFMigrations() - .PublishAsMigrationScript(); -``` - -The script is placed in the publish output directory next to the other published artifacts. - -### Migration bundle - -Generate a self-contained EF Core migration bundle executable: - -```csharp title="AppHost.cs" -api.AddEFMigrations() - .PublishAsMigrationBundle(); -``` - -The bundle includes the EF Core tooling and can be run as part of your deployment pipeline without requiring the .NET SDK on the target machine. - -### Customize output directory and namespace - -```csharp title="AppHost.cs" -api.AddEFMigrations() - .PublishAsMigrationScript() - .WithMigrationOutputDirectory("db/migrations") - .WithMigrationNamespace("MyApp.Migrations"); -``` - -## Use a separate migrations project - -When your migrations are defined in a dedicated project rather than the startup project, use `WithMigrationsProject`: - -```csharp title="AppHost.cs" -api.AddEFMigrations() - .WithMigrationsProject(); -``` - -Both the startup assembly and the migrations assembly are loaded together in the same `AssemblyLoadContext`, so EF Core tooling can resolve all required types. - -## Dashboard resource commands - -When `AddEFMigrations` is called, the following commands become available on the project resource in the Aspire dashboard: - -| Command | Equivalent CLI operation | -|---|---| -| **Update Database** | `dotnet ef database update` | -| **Drop Database** | `dotnet ef database drop` | -| **Reset Database** | `dotnet ef database drop` then `dotnet ef database update` | -| **Add Migration** | `dotnet ef migrations add ` (prompts for a migration name) | -| **Remove Migration** | `dotnet ef migrations remove` | -| **Get Database Status** | Shows applied migrations and pending model changes | - -:::tip -After running **Add Migration** or **Remove Migration**, the project must be recompiled for the changes to take effect. The dashboard displays a notification reminding you to rebuild. -::: - -## Configuration reference - -The following extension methods are available on `EFMigrationResourceBuilder`: - -| Method | Description | -|---|---| -| `RunDatabaseUpdateOnStart()` | Apply pending migrations when the AppHost starts | -| `PublishAsMigrationScript()` | Generate a SQL script during `aspire publish` | -| `PublishAsMigrationBundle()` | Generate a migration bundle during `aspire publish` | -| `WithMigrationOutputDirectory(path)` | Override the output directory for generated artifacts | -| `WithMigrationNamespace(ns)` | Set the namespace for the generated migration script | -| `WithMigrationsProject()` | Specify a separate project that contains the migration files | - - -For the manual migration service approach (without the hosting integration), see [Apply EF Core migrations in Aspire](/integrations/databases/efcore/migrations/). -