Refactor aspire new layering for polyglot templates by davidfowl · Pull Request #14677 · dotnet/aspire

davidfowl · 2026-02-25T08:43:50Z

Description

This PR reworks aspire new into a template-first model with two execution paths and consistent language-aware selection behavior.

Template architecture

DotNet-based templates (TemplateRuntime.DotNet): executed through dotnet new flows.
CLI-based templates (TemplateRuntime.Cli): CLI templates are embedded resources copied to disk (with token replacement) by CLI callbacks.
NewCommand now resolves template + language intent first, then dispatches to the template runtime, instead of hardcoding behavior in command branches.

Template discovery and filtering

Template discovery APIs were made async so each factory can self-filter based on runtime availability.
DotNetTemplateFactory now owns .NET SDK availability filtering; if SDK is unavailable, .NET templates are not offered.
new and init surfaces are separated cleanly in factory output (e.g., singlefile remains on init surface).

Language capability model

Templates can now declare supported AppHost languages in metadata (SelectableAppHostLanguages).
A template can also declare fixed language support (SupportsLanguage) for filtering when --language is provided.
aspire-empty declares selectable AppHost languages (C# and TypeScript), while language-specific templates stay fixed.

Prompting and selection flow

Template selection happens first (explicit template arg or template picker).
Language prompting happens after template selection, and only for templates that declare selectable languages.
Language resolution order is:
1. explicit --language
2. saved local config (language)
3. interactive language prompt
The chosen language is persisted to local config.
--language on new is recursive so both forms work with template commands.

CLI template implementation updates

Introduced a mechanical embedded-resource tree copy helper for CLI templates.
Empty AppHost C# generation is now CLI-driven via embedded empty-apphost resources.
TypeScript starter generation was switched to embedded-tree copy with token replacement.
Added debug logging in CLI template generation paths to diagnose resource resolution/copy issues.

Embedded resource reliability

Added <WithCulture>false</WithCulture> for embedded template resources to prevent *.run.json from being treated as culture resources.
Verified expected embedded names are available (including empty-apphost.apphost.run.json and ts-starter.apphost.run.json).

Validation

dotnet test tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
Targeted regressions for NewCommand/DotNetTemplateFactory and language/subcommand parsing paths.

Fixes #14676

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

github-actions · 2026-02-25T08:43:59Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 14677

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 14677"

github-actions · 2026-02-25T09:41:20Z

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit 5beeac5:

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AgentInitCommand_WithMalformedMcpJson_ShowsErrorAndExitsNonZero	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndPublishToKubernetes	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateEmptyAppHostProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateStartWaitAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DescribeCommandResolvesReplicaNames	▶️ View Recording
DescribeCommandShowsRunningResources	▶️ View Recording
DetachFormatJsonProducesValidJson	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	❌ Upload failed
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	❌ Upload failed
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording

_{📹 Recordings uploaded automatically from CI run #22523674347}

Copilot

Pull request overview

This PR refactors the aspire new command to separate .NET and polyglot template creation through cleaner abstractions. Instead of branching at the command level, templates now declare their runtime model (DotNet/Polyglot) and route through appropriate factory implementations.

Changes:

Introduced TemplateRuntime enum and ITemplateVersionPrompter interface to separate template-specific concerns from command-level logic
Added PolyglotTemplateFactory with support for generic polyglot AppHost creation and a TypeScript starter template (Node.js + React)
Refactored NewCommand to resolve language once and route to the appropriate template runtime
Moved .NET SDK installation gating from NewCommand into DotNetTemplateFactory for better separation of concerns

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/Aspire.Cli/Templating/TemplateRuntime.cs	New enum defining DotNet and Polyglot runtime models
src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs	New factory for polyglot templates with embedded TypeScript starter template
src/Aspire.Cli/Templating/ITemplate.cs	Added Runtime and IncludeAsSubcommand properties for template routing
src/Aspire.Cli/Templating/ITemplateProvider.cs	Added GetInitTemplates() method for init-specific templates
src/Aspire.Cli/Templating/TemplateProvider.cs	Implemented GetInitTemplates() to delegate to factories
src/Aspire.Cli/Templating/TemplateInputs.cs	Added Language property for language selection
src/Aspire.Cli/Templating/CallbackTemplate.cs	Updated constructor to accept runtime and includeAsSubcommand parameters
src/Aspire.Cli/Templating/DotNetTemplateFactory.cs	Moved SDK installation check into template application; uses ITemplateVersionPrompter
src/Aspire.Cli/Commands/NewCommand.cs	Refactored to resolve language first, then route to appropriate template; split ITemplateVersionPrompter from INewCommandPrompter
src/Aspire.Cli/Commands/InitCommand.cs	Updated to use ITemplateVersionPrompter and ITemplateProvider
src/Aspire.Cli/Program.cs	Registered PolyglotTemplateFactory and ITemplateVersionPrompter in DI container
src/Aspire.Cli/Aspire.Cli.csproj	Added embedded resources for TypeScript starter template files
src/Aspire.Cli/Templating/Templates/ts-starter/*	TypeScript starter template files (apphost, package.json, tsconfig, API, settings)
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Updated test service registration for new interfaces
tests/Aspire.Cli.Tests/Templating/DotNetTemplateFactoryTests.cs	Updated tests for new DotNetTemplateFactory constructor parameters
tests/Aspire.Cli.Tests/Commands/NewCommandTests.cs	Added tests for polyglot template selection and language routing
localhive.ps1	Improved CLI installation robustness with backup/restore logic and channel configuration

src/Aspire.Cli/Templating/TemplateRuntime.cs

src/Aspire.Cli/Commands/NewCommand.cs

src/Aspire.Cli/Templating/ITemplate.cs

src/Aspire.Cli/Templating/ITemplateProvider.cs

src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs

Copilot · 2026-02-27T05:46:47Z

src/Aspire.Cli/Commands/NewCommand.cs

+        }
+
        // NOTE: I am using Single(...) here because if we get to this point and we are not running the 'aspire new' without a template
        //       specified then we should have errored out with the help text. If we get there then someting is really wrong and we should


Typo in comment: "someting" should be "something".

Suggested change

// specified then we should have errored out with the help text. If we get there then someting is really wrong and we should

// specified then we should have errored out with the help text. If we get there then something is really wrong and we should

src/Aspire.Cli/Commands/NewCommand.cs

src/Aspire.Cli/Templating/CliTemplateFactory.cs

src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs

mitchdenny

Overall this is a clean refactoring that properly separates .NET and polyglot template concerns behind the ITemplate/ITemplateFactory/ITemplateProvider abstractions. A few issues noted inline.

src/Aspire.Cli/Commands/NewCommand.cs

mitchdenny · 2026-02-27T06:03:29Z

src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs

+        var outputTask = process.StandardOutput.ReadToEndAsync(cancellationToken);
+        var errorTask = process.StandardError.ReadToEndAsync(cancellationToken);
+
+        await process.WaitForExitAsync(cancellationToken).ConfigureAwait(false);


If the cancellation token fires during WaitForExitAsync, an OperationCanceledException propagates but the spawned process (npm/vite) continues running as an orphan. The using disposal on Process does not terminate the OS process.

Consider wrapping this in a try/catch to terminate the process tree on cancellation via process.TERMINATE(entireProcessTree: true).

src/Aspire.Cli/Templating/CliTemplateFactory.cs

JamesNK · 2026-02-27T05:53:07Z

src/Aspire.Cli/Commands/NewCommand.cs

+
+    private async Task<ITemplate> GetProjectTemplateAsync(ParseResult parseResult, string selectedLanguageId, CancellationToken cancellationToken)
+    {
+        if (!selectedLanguageId.Equals(KnownLanguageId.CSharp, StringComparison.OrdinalIgnoreCase))


Should the language option type be an enum? Commandline help would then automatically include available values to the user.

src/Aspire.Cli/Commands/NewCommand.cs

src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs

src/Aspire.Cli/Templating/CliTemplateFactory.cs

src/Aspire.Cli/Templating/PolyglotTemplateFactory.cs

JamesNK · 2026-02-27T11:01:23Z

src/Aspire.Cli/Commands/NewCommand.cs

+        Options.Add(_languageOption);

-        _templates = templateProvider.GetTemplates();
+        _templates = templateProvider.GetTemplatesAsync(CancellationToken.None).GetAwaiter().GetResult().ToArray();


Blocking inside the constructor delays all of CLI startup.

This one is hard to fix.

JamesNK · 2026-02-27T22:02:38Z

src/Aspire.Cli/Commands/NewCommand.cs

+        return (true, selectedLanguageId);
+    }
+
+    private Task<ITemplate[]> GetTemplatesForPromptAsync(ParseResult parseResult, CancellationToken cancellationToken)


Doesn't need to be async

JamesNK · 2026-02-28T00:27:05Z

src/Aspire.Cli/Commands/NewCommand.cs

+    private static bool ShouldResolveCliTemplateVersion(ITemplate template)
+    {
+        return template.Runtime is TemplateRuntime.Cli &&
+               !template.Name.Equals("aspire-empty", StringComparison.OrdinalIgnoreCase);


"aspire-empty" should be a const somewhere. Also replace other places in CLI that hardcodes the string

- Add CliTemplateFactory with TypeScript starter and Empty AppHost templates - Add embedded template resources with token replacement (ports, hostName, project name) - Refactor NewCommand to route to .NET or CLI template runtime - Restore templates as subcommands for proper option scoping - Move .NET SDK gating into DotNetTemplateFactory - Split template version prompting into ITemplateVersionPrompter - Add localhive.ps1 improvements (backup/rename, locked DLLs, channel config) - Use workspace directory name as default project name Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mitchdenny

I think this is a good change overall. Obviously the tests need to pass :) And agree with some of the nits that James has mentioned but assuming those get addressed good to merge. The Git template spike I am doing will be made better by this PR.

JamesNK · 2026-02-28T04:23:17Z

src/Aspire.Cli/Commands/NewCommand.cs

-            };
-            Options.Add(_languageOption);
-        }
+            Description = "The programming language for the AppHost.",


UI text in resource files

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Make polyglot behavior default-on in CLI commands and tests, and remove obsolete config/schema/workflow/docs references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update empty apphost and secret E2E flows to account for template language prompt interactions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Prevent CliTemplateFactory from prompting for localhost TLD when interactive input is unavailable, while preserving explicit option behavior and interactive prompts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Introduce TemplateNuGetConfigService and use it from DotNetTemplateFactory and CliTemplateFactory (empty C# apphost path). Also resolve CLI template version for all CLI templates, including aspire-empty, and update tests to cover package version resolution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Embed a full React frontend in the ts-starter template, update API payload/health endpoint, and remove runtime vite scaffolding. Also make template resource extraction binary-safe by stream-copying binary assets so files like Aspire.png are not corrupted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove ASPIRE_SHOW_DASHBOARD_RESOURCES from ts-starter apphost.run.json profiles to match current template defaults. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

davidfowl force-pushed the davidfowl/fix-polyglot-new branch from 93dc534 to 24df40f Compare February 25, 2026 08:45

github-actions bot mentioned this pull request Feb 25, 2026

[13.2-burndown] Daily Burndown Report - February 25, 2026 #14682

Closed

davidfowl force-pushed the davidfowl/fix-polyglot-new branch 2 times, most recently from 102143d to 696aca4 Compare February 27, 2026 02:52

davidfowl marked this pull request as ready for review February 27, 2026 05:39

Copilot AI review requested due to automatic review settings February 27, 2026 05:39

Copilot started reviewing on behalf of davidfowl February 27, 2026 05:40 View session

Copilot AI reviewed Feb 27, 2026

View reviewed changes

mitchdenny reviewed Feb 27, 2026

View reviewed changes

JamesNK reviewed Feb 27, 2026

View reviewed changes

This was referenced Feb 27, 2026

[pull requests] Review required #13834

Open

[13.2-burndown] Daily Burndown Report - February 27, 2026 #14765

Closed

davidfowl force-pushed the davidfowl/fix-polyglot-new branch from f9f31b9 to f11c271 Compare February 27, 2026 18:14

JamesNK reviewed Feb 28, 2026

View reviewed changes

davidfowl force-pushed the davidfowl/fix-polyglot-new branch from 360f0b1 to 47828b2 Compare February 28, 2026 00:37

mitchdenny approved these changes Feb 28, 2026

View reviewed changes

JamesNK reviewed Feb 28, 2026

View reviewed changes

davidfowl and others added 4 commits February 27, 2026 21:58

Address new command feedback

97a7777

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove polyglotSupportEnabled feature flag

393031e

Make polyglot behavior default-on in CLI commands and tests, and remove obsolete config/schema/workflow/docs references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adjust CLI E2E language-selection steps

71d500d

Update empty apphost and secret E2E flows to account for template language prompt interactions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix non-interactive localhost TLD prompting

832fb32

Prevent CliTemplateFactory from prompting for localhost TLD when interactive input is unavailable, while preserving explicit option behavior and interactive prompts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions bot mentioned this pull request Feb 28, 2026

[13.2-burndown] Daily Burndown Report - February 28, 2026 #14801

Open

davidfowl and others added 3 commits February 28, 2026 06:48

Adjust ts-starter run environment

5beeac5

Remove ASPIRE_SHOW_DASHBOARD_RESOURCES from ts-starter apphost.run.json profiles to match current template defaults. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

davidfowl mentioned this pull request Feb 28, 2026

Review the new ts-starter template (Express/React) #14804

Open

davidfowl merged commit e1de0eb into release/13.2 Feb 28, 2026
345 checks passed

davidfowl deleted the davidfowl/fix-polyglot-new branch February 28, 2026 16:03

dotnet-policy-service bot added this to the 13.2 milestone Feb 28, 2026

This was referenced Feb 28, 2026

Remove the polyglot apphost feature flag #14770

Closed

When polyglotSupportEnabled, show a language selection when running aspire new #14676

Closed

	// specified then we should have errored out with the help text. If we get there then someting is really wrong and we should
	// specified then we should have errored out with the help text. If we get there then something is really wrong and we should

Conversation

davidfowl commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Template architecture

Template discovery and filtering

Language capability model

Prompting and selection flow

CLI template implementation updates

Embedded resource reliability

Validation

Checklist

Uh oh!

github-actions bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎬 CLI E2E Test Recordings

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mitchdenny left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mitchdenny Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JamesNK Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

davidfowl Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

mitchdenny left a comment

Choose a reason for hiding this comment

Uh oh!

JamesNK Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

davidfowl commented Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 25, 2026 •

edited

Loading