Microsoft developer platform documentation updateのうち、今回確認すべきポイントは、.NET AspireのAppHostイベント購読で builder.Eventing.Subscribe<T>() だけを使う説明から、IDistributedApplicationBuilder に追加された簡潔な拡張メソッドを使う説明へ整理されたことです。既存コードが直ちに壊れる変更ではありませんが、AppHostに直接イベント処理を書いている場合は、OnBeforeStart、OnBeforePublish、OnAfterPublish へ置き換えられる箇所を確認すると、コードの意図が読み取りやすくなります。
一方で、すべてのイベント購読を新しい書き方に置き換えるべきではありません。IDistributedApplicationEventingSubscriber の中、AfterResourcesCreatedEvent、リソース単位のイベント、独自イベントでは、引き続き Eventing.Subscribe<T>() を使う場面があります。今回の更新は「低レベルAPIの廃止」ではなく、「AppHostレベルの主要イベントをより発見しやすくするためのドキュメント更新」と捉えるのが実務上は安全です。
Microsoft developer platform documentation updateで何が変わったのか
今回の更新は、Microsoft developer platformの一部である .NET Aspire のAppHost eventingドキュメントに関するものです。GitHub上では、microsoft/aspire のPR #14119で IDistributedApplicationBuilder 向けのAppHostレベルイベント購読ヘルパーが追加され、その内容を microsoft/aspire.dev のPR #821がドキュメント化しています。PR #821は2026年5月5日に作成され、2026年5月6日に release/13.3 ブランチへマージされています。(GitHub)
ドキュメント更新の中心は、AppHostイベント購読の例を builder.Eventing.Subscribe<T>() から、ビルダーに直接呼び出せる builder.OnBeforeStart() などの拡張メソッドへ変更した点です。PR #821の説明では、追加された便利メソッドとして OnBeforeStart、OnBeforePublish、OnAfterPublish の3つが明記されています。(GitHub)
| 変更点 | 従来の書き方 | 新しく推奨される書き方 | 実務上の意味 |
|---|---|---|---|
| AppHost開始前イベント | builder.Eventing.Subscribe<BeforeStartEvent>(...) | builder.OnBeforeStart(...) | AppHost起動前に行う検証や初期設定が読みやすくなる |
| Publish前イベント | builder.Eventing.Subscribe<BeforePublishEvent>(...) | builder.OnBeforePublish(...) | manifest生成前の検証や調整を明示しやすい |
| Publish後イベント | builder.Eventing.Subscribe<AfterPublishEvent>(...) | builder.OnAfterPublish(...) | publish後の後処理をAppHostコード上で把握しやすい |
| 高度な購読処理 | Eventing.Subscribe<T>() | 原則そのまま | Subscriber、独自イベント、対象外イベントでは従来APIを使う |
追加された3つの拡張メソッド
今回のドキュメント更新で特に確認すべき IDistributedApplicationBuilder の拡張メソッドは、次の3つです。公式ドキュメントでも、AppHostイベント用のbuilder-level extension methodとしてこの3つが示されています。(Aspire)
| メソッド | 対応イベント | 主な用途 |
|---|---|---|
OnBeforeStart | BeforeStartEvent | AppHost起動前の検証、ログ出力、リソースモデル確認 |
OnBeforePublish | BeforePublishEvent | manifest生成前の検証、publish前のリソース調整 |
OnAfterPublish | AfterPublishEvent | publish後のログ出力、後処理、結果確認 |
たとえば、AppHost起動前にログを出すだけなら、従来の Eventing.Subscribe<BeforeStartEvent>() よりも次のように書けます。
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
var builder = DistributedApplication.CreateBuilder(args);
builder.OnBeforeStart(static (@event, cancellationToken) =>
{
var logger = @event.Services.GetRequiredService<ILogger<Program>>();
logger.LogInformation("AppHost is about to start.");
return Task.CompletedTask;
});
builder.Build().Run();この書き方の利点は、イベント購読の意図がメソッド名から分かることです。Subscribe<BeforeStartEvent> は柔軟ですが、初見のコードでは「何に対する購読なのか」を型引数まで読まないと分かりません。OnBeforeStart であれば、AppHost開始前の処理だとすぐ判断できます。
既存コードへの影響範囲
今回の変更で影響を受けやすいのは、.NET AspireのAppHostをカスタマイズしているプロジェクトです。特に、AppHost.cs や独自のHosting拡張ライブラリで builder.Eventing.Subscribe<T>() を使っている場合は確認対象になります。
対応した方がよいプロジェクト
次のいずれかに当てはまる場合は、コード検索して置き換え可否を確認してください。
AppHost.csにbuilder.Eventing.Subscribe<BeforeStartEvent>を書いている- publish時のmanifest生成前後に処理を入れている
- AspireのカスタムリソースやHosting拡張を作っている
- チーム内でAppHostコードの可読性を高めたい
- 今後のAspire 13.3系ドキュメントに合わせてサンプルコードを更新したい
逆に、AppHostイベントを使っていない通常のアプリケーションコードには、直接の作業はほとんどありません。Web API、フロントエンド、データベース接続など、Aspireのリソース定義だけを使っているプロジェクトでは、今回の更新による修正は不要なことが多いです。
置き換えてよいコードと残すべきコード
今回の更新で重要なのは、「Eventing.Subscribe<T>() をすべて置き換える」のではなく、「AppHostのbuilderに直接書いている対象イベントだけを置き換える」ことです。公式ドキュメントでも、IDistributedApplicationEventing を直接使う必要がある場合は、低レベルAPIである Eventing.Subscribe<T>() を使えると説明されています。(Aspire)
置き換えてよい例
builder に直接 BeforeStartEvent を購読している場合は、基本的に OnBeforeStart へ置き換えられます。
builder.Eventing.Subscribe<BeforeStartEvent>((@event, cancellationToken) =>
{
// 起動前の処理
return Task.CompletedTask;
});置き換え後は次のようになります。
builder.OnBeforeStart((@event, cancellationToken) =>
{
// 起動前の処理
return Task.CompletedTask;
});BeforePublishEvent と AfterPublishEvent も同じ考え方です。
builder.OnBeforePublish((@event, cancellationToken) =>
{
// manifest生成前の検証
return Task.CompletedTask;
});
builder.OnAfterPublish((@event, cancellationToken) =>
{
// publish後の後処理
return Task.CompletedTask;
});そのまま残すべき例
IDistributedApplicationEventingSubscriber の中では、IDistributedApplicationBuilder ではなく IDistributedApplicationEventing を受け取るため、今回のbuilder拡張メソッドは使えません。PR #14119の説明でも、IDistributedApplicationEventingSubscriber の実装は移行できなかった主なケースとして挙げられています。(GitHub)
internal sealed class LifecycleLoggerSubscriber : IDistributedApplicationEventingSubscriber
{
public Task SubscribeAsync(
IDistributedApplicationEventing eventing,
DistributedApplicationExecutionContext executionContext,
CancellationToken cancellationToken)
{
eventing.Subscribe<BeforeStartEvent>((@event, ct) =>
{
// Subscriber内では従来のSubscribeを使う
return Task.CompletedTask;
});
return Task.CompletedTask;
}
}また、AfterResourcesCreatedEvent についても注意が必要です。AppHostのライフサイクルイベントとしては存在しますが、今回のドキュメント更新で追加されたbuilder-level extension methodの一覧には OnAfterResourcesCreated は含まれていません。必要な場合は、従来どおり builder.Eventing.Subscribe<AfterResourcesCreatedEvent>() を使います。(Aspire)
builder.Eventing.Subscribe<AfterResourcesCreatedEvent>((@event, cancellationToken) =>
{
// リソース作成後に実行したい処理
return Task.CompletedTask;
});移行時の実務チェックリスト
既存プロジェクトを更新する場合は、次の順番で確認すると安全です。
| 確認項目 | 見るべき場所 | 判断基準 |
|---|---|---|
| Aspireの対象バージョン | AppHostプロジェクトのパッケージ、CLI、リリースブランチ | 13.3系の変更を取り込んでいるか確認する |
Eventing.Subscribe<T>() の利用箇所 | AppHost.cs、Hosting拡張、テストコード | 対象イベントが BeforeStartEvent、BeforePublishEvent、AfterPublishEvent か確認する |
| Subscriber内の購読 | IDistributedApplicationEventingSubscriber 実装 | OnBeforeStart へ置き換えず、eventing.Subscribe<T>() を残す |
AfterResourcesCreatedEvent の購読 | AppHostコード、Subscriber | OnAfterResourcesCreated は前提にせず、従来APIを使う |
| publish時の動作 | CI/CD、aspire publish、manifest生成処理 | OnBeforePublish と OnAfterPublish が期待タイミングで動くか確認する |
| イベント処理の重さ | イベントハンドラー内の処理 | 起動やpublishを遅らせる処理を入れていないか確認する |
検索するなら、まず次のキーワードでリポジトリ全体を確認します。
Eventing.Subscribe<BeforeStartEvent>
Eventing.Subscribe<BeforePublishEvent>
Eventing.Subscribe<AfterPublishEvent>
Eventing.Subscribe<AfterResourcesCreatedEvent>
IDistributedApplicationEventingSubscriber置き換え対象を絞ったら、単純な文字列置換ではなく、呼び出し元が builder なのか、builder.ApplicationBuilder なのか、eventing なのかを確認してください。特に拡張ライブラリでは、IResourceBuilder<T>.ApplicationBuilder 経由でAppHost builderにアクセスしていることがあります。
よくある失敗ポイント
OnAfterResourcesCreated があると思い込む
今回の更新で追加された主なbuilder拡張メソッドは OnBeforeStart、OnBeforePublish、OnAfterPublish です。AfterResourcesCreatedEvent はAppHostライフサイクル上の重要なイベントですが、C#のbuilder拡張メソッドとして OnAfterResourcesCreated が使える前提でコードを書くと、バージョンやAPI面でつまずく可能性があります。
AfterResourcesCreatedEvent を使いたい場合は、次のように従来APIを使うのが安全です。
builder.Eventing.Subscribe<AfterResourcesCreatedEvent>((@event, cancellationToken) =>
{
// Dashboard表示後、リソース作成後に必要な処理
return Task.CompletedTask;
});Subscriber内まで機械的に置き換える
IDistributedApplicationEventingSubscriber は、AppHostコードをすっきり分離したい場合や、拡張ライブラリとしてライフサイクル処理を提供したい場合に使います。この実装内では IDistributedApplicationEventing を受け取るため、builder.OnBeforeStart() のような書き方はできません。
Subscriber内の購読を無理に置き換えようとすると、設計を崩したり、不要にbuilderへの依存を増やしたりする原因になります。Subscriberでは eventing.Subscribe<T>() を使う、AppHost直下では builder.OnBeforeStart() を使う、と分けて考えるのが実務的です。
重い処理をイベントハンドラーに入れる
イベントハンドラーは便利ですが、起動やpublishの流れに影響します。公式ドキュメントでは、イベントのdispatch behaviorには blocking / non-blocking、sequential / concurrent の選択肢があり、既定では BlockingSequential と説明されています。また、イベントによっては処理が終わるまで実行がブロックされる点にも触れられています。(Aspire)
そのため、OnBeforeStart に長時間かかる外部API呼び出しや重いファイル処理を入れると、AppHostの起動が遅くなります。必要であれば、イベント内では検証や登録だけにとどめ、時間のかかる処理は別のリソース、CI/CDステップ、または非同期ジョブに逃がすべきです。
OnBeforePublish が通常起動でも動くと思う
OnBeforePublish と OnAfterPublish は、アプリケーションをpublishしてmanifestを生成する流れで使うイベントです。通常のAppHost起動時に必ず実行される初期化処理を入れたいなら、OnBeforeStart を使います。公式ドキュメントでも、publishing eventsはアプリケーションのpublish、つまりdeployment manifest生成時に発生するイベントとして説明されています。(Aspire)
具体的な活用シーン
起動前にリソース定義を検証する
OnBeforeStart は、AppHostが起動する前にモデルやサービスを確認したい場合に向いています。たとえば、開発環境で必須パラメーターが設定されているか、特定のリソース名が命名規則に合っているかを確認できます。
builder.OnBeforeStart((@event, cancellationToken) =>
{
var invalidResources = @event.Model.Resources
.Where(resource => resource.Name.Contains("_", StringComparison.Ordinal))
.Select(resource => resource.Name)
.ToArray();
if (invalidResources.Length > 0)
{
throw new InvalidOperationException(
$"Resource names must not contain underscores: {string.Join(", ", invalidResources)}");
}
return Task.CompletedTask;
});このような検証は、起動後に問題が出るよりも早い段階で検出できるため、チーム開発では効果があります。ただし、検証ルールを厳しくしすぎるとローカル開発の邪魔になるため、環境ごとに有効・無効を切り替える設計も検討してください。
publish前にmanifest生成条件を確認する
OnBeforePublish は、publish前の最終確認に向いています。たとえば、Azureに出す前提のリソースだけ命名規則をチェックする、必須の環境変数が不足していないか確認する、といった使い方です。
builder.OnBeforePublish((@event, cancellationToken) =>
{
// 例: publish前の検証処理
// 必要に応じて、リソース定義や設定値を確認する
return Task.CompletedTask;
});ここで重要なのは、publish前検証を通常起動時の検証と混同しないことです。ローカル実行でも必要な検証は OnBeforeStart、manifest生成やデプロイ前提の検証は OnBeforePublish に分けると、イベントの責務が明確になります。
publish後の後処理をまとめる
OnAfterPublish は、publish完了後のログ出力や後処理に向いています。たとえば、生成物の場所をログに出す、チーム内の運用ルールに合わせた通知処理へつなげる、といった用途があります。
builder.OnAfterPublish((@event, cancellationToken) =>
{
// 例: publish後の処理
// ログ出力、後続処理、クリーンアップなど
return Task.CompletedTask;
});publish後処理では、外部通知やファイル操作を入れたくなりますが、失敗時の扱いを事前に決めておく必要があります。通知失敗でpublish全体を失敗扱いにするのか、警告ログだけにするのかをチームで決めておくと、CI/CDで不要な混乱を避けられます。
移行の判断基準
今回のMicrosoft developer platform documentation updateに対して、すべてのプロジェクトが急いで対応する必要はありません。判断基準は次のように整理できます。
| 状況 | 対応方針 |
|---|---|
| AppHostイベントを使っていない | 対応不要。リリースノート確認だけでよい |
BeforeStartEvent をAppHost直下で購読している | OnBeforeStart への置き換えを検討 |
BeforePublishEvent / AfterPublishEvent を使っている | OnBeforePublish / OnAfterPublish へ置き換えを検討 |
AfterResourcesCreatedEvent を使っている | 従来の Eventing.Subscribe<AfterResourcesCreatedEvent>() を維持 |
IDistributedApplicationEventingSubscriber を実装している | 従来の eventing.Subscribe<T>() を維持 |
| 独自イベントをpublish / subscribeしている | 原則として従来APIを維持 |
| 社内テンプレートやサンプルコードを管理している | 新しい書き方に更新しておくと今後の学習コストを下げられる |
実務では、まずAppHost直下の BeforeStartEvent だけを OnBeforeStart に置き換え、ビルドと起動を確認するのが安全です。その後、publish系イベントを使っているプロジェクトだけ OnBeforePublish と OnAfterPublish を確認すると、影響範囲を抑えながら更新できます。
次にやるべきこと
まず、AppHostプロジェクトで Eventing.Subscribe<BeforeStartEvent>、Eventing.Subscribe<BeforePublishEvent>、Eventing.Subscribe<AfterPublishEvent> を検索してください。呼び出し元が IDistributedApplicationBuilder であれば、新しい OnBeforeStart、OnBeforePublish、OnAfterPublish へ置き換える候補です。
次に、AfterResourcesCreatedEvent、リソースイベント、Subscriber内の購読は無理に置き換えないように分類します。最後に、通常起動とpublishの両方を実行し、イベントの実行順序、ログ、CI/CDへの影響を確認してください。
今回の更新は、AspireのイベントAPIをより読みやすくするための改善です。置き換えそのものよりも、「どのイベントがAppHost全体のものか」「どのイベントがresource単位か」「どの処理が起動時かpublish時か」を整理することが、保守しやすいAppHost設計につながります。
コメント