結論から言うと、Microsoft developer platformのAspireでaspire-py-starterを新規作成する場合、今後はdotnet new aspire-py-starterではなく、aspire new aspire-py-starterを使います。2026年5月5日のドキュメント更新では、FastAPIとReactのPythonスターターテンプレートが、C# AppHostベースからTypeScript AppHostベースへ移行したことが明文化されました。あわせて、Redisを含めて生成できる--use-redis-cacheオプションも追加されています。(GitHub)
この変更で、既存プロジェクトをすぐ作り直す必要はありません。既存の旧テンプレート由来プロジェクトは継続利用できます。ただし、新規作成手順、社内ハンズオン、CI/CDのスキャフォールド処理、README、開発環境チェックリストにdotnet new aspire-py-starterが残っている場合は修正対象です。(GitHub)
Microsoft developer platformのAspireドキュメント更新で何が変わったか
今回の更新は、microsoft/aspire#15574のコード変更を、microsoft/aspire.dev側のドキュメントに反映するものです。ドキュメントPRは2026年5月5日にrelease/13.3へマージされ、対象はaspire-py-starter、つまりFastAPIバックエンドとReactフロントエンドを含むPythonスターターです。(GitHub)
主な変更点は次のとおりです。
| 確認項目 | 変更前 | 変更後 | 実務での対応 |
|---|---|---|---|
| 新規作成コマンド | dotnet new aspire-py-starter | aspire new aspire-py-starter | README、手順書、研修資料、CIスクリプトを置き換える |
| AppHost | C# AppHost | TypeScript AppHost | AppHost.cs前提の説明やレビュー観点をapphost.ts前提に更新する |
| テンプレート方式 | dotnet newテンプレート | Aspire CLIテンプレート | Aspire CLIのインストールとバージョン確認を手順に入れる |
| 生成構成 | C#プロジェクト名を前提にした構成 | apphost.ts、app/、frontend/ | フォルダ構成を前提にした自動処理を見直す |
| Redis | ドキュメント上の明示が不足 | --use-redis-cacheで選択可能 | キャッシュを使う検証環境では明示的にtrueを指定する |
| .NET SDK | AppHost作成・実行で必要 | Pythonスターターのスキャフォールドや実行には不要 | Python/Reactのみのチームでは.NET SDK前提を外せる。ただし.NETプロジェクトを含む場合は別 |
ドキュメント上も、Aspire Starter App with FastAPI and ReactはTypeScript AppHostを使うPythonベースのスターターとして説明され、構成要素はapphost.ts、app/、frontend/に更新されています。(GitHub)
新しい作成コマンドはaspire new aspire-py-starter
これからPythonスターターを作る場合の基本コマンドは次のとおりです。
aspire new aspire-py-starterRedisキャッシュを含めて生成したい場合は、次のように指定します。
aspire new aspire-py-starter --use-redis-cache true--use-redis-cacheはtrueまたはfalseを受け取り、指定しない場合は対話的に確認されます。CI/CDやハンズオン教材のように実行結果を安定させたい場面では、trueまたはfalseを明示するのが安全です。(GitHub)
たとえば、Redisなしで最小構成を作る社内検証なら次のようにします。
aspire new aspire-py-starter --use-redis-cache false一方、キャッシュを使うAPIの挙動、Redis接続、OpenTelemetryの観測まで含めて試したい場合は、最初からRedisありで生成したほうが確認漏れを減らせます。
aspire new aspire-py-starter --use-redis-cache true生成されるプロジェクト構成で確認すべきポイント
新しいaspire-py-starterでは、AppHostがC#ではなくTypeScriptで生成されます。ドキュメントでは、FastAPIバックエンドをaddUvicornAppで管理し、Reactベースのフロントエンドを含む構成として説明されています。(GitHub)
| 生成物 | 役割 | 確認ポイント |
|---|---|---|
apphost.ts | Aspireのアプリ構成を定義するTypeScript AppHost | サービス追加、参照関係、起動順、ヘルスチェック、Redis有無をここで確認する |
app/ | FastAPIバックエンド | APIエンドポイント、Python依存関係、Uvicorn起動設定を確認する |
frontend/ | React + TypeScriptフロントエンド | Vite設定、API参照、ビルドスクリプトを確認する |
aspire.config.json | AppHostの言語、利用パッケージ、プロファイルを定義 | appHost.languageがtypescript/nodejsになっているか、必要なAspireパッケージが入っているかを見る |
.modules/ | TypeScript AppHost向けに生成されるSDK | aspire restoreやaspire run時のSDK再生成で問題が出ていないか確認する |
apphost.tsでは、FastAPIアプリがaddUvicornApp("app", "./app", "main:app")で追加され、ViteフロントエンドはaddViteApp("frontend", "./frontend")で追加されます。Redisを有効にした場合は、addRedis("cache")、.withReference(cache)、.waitFor(cache)のような接続・起動順の定義が含まれます。(GitHub)
aspire.config.json側では、AppHostのパスがapphost.ts、言語がtypescript/nodejsとして定義され、標準ではAspire.Hosting.JavaScriptとAspire.Hosting.Pythonがパッケージとして含まれます。Redisを使う場合は、Aspire.Hosting.Redisの追加も確認対象になります。(GitHub)
TypeScript AppHost移行で開発体験はどう変わるか
今回の変更は、Pythonスターターの「アプリ本体」がTypeScriptになるという意味ではありません。バックエンドはFastAPI、フロントエンドはReactのままです。変わるのは、複数サービスの起動、依存関係、エンドポイント、ヘルスチェック、デプロイ意図などを定義するAppHostの記述言語です。
MicrosoftのAspireブログでは、TypeScript AppHostでもリソース、参照、起動依存、エンドポイント、デプロイ成果物といったAppHostの考え方は同じで、違いは記述面がTypeScriptになる点だと説明されています。Node.js上でAppHostを書けるため、JavaScript/TypeScript中心のチームがC#に寄せずにAspireのアプリモデルを扱いやすくなります。(Microsoft for Developers)
実務上の変化は、次の3つです。
| 観点 | 影響 |
|---|---|
| 開発者のスキルセット | AppHostの編集はC#ではなくTypeScript中心になる |
| 開発環境 | Python、Node.js、Aspire CLI、コンテナランタイムの確認が重要になる |
| 自動化 | dotnet new前提の生成処理をAspire CLI前提に変更する必要がある |
TypeScript AppHostの前提として、MicrosoftのブログではNode.js 20以降、Docker DesktopやPodmanなどのOCI互換コンテナランタイム、Aspire CLIが挙げられています。また、.NET SDKはC# AppHostを書く場合や、アプリケーション構成に.NETプロジェクトが含まれる場合に必要とされています。(Microsoft for Developers)
つまり、Python + Reactだけのスターターを試すチームでは、.NET SDKを前提にしたオンボーディングを軽くできます。一方で、後からASP.NET Core APIやC#のAppHostを追加する場合は、.NET SDKが再び必要になる可能性があります。
対応が必要な人、すぐには対応不要な人
今回の変更は「既存プロジェクトが壊れる更新」ではなく、「これから作るプロジェクトの入口が変わる更新」と考えると整理しやすくなります。
| 読者・チーム | 対応の優先度 | やること |
|---|---|---|
| 新規にFastAPI + ReactのAspireアプリを作る人 | 高 | aspire new aspire-py-starterを使う |
| 社内テンプレートやハンズオン資料を管理している人 | 高 | dotnet new aspire-py-starterの記述を検索して置き換える |
| CI/CDでサンプルプロジェクトを自動生成しているチーム | 高 | Aspire CLIの導入、--use-redis-cacheの明示、生成後の構成チェックを入れる |
旧aspire-py-starterで作成済みの既存プロジェクト | 中 | すぐ作り直さず、移行メリットがある場合だけ検討する |
| C# AppHostを深くカスタマイズ済みのチーム | 低〜中 | 無理にTypeScript AppHostへ移行せず、現行構成を維持できるか確認する |
| Python/React中心でC#を使っていないチーム | 中〜高 | TypeScript AppHostへの移行で開発環境を簡素化できるか検討する |
既存プロジェクトについては、公式ドキュメント更新でも「旧テンプレートで作成済みのプロジェクトは継続して動作するが、新規プロジェクトではaspire new aspire-py-starterを使う」と整理されています。(GitHub)
旧手順から新手順へ置き換える実務チェックリスト
まず、リポジトリや社内ドキュメントに旧コマンドが残っていないか確認します。
grep -R "dotnet new aspire-py-starter" .見つかったら、原則として次のように置き換えます。
aspire new aspire-py-starterRedisを使わない手順であれば、対話プロンプトを避けるために明示しておくと運用しやすくなります。
aspire new aspire-py-starter --use-redis-cache falseRedis込みの教材や検証では、次のようにします。
aspire new aspire-py-starter --use-redis-cache true次に、生成後の構成チェックを追加します。
| チェック項目 | 確認方法 | 問題がある場合の見直し |
|---|---|---|
apphost.tsがあるか | プロジェクト直下を確認 | 旧テンプレート前提の手順が残っている可能性 |
app/があるか | FastAPIバックエンドの配置を確認 | フォルダ名を固定参照しているスクリプトを修正 |
frontend/があるか | React/Viteの配置を確認 | 旧Webプロジェクト名を前提にした説明を修正 |
aspire.config.jsonがあるか | AppHost言語とパッケージを確認 | TypeScript AppHostのSDK生成に関わるため必ず確認 |
| Redisを使うか | --use-redis-cacheの指定とAppHostの内容を確認 | 手順書ではtrue/falseを明示 |
.NET SDK前提の説明がないか | セットアップ手順を確認 | Pythonスターターだけなら不要な前提を削除。ただし.NETプロジェクト併用時は残す |
社内のレビュー観点も変更が必要です。たとえば、以前は「AppHost.csにAddUvicornAppがあるか」を見ていた場合、今後は「apphost.tsでbuilder.addUvicornAppが定義されているか」を確認する形になります。
--use-redis-cacheを有効にすべきケース
--use-redis-cacheは、テンプレート生成時にRedisキャッシュリソースを含めるためのオプションです。ドキュメントでは、trueまたはfalseを受け取り、指定しない場合は対話的に確認されると説明されています。(GitHub)
判断基準は次のとおりです。
| 選択 | 向いているケース | 注意点 |
|---|---|---|
--use-redis-cache true | キャッシュ利用、Redis連携、分散アプリの依存関係、起動順制御を含めて学びたい | Redisリソースも起動対象になるため、コンテナランタイムの状態を確認する |
--use-redis-cache false | FastAPIとReactの基本構成だけを素早く確認したい | 後からRedisを追加する場合はAppHostとパッケージ設定の変更が必要 |
| 未指定 | 対話的に作成する個人検証 | CIや教材ではプロンプトにより手順が止まる可能性がある |
Redisを有効にすると、テンプレート処理ではRedis用の条件ブロックが反映され、Aspire.Hosting.Redisも設定に追加されます。これは、単にPythonコードへライブラリを足すだけでなく、AppHost上のリソース、参照関係、起動順に影響する変更です。(GitHub)
そのため、「Redisを使う予定はまだないが、後で必要になるかもしれない」という理由だけで有効にするより、検証目的を決めて選ぶのが現実的です。最初はRedisなしで構成を把握し、キャッシュや分散トレースの確認が必要になった段階でRedisありのテンプレートを別途生成して差分を見る、という進め方も有効です。
既存プロジェクトをTypeScript AppHostへ移行するべきか
旧テンプレートで作った既存プロジェクトは、そのまま使えるとされています。したがって、既存のC# AppHostをすぐTypeScriptへ置き換える必要はありません。(GitHub)
移行を検討する価値があるのは、次のようなケースです。
| 移行を検討しやすいケース | 理由 |
|---|---|
| PythonとReactだけで構成されている | AppHostだけC#という状態を解消しやすい |
| チームの主言語がTypeScript | AppHostのレビューや保守をTypeScriptの文脈で進めやすい |
| 新規プロジェクトと構成をそろえたい | 13.3以降のスターター構成に合わせやすい |
| .NET SDK前提のオンボーディングを減らしたい | Python/React中心の環境構築を軽くできる |
一方、次のような場合は、移行を急がないほうが安全です。
| 移行を急がないほうがよいケース | 理由 |
|---|---|
| C# AppHostに独自の統合や複雑な設定がある | 単純なテンプレート差し替えでは再現できない可能性がある |
| .NETプロジェクトを多数含む | .NET SDKは引き続き必要で、環境簡素化のメリットが小さい |
| CI/CDがC# AppHost前提で安定している | 変更範囲が広がり、検証コストが増える |
| チームがTypeScript AppHostに慣れていない | AppHostのトラブルシュート方法も変わる |
移行する場合は、既存プロジェクトを直接書き換えるのではなく、新しいaspire-py-starterを別フォルダに生成し、apphost.ts、aspire.config.json、app/、frontend/の構造を比較するところから始めるのが安全です。特に、サービス名、環境変数、ヘルスチェック、Redis参照、静的ファイルの公開設定は差分が出やすい部分です。
開発環境で確認すべきこと
TypeScript AppHost化により、開発環境の確認ポイントも変わります。AppHostをTypeScriptで実行するため、Node.jsとAspire CLIの状態が重要になります。MicrosoftのTypeScript AppHost解説では、Node.js 20以降、OCI互換コンテナランタイム、Aspire CLIが前提として示されています。(Microsoft for Developers)
実務では、次の順に確認するとトラブルを切り分けやすくなります。
| 順番 | 確認項目 | コマンド例 |
| -: | —————— | —————————————————— |
| 1 | Aspire CLIが使えるか | aspire --version |
| 2 | Node.jsが使えるか | node --version |
| 3 | Pythonが使えるか | python --versionまたはpython3 --version |
| 4 | コンテナランタイムが起動しているか | Docker Desktop、Podmanなどの状態を確認 |
| 5 | テンプレートが生成できるか | aspire new aspire-py-starter --use-redis-cache false |
| 6 | AppHost SDKが生成されるか | .modules/やaspire restoreの結果を確認 |
| 7 | アプリが起動するか | aspire run |
TypeScript AppHostでは、aspire.config.jsonのpackagesにある統合パッケージをもとにSDKが生成されます。Microsoftのブログでも、aspire addがaspire.config.jsonのpackagesを更新し、aspire restoreがSDKを再生成する流れが説明されています。(Microsoft for Developers)
.modules/aspire.jsまわりでエラーが出る場合は、まずaspire restoreを実行し、aspire.config.jsonに必要なパッケージが入っているかを確認します。今回のPythonスターターでは、標準でJavaScriptとPythonのホスティング統合が含まれ、Redisを有効にした場合はRedis統合も関係します。(GitHub)
失敗しやすいポイント
旧コマンドをそのまま使ってしまう
もっとも起きやすい失敗は、過去の記事や社内資料を見てdotnet new aspire-py-starterを実行することです。今回の更新では、このコマンドは新規Pythonスターター作成の手段ではなくなったと明記されています。(GitHub)
古い資料を参照している読者向けには、次のように明確に書き換えましょう。
# 旧手順ではなく、今後はこちらを使う
aspire new aspire-py-starterAppHost.csを探してしまう
新テンプレートでは、中心になるファイルはAppHost.csではなくapphost.tsです。C# AppHostに慣れている人ほど、生成後にAppHost.csがないことを「生成ミス」と誤解しやすい点に注意してください。
レビュー時は、次のように観点を置き換えます。
| 旧観点 | 新観点 |
|---|---|
AppHost.csにサービス定義があるか | apphost.tsにサービス定義があるか |
C#のAddUvicornAppを確認する | TypeScriptのbuilder.addUvicornAppを確認する |
C#のWithReferenceを見る | TypeScriptの.withReference()を見る |
| C#プロジェクト構成を見る | apphost.ts、app/、frontend/、aspire.config.jsonを見る |
Redisオプションを曖昧にしたまま自動化する
--use-redis-cacheを指定しないと、対話的に選択する流れになります。ローカルで試すだけなら問題ありませんが、CI/CD、研修、記事内の再現手順では結果がぶれます。
自動化では、必ず次のどちらかを明示しましょう。
aspire new aspire-py-starter --use-redis-cache trueaspire new aspire-py-starter --use-redis-cache false.NET SDKが完全に不要になったと誤解する
Pythonスターターのスキャフォールドや実行に.NET SDKが不要になった点は大きな変更です。ただし、これは「すべてのAspire開発で.NET SDKが不要」という意味ではありません。C# AppHostを使う場合や、アプリケーションに.NETプロジェクトが含まれる場合は.NET SDKが必要です。(Microsoft for Developers)
社内手順では、次のように書き分けると誤解を防げます。
| シナリオ | .NET SDKの扱い |
|---|---|
新しいaspire-py-starterだけを試す | 原則として不要 |
| C# AppHostを使う | 必要 |
| ASP.NET Coreなど.NETプロジェクトを含める | 必要 |
| 旧テンプレート由来のC# AppHostを保守する | 必要になる可能性が高い |
チームで更新すべきドキュメントとスクリプト
今回のMicrosoft developer platformドキュメント更新を受けて、チーム内では次の場所を確認してください。
| 対象 | 修正内容 |
|---|---|
| README | dotnet new aspire-py-starterをaspire new aspire-py-starterへ変更 |
| オンボーディング資料 | .NET SDK前提の説明を、Pythonスターター用とC#/.NET用に分ける |
| ハンズオン教材 | 生成後の構成をapphost.ts、app/、frontend/で説明する |
| CI/CDスクリプト | Aspire CLIの利用、Redisオプションの明示、生成先フォルダの確認を追加 |
| コードレビュー観点 | C# AppHost前提からTypeScript AppHost前提へ更新 |
| トラブルシュート手順 | .modules/、aspire.config.json、aspire restoreの確認を追加 |
特に、教材や記事では「FastAPI + Reactスターター」と「ASP.NET Core系スターター」を混同しないことが重要です。aspire-starterやaspire-ts-cs-starterなど、ほかのテンプレートとは前提が異なるため、コマンド名と生成構成をセットで説明してください。
まず取るべき行動
今回の変更で最初にやるべきことは、既存プロジェクトの全面移行ではありません。まず、古い新規作成手順をなくすことです。
実務では、次の順で進めると安全です。
- リポジトリ、社内Wiki、CI設定から
dotnet new aspire-py-starterを検索する - 新規作成手順を
aspire new aspire-py-starterへ置き換える - Redisの有無を
--use-redis-cache true/falseで明示する - 生成後の構成を
apphost.ts、app/、frontend/、aspire.config.json前提に更新する - 既存のC# AppHostプロジェクトは、移行メリットがある場合だけ別途検証する
Microsoft developer platformの今回のドキュメント更新は、Python/ReactスターターをTypeScript AppHost中心の構成へそろえるための変更です。新規作成では新コマンドへ切り替え、既存プロジェクトでは無理な置き換えを避け、手順書・自動化・レビュー観点を先に直すのが、もっとも失敗の少ない対応です。
コメント