Add project reference support for polyglot apphost integrations

[davidfowl]

Description

Adds project reference support for polyglot AppHost integrations, enabling integration authors to test hosting integrations locally before publishing to a NuGet feed.

How it works

In .aspire/settings.json, a package entry whose value ends in .csproj is treated as a project reference instead of a NuGet version:

{
  "packages": {
    "Aspire.Hosting.Redis": "13.2.0",
    "MyIntegration": "../src/MyIntegration/MyIntegration.csproj"
  }
}

Two resolution paths in PrebuiltAppHostServer.PrepareAsync:

• NuGet-only (no project refs): Uses BundleNuGetService — no .NET SDK required
• Project refs present: Generates a synthetic .csproj with <PackageReference> and <ProjectReference> items, runs dotnet build with CopyLocalLockFileAssemblies=true to produce the full transitive DLL closure directly into the integration libs path. Requires .NET SDK (checked before build).

The synthetic project is isolated from parent MSBuild imports via Directory.Build.props, Directory.Build.targets, and Directory.Packages.props (CPM opt-out).

Key changes

• IntegrationReference record: represents both NuGet packages and project references
• AspireJsonConfiguration.GetIntegrationReferences(): replaces GetAllPackages(), detects .csproj paths
• IAppHostServerProject.PrepareAsync: signature changed to IEnumerable<IntegrationReference>
• PrebuiltAppHostServer: NuGet-only → BundleNuGetService; project refs → dotnet build synthetic project
• DotNetBasedAppHostServerProject: handles project refs as <ProjectReference> in generated csproj
• SdkGenerateCommand / SdkDumpCommand: use PrepareAsync through interface (no more casting)

Fixes #14760

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]

🚀 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 -- 14821

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Adds support for using local .csproj project references (in addition to NuGet package versions) for polyglot AppHost integrations via .aspire/settings.json, enabling local integration authoring/testing without publishing to a feed.

Changes:

• Introduces IntegrationReference and updates configuration parsing to treat values ending in .csproj as project references.
• Updates AppHost server preparation flow to accept integration references across CLI paths (scaffolding, SDK generate/dump, sessions).
• Adds unit and end-to-end tests covering synthetic project generation and TypeScript AppHost project-reference discovery/codegen.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/TestServices/TestAppHostServerSessionFactory.cs	Updates test session factory signature to use IntegrationReference.
tests/Aspire.Cli.Tests/Projects/PrebuiltAppHostServerTests.cs	Adds unit tests for synthetic integration restore .csproj generation.
tests/Aspire.Cli.Tests/Projects/GuestAppHostProjectTests.cs	Updates configuration tests to validate integration reference behavior (packages + project refs).
tests/Aspire.Cli.Tests/Projects/AppHostServerProjectTests.cs	Updates project scaffolding tests to pass IntegrationReference objects.
tests/Aspire.Cli.Tests/Configuration/IntegrationReferenceTests.cs	Adds unit tests for IntegrationReference and .csproj detection/path resolution.
tests/Aspire.Cli.EndToEnd.Tests/ProjectReferenceTests.cs	Adds E2E scenario validating TS AppHost can use a local .NET integration project reference.
src/Aspire.Cli/Scaffolding/ScaffoldingService.cs	Switches scaffolding preparation to use integration references.
src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs	Implements project-reference path: synthetic .csproj + dotnet build to materialize DLL closure; retains NuGet-only path.
src/Aspire.Cli/Projects/IAppHostServerSession.cs	Updates session factory API to accept integration references.
src/Aspire.Cli/Projects/IAppHostServerProject.cs	Updates server project API to accept integration references.
src/Aspire.Cli/Projects/GuestAppHostProject.cs	Updates integration gathering and codegen hash inputs to use integration references.
src/Aspire.Cli/Projects/DotNetBasedAppHostServerProject.cs	Updates generated server project to handle explicit project references and new integration list type.
src/Aspire.Cli/Projects/AppHostServerSession.cs	Wires session preparation to pass integration references.
src/Aspire.Cli/Projects/AppHostServerProject.cs	Updates prebuilt project construction to include SDK installer dependency.
src/Aspire.Cli/Configuration/IntegrationReference.cs	Adds record representing either a NuGet reference or a .csproj project reference.
src/Aspire.Cli/Configuration/AspireJsonConfiguration.cs	Replaces package enumeration with GetIntegrationReferences supporting .csproj detection and path resolution.
src/Aspire.Cli/Commands/Sdk/SdkGenerateCommand.cs	Uses IAppHostServerProject.PrepareAsync with integration references (removes concrete casting).
src/Aspire.Cli/Commands/Sdk/SdkDumpCommand.cs	Uses IAppHostServerProject.PrepareAsync with optional project-reference integration.

Comments suppressed due to low confidence (2)

src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs:214

• When copying nuget.config, appHostDirectory is computed as Path.GetDirectoryName(_appPath)!, which points to the parent of the AppHost directory. This can cause restores to miss the user’s nuget.config. Use _appPath as the app host directory.

        // Copy nuget.config from the user's apphost directory if present
        var appHostDirectory = Path.GetDirectoryName(_appPath)!;
        var userNugetConfig = Path.Combine(appHostDirectory, "nuget.config");
        if (File.Exists(userNugetConfig))
        {
            File.Copy(userNugetConfig, Path.Combine(restoreDir, "nuget.config"), overwrite: true);
        }

src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs:105

• ResolveChannelNameAsync is called to read the local .aspire/settings.json channel, but inside it currently uses Path.GetDirectoryName(_appPath). Since _appPath is the AppHost directory, this will look in the parent directory and can ignore the app’s configured channel. Update ResolveChannelNameAsync to load from _appPath directly.

            // Resolve the configured channel (local settings.json → global config fallback)
            var channelName = await ResolveChannelNameAsync(cancellationToken);

[github-actions]

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit b682686:

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
CreateAndRunTypeScriptStarterProject	▶️ 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	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	▶️ View Recording
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
TypeScriptAppHostWithProjectReferenceIntegration	❌ Upload failed

---

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

[davidfowl]

PR Testing Report

CLI Version: 13.2.0-pr.14821.g77549853 ✅ (matches head commit 77549853)

Scenarios Tested

Scenario	Status	Details
Basic CLI smoke test (aspire new)	✅ Passed	C# and TypeScript empty AppHosts created successfully
Project reference (.csproj in settings.json)	✅ Passed	Custom Aspire.Hosting.MyCustom integration built and linked via .csproj path. Dashboard launched.
NuGet package regression	✅ Passed	Aspire.Hosting.Redis via NuGet version — 8 ATS capabilities discovered, dashboard launched

Key Observations

• Project reference detection works correctly: PrebuiltAppHostServer logs Building integration project with 2 packages and 1 project references when a .csproj path is specified in settings.json.
• Graceful error without .NET SDK: When .NET SDK is not installed, the CLI reports a clear error: "Project references in settings.json require .NET SDK 10.0.100 or later."
• No regression for NuGet packages: Standard version-based package references continue to work as before.

Overall: ✅ Verified — Project reference support for polyglot AppHost integrations works as expected.

[JamesNK]

Nice PR — the IntegrationReference abstraction is clean and the two resolution paths in PrebuiltAppHostServer.PrepareAsync (NuGet-only vs project refs) are well separated. The SDK commands (SdkDumpCommand / SdkGenerateCommand) are nicely simplified by routing through the interface instead of type-checking. Tests are thorough.

Main concern is around the NuGet configuration handling in BuildIntegrationProjectAsync:

1. User nuget.config overwrite: If the user has a nuget.config and a channel is configured, the user's config is first copied then completely overwritten by the generated one. Custom sources are silently lost.
2. RestoreConfigFile is graph-wide: This MSBuild property applies to the entire restore graph, including the referenced project's transitive dependencies. If the referenced project needs sources that aren't in the generated config, restore will fail.
3. Unconditional nuget.org: Always adding nuget.org may be problematic in restricted environments.

These are related issues — recommend reconsidering the NuGet source strategy for the synthetic project. Options include: using RestoreAdditionalProjectSources instead of RestoreConfigFile, or merging channel sources into the user's existing config rather than overwriting it.

Smaller items: hardcoded net10.0 TFM (should share constant with DotNetBasedAppHostServerProject), method naming (GetAllPackagesAsync → GetAllIntegrationsAsync), and nullable safety around IntegrationReference.Version!.

[JamesNK]

@davidfowl Trying out AI code review 😄

[sebastienros]

Can "MyIntegration": "../src/MyIntegration/MyIntegration.csproj" be using a name that doesn't match the project name? I think there is an issue in this case, need to find it again

[sebastienros]

IntegrationReference.Name comes from the settings.json dictionary key and is used as the assembly name for Assembly.Load. If the key doesn't match the project's actual assembly name (e.g., "my-redis": "../MyRedis.csproj" => Assembly.Load("my-redis") fails), the integration silently won't be discovered.

Derive assembly name from Path.GetFileNameWithoutExtension(projectPath) for project references, or validate key matches csproj filename.