2026年5月5日に確認されたMicrosoft developer platformのdocumentation updateで押さえるべき結論は、Aspire.Hosting.EntityFrameworkCoreの新しい説明ページが単純に追加されたわけではなく、既存のEF Core migrationsドキュメントとの重複が見つかり、最終的にPR #815は差分なしとして閉じられたという点です。一方で、開発者が見るべき実務上の変更は明確です。Aspire AppHostでEF Coreマイグレーションを扱うAddEFMigrations、RunDatabaseUpdateOnStart()、PublishAsMigrationScript()、PublishAsMigrationBundle()の確認が必要になります。特に、従来の手動Worker Service方式を使っているチーム、複数DbContextを持つサービス、CI/CDでマイグレーション成果物を生成しているチームは、設定の重複や実行タイミングを見直すべきです。(GitHub)
今回のMicrosoft developer platform documentation updateで何が起きたのか
今回の更新対象は、GitHub上のmicrosoft/aspire.devリポジトリにあるPR #815「[docs] Add Aspire.Hosting.EntityFrameworkCore hosting integration documentation」です。
このPRは、microsoft/aspire#13481で導入されたAspire.Hosting.EntityFrameworkCoreのホスティング統合について、Aspire公式サイト側にドキュメントを追加する目的で作成されました。対象ブランチはrelease/13.3で、PR本文ではAspire.Hosting.EntityFrameworkCore NuGetパッケージ、AddEFMigrations()、RunDatabaseUpdateOnStart()、公開時のマイグレーション成果物生成などを説明する新規ページを追加する予定だったことが示されています。(GitHub)
ただし、レビューの過程で「内容の多くは既存ページにすでに入っている」と指摘されました。その結果、追加予定だったef-migrations-hosting.mdxとサイドバー項目は削除され、PRは実質的に差分なしの状態で閉じられています。つまり、5月5日の更新は“新機能の追加通知”というより、既存ドキュメントとの重複整理と確認のための更新と捉えるのが正確です。(GitHub)
読者が確認すべき変更点
今回のポイントは、PR #815そのものが最終的に空になったことではなく、AspireにおけるEF Coreマイグレーションの説明が、手動の移行サービス方式だけでなく、AppHost APIによる自動化方式まで広がっていることです。
特に確認したいのは次の4点です。
| 確認項目 | 内容 | 実務での意味 |
|---|---|---|
Aspire.Hosting.EntityFrameworkCore | AppHost側でEF Coreマイグレーション管理を扱うためのパッケージ | 既存のWorker Service方式以外の選択肢が増える |
AddEFMigrations() | プロジェクトリソースにマイグレーション用リソースを追加するAPI | AppHost上でマイグレーションを明示的に管理できる |
RunDatabaseUpdateOnStart() | ローカル実行時にDB更新を自動実行する設定 | 開発環境で毎回手動実行する手間を減らせる |
PublishAsMigrationScript() / PublishAsMigrationBundle() | aspire publish時にSQLスクリプトやバンドルを生成する設定 | CI/CDや本番展開前のDB変更確認に使える |
既存のPR #774では、migrations.mdxに「Automated EF migrations with AddEFMigrations」セクションが追加され、パッケージ導入、AppHost設定、ローカル実行時の動作、公開時の成果物生成、publishContainer: trueを使ったコンテナ化まで説明対象に含められました。(GitHub)
対応すべきチームと対応不要なチーム
すべてのMicrosoft developer platform利用者がすぐに修正する必要があるわけではありません。影響を受けるのは、主に.NET AspireとEF Coreを組み合わせて使っている開発チームです。
| 対象 | 対応優先度 | 理由 |
|---|---|---|
| Aspire AppHostでEF Coreを使っている | 高 | AddEFMigrationsを導入できるか確認する価値がある |
| 手動のMigration Worker Serviceを作っている | 高 | 新APIと処理が重複しないか確認が必要 |
| 複数のDbContextを1つのサービスで扱っている | 高 | DbContext指定やリソース名の整理が必要 |
aspire publishをCI/CDに組み込んでいる | 中〜高 | マイグレーションスクリプトやバンドル生成の使い分けを検討できる |
| EF Coreを使っていないAspireプロジェクト | 低 | 今回の更新による直接影響は小さい |
| Aspireを使っていない通常のASP.NET Coreアプリ | 低 | EF Core自体の基本的なマイグレーション運用は従来通り |
特に注意したいのは、すでに自前のWorker ServiceでDatabase.MigrateAsync()を実行しているケースです。そこへRunDatabaseUpdateOnStart()を安易に追加すると、開発環境で同じマイグレーション処理を二重に設計してしまう可能性があります。EF Coreマイグレーションは通常、適用済み履歴を見て差分実行されますが、実行タイミングやシード処理まで重なると、期待しないデータ投入や起動順の問題につながります。
Aspire.Hosting.EntityFrameworkCoreでできること
Aspire.Hosting.EntityFrameworkCoreは、Aspire AppHostからEF Coreマイグレーション管理を行うためのホスティング統合です。リポジトリのREADMEでは、対象プロジェクトがMicrosoft.EntityFrameworkCore.Designを参照する必要があること、AppHostにAspire.Hosting.EntityFrameworkCoreを追加すること、AddEFMigrationsでマイグレーションリソースを定義することが説明されています。(GitHub)
基本イメージは次のようになります。
dotnet add package Aspire.Hosting.EntityFrameworkCorevar db = builder.AddPostgres("pg")
.AddDatabase("appdb");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(db);
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext");この設定により、AppHost上でAPIプロジェクトに紐づくEF Coreマイグレーションリソースを扱えるようになります。DbContextが1つだけなら型名指定を省略できる場合がありますが、複数DbContextがある場合は、どのDbContextに対するマイグレーションなのかを明示するほうが安全です。
ダッシュボードから使える操作
AddEFMigrationsを呼び出すと、Aspire Dashboard上でマイグレーション関連のコマンドを扱えるようになります。READMEでは、Update Database、Drop Database、Reset Database、Add Migration、Remove Migration、Get Database Statusなどのコマンドが示されています。(GitHub)
| コマンド | 用途 | 注意点 |
|---|---|---|
| Update Database | 未適用のマイグレーションをDBに適用 | 開発DB向けに使うのが基本 |
| Drop Database | DBを削除 | 誤操作防止のため対象環境を確認 |
| Reset Database | DBを削除して再作成 | シードデータや検証用データが消える可能性がある |
| Add Migration | 新しいマイグレーションを作成 | 作成後は対象プロジェクトの再ビルドが必要 |
| Remove Migration | 直近のマイグレーションを削除 | 適用済みDBとの整合性に注意 |
| Get Database Status | 現在のマイグレーション状態を確認 | CI前や動作確認時に有用 |
実務では、これらの操作を本番DB向けの手軽な管理画面として使うのではなく、ローカル開発や検証環境での状態確認・マイグレーション作成補助として使うのが安全です。
RunDatabaseUpdateOnStart()はローカル起動の自動化として考える
RunDatabaseUpdateOnStart()は、AppHost起動時にマイグレーションを自動適用するための設定です。
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.RunDatabaseUpdateOnStart();
api.WaitForCompletion(apiMigrations);公式ドキュメントの更新内容では、RunDatabaseUpdateOnStart()はローカル実行モードに関係する説明として扱われています。aspire publishや実際のデプロイで同じように自動実行されると考えると誤解しやすいため、環境ごとの実行タイミングを分けて設計する必要があります。(GitHub)
実務での判断基準は次の通りです。
| 利用シーン | RunDatabaseUpdateOnStart()の適性 | 理由 |
|---|---|---|
| ローカル開発DBを毎回作り直す | 向いている | 起動時にスキーマを整えやすい |
| チーム内の検証環境 | 条件付きで有効 | DB初期化ルールを明確にすれば便利 |
| 本番環境 | 慎重に判断 | DB変更は承認・バックアップ・ロールバック設計が必要 |
| 複数サービスが同じDBを参照 | 要設計 | 起動順と同時実行を管理する必要がある |
本番に近い環境では、起動時に自動でDBスキーマを書き換えるより、マイグレーションスクリプトやバンドルをCI/CDで生成し、レビューや承認プロセスを通して適用するほうが安全です。
PublishAsMigrationScript()とPublishAsMigrationBundle()の使い分け
今回のドキュメント更新で実務上重要なのは、ローカル起動だけでなく、公開時の成果物生成にも触れられている点です。
PublishAsMigrationScript()はSQLスクリプトを生成する用途、PublishAsMigrationBundle()はEF Coreのマイグレーションバンドルを生成する用途で使います。PR #774では、これらをaspire publish時のパイプラインに組み込む説明が追加されています。(GitHub)
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.PublishAsMigrationScript()
.PublishAsMigrationBundle();使い分けは次のように考えると分かりやすいです。
| 方法 | 向いているケース | メリット | 注意点 |
|---|---|---|---|
| SQLスクリプト | DBAレビューが必要な組織 | 差分を人が確認しやすい | 実行環境ごとの接続管理が必要 |
| Migration Bundle | CI/CDで実行したい場合 | 実行単位を成果物として扱える | 実行タイミングと接続文字列の管理が必要 |
| Container化したBundle | コンテナ環境で一度だけ実行したい場合 | デプロイ資産として扱いやすい | 再起動ポリシーを誤ると繰り返し実行される可能性がある |
publishContainer: trueを使う場合の注意点
PublishAsMigrationBundle(publishContainer: true)を使うと、生成したマイグレーションバンドルをコンテナイメージとして扱えるようになります。PR #774では、このオプションが13.3向けの新しい説明として扱われ、Docker Compose、Azure Container Apps、Kubernetesなどの環境ごとの再起動防止パターンにも触れられています。(GitHub)
例として、ドキュメントでは次のような構成が示されています。
var db = builder.AddPostgres("pg")
.AddDatabase("appdb");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(db);
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.WithReference(db)
.WaitFor(db)
.PublishAsMigrationBundle(publishContainer: true);ここで重要なのは、マイグレーション用コンテナがDBへ接続できること、DBが利用可能になってから実行されることです。ドキュメント更新では、publishContainer: trueを使う場合に.WithReference(db)と.WaitFor(db)を確認する説明が含まれています。(GitHub)
また、マイグレーションバンドルは基本的に再実行しても差分がなければ何もしない設計ですが、コンテナオーケストレーション側が終了したコンテナを自動再起動する設定になっていると、運用上のノイズや不要な再実行につながります。Docker Composeではrestart設定、Azure Container AppsではJob化、KubernetesではJobやrestartPolicyの調整を検討する必要があります。
既存プロジェクトで確認する手順
今回のMicrosoft developer platform documentation updateを受けて、既存プロジェクトでは次の順番で確認すると効率的です。
| 手順 | 確認内容 | 判断ポイント |
| -: | ——————————————– | ————————————– |
| 1 | AspireとEF Coreを組み合わせているか | 対象外なら対応不要 |
| 2 | 既存のマイグレーション実行方法を確認 | Worker Service、手動CLI、CI/CDのどれか |
| 3 | Aspire.Hosting.EntityFrameworkCoreを導入するか判断 | AppHostで一元管理したいなら候補 |
| 4 | DbContextの数を確認 | 複数なら型名指定やリソース名を明確にする |
| 5 | ローカル起動時の自動適用を使うか判断 | RunDatabaseUpdateOnStart()は開発環境中心に検討 |
| 6 | 公開時の成果物を決める | SQLスクリプト、Bundle、Container Bundleを選ぶ |
| 7 | CI/CDと本番適用手順を確認 | 自動適用、承認、ロールバックを分けて設計 |
| 8 | 重複実行を防ぐ | Worker ServiceとAddEFMigrationsの併用に注意 |
特に、すでに以下のようなコードを持つWorker Serviceがある場合は要注意です。
await dbContext.Database.MigrateAsync(cancellationToken);この処理を残したまま、AppHost側でもRunDatabaseUpdateOnStart()を設定すると、マイグレーションの責任範囲が分かれます。シンプルなプロジェクトならAddEFMigrationsへ寄せる、複雑なシード処理や業務固有の初期化があるならWorker Serviceを維持する、というように役割を明確にしましょう。
移行判断：Worker Service方式をやめるべきか
AddEFMigrationsがあるからといって、既存のWorker Service方式を必ず廃止すべきとは限りません。むしろ、どちらが運用に合うかを判断することが大切です。
| 比較項目 | Worker Service方式 | AddEFMigrations方式 |
|---|---|---|
| 実装の自由度 | 高い | 標準APIの範囲で整理しやすい |
| シード処理との統合 | しやすい | DB更新中心に考える必要がある |
| AppHostでの見通し | やや分散しやすい | AppHostに集約しやすい |
| Dashboard操作 | 自前実装が必要 | コマンドとして扱いやすい |
| CI/CD成果物生成 | 別途設計が必要 | PublishAsMigrationScript()などを使いやすい |
| 初心者への分かりやすさ | コード量が多い | 設定の意図が見えやすい |
おすすめの判断は次の通りです。
単純に「起動時にDBスキーマを整えたい」「開発環境でマイグレーション操作を見やすくしたい」なら、AddEFMigrations方式を検討する価値があります。
一方で、「マイグレーション後に複雑な初期データ投入を行う」「外部APIや複数DBをまたぐ初期化処理がある」「業務要件上、マイグレーション処理を独立したアプリケーションとして監視したい」場合は、Worker Service方式を維持するほうが扱いやすいことがあります。
設定時に失敗しやすいポイント
Microsoft.EntityFrameworkCore.Designの参照不足
AddEFMigrationsを使う対象プロジェクトでは、EF Coreのデザイン時機能が必要になります。READMEでは、対象プロジェクトがMicrosoft.EntityFrameworkCore.Designを参照する必要があることが説明されています。(GitHub)
ただし、dotnet add packageで追加した場合のPrivateAssets設定により、マイグレーションコマンド側から期待通り参照できない可能性がある点にも注意が必要です。導入後は、DashboardからGet Database StatusやAdd Migrationを実行し、コマンドが正しく動くか確認しましょう。
複数DbContextで型指定を省略する
1つのプロジェクトに複数のDbContextがある場合、AddEFMigrations("api-migrations")だけでは、どのDbContextを対象にするのかが曖昧になります。
この場合は、次のように完全修飾名を指定する運用にしたほうが安全です。
var userMigrations = api.AddEFMigrations(
"user-migrations",
"MyApp.Data.UserDbContext");
var orderMigrations = api.AddEFMigrations(
"order-migrations",
"MyApp.Data.OrderDbContext");リソース名もapi-migrationsのように汎用的にせず、user-migrations、order-migrationsのように対象を分けると、Dashboard上の操作ミスを減らせます。
ローカル実行と公開時実行を混同する
RunDatabaseUpdateOnStart()はローカル起動時の自動化として便利ですが、公開時のマイグレーション適用とは別に考える必要があります。公開時はPublishAsMigrationScript()やPublishAsMigrationBundle()を使い、生成した成果物を誰が、どのタイミングで、どの接続先に対して実行するかを決めるべきです。
コンテナ化したマイグレーションの再起動設定を忘れる
publishContainer: trueでマイグレーションバンドルをコンテナ化する場合、実行後にコンテナが終了します。環境によっては終了したコンテナを再起動しようとするため、Docker Compose、Azure Container Apps、Kubernetesごとに「一度実行して止める」設定を検討してください。
PR #815だけを見て「新規ページが追加された」と判断する
今回のPR #815は、当初は新しいページを追加する方針でしたが、既存のmigrations.mdxに内容があると判断され、重複ページは削除されました。したがって、確認先はPR #815だけでなく、既存のApply migrationsドキュメントとPR #774の変更内容です。(GitHub)
実務でのおすすめ対応
今回の更新を受けた実務対応は、次の3パターンに分けると整理しやすくなります。
ローカル開発を楽にしたい場合
ローカルのコンテナDBを頻繁に作り直すチームは、AddEFMigrationsとRunDatabaseUpdateOnStart()を検討しましょう。
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.RunDatabaseUpdateOnStart();
api.WaitForCompletion(apiMigrations);この構成にすると、APIやWorkerがDBスキーマ未作成の状態で起動して失敗するリスクを下げられます。ただし、既存のWorker Serviceが同じ処理をしていないか確認してください。
CI/CDでDB変更を管理したい場合
本番やステージングでは、起動時に自動でDB更新するより、成果物を作ってレビューする流れが向いています。
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.PublishAsMigrationScript()
.PublishAsMigrationBundle();SQLレビューが必要な組織ではスクリプトを、パイプラインで実行したい場合はバンドルを中心に検討するとよいでしょう。
コンテナ環境で一度だけ実行したい場合
コンテナベースの環境に合わせたい場合は、publishContainer: trueを検討できます。
var apiMigrations = api.AddEFMigrations(
"api-migrations",
"MyApp.Data.AppDbContext")
.WithReference(db)
.WaitFor(db)
.PublishAsMigrationBundle(publishContainer: true);この場合は、接続文字列、DB起動待ち、再起動ポリシーの3点を必ず確認してください。特にKubernetesではDeploymentではなくJobとして扱う設計が必要になることがあります。
まず確認すべきチェックリスト
最後に、今回のMicrosoft developer platform documentation updateを受けて、開発チームで確認すべき項目をまとめます。
| チェック | 確認内容 |
|---|---|
| □ | Aspire AppHostでEF Coreを使っているか |
| □ | 既存のマイグレーション実行方法を棚卸ししたか |
| □ | Worker ServiceとAddEFMigrationsが重複していないか |
| □ | 対象プロジェクトにMicrosoft.EntityFrameworkCore.Design参照があるか |
| □ | 複数DbContextの場合、対象DbContextを明示しているか |
| □ | RunDatabaseUpdateOnStart()を本番用途と誤解していないか |
| □ | PublishAsMigrationScript()またはPublishAsMigrationBundle()の使い道を決めたか |
| □ | publishContainer: trueを使う場合、DB参照と起動待ちを設定したか |
| □ | コンテナの再起動ポリシーを環境別に確認したか |
| □ | PR #815ではなく、既存のmigrations.mdxとPR #774の内容も確認したか |
今回の更新は、表面上は「ドキュメント追加PRが閉じられた」という小さな動きに見えます。しかし実務では、Aspire AppHostでEF Coreマイグレーションを管理する選択肢が整理され、ローカル開発、Dashboard操作、CI/CDでの成果物生成を見直すきっかけになります。
まずは自分のプロジェクトで、マイグレーションを「どこで」「いつ」「誰の責任で」実行しているかを確認しましょう。そのうえで、単純な開発環境の自動化にはAddEFMigrations、本番適用にはスクリプトやバンドル、複雑な初期化にはWorker Serviceというように、用途別に使い分けるのが安全です。
コメント