Add AddCSharpApp method to add C# file-based apps & projects

[DamianEdwards]

Description

Adds new hosting method AddCSharpApp that can be used to add:

• C# projects (path to .csproj)
• C# projects (path to project directory containing a single .csproj file)
• C# file-based app (path to .cs file)

e.g.

var builder = DistributedApplication.CreateBuilder(args);

// C# File-based app
// NOTE: This is in a sub-folder to ensure it doesn't pickup .razor files from the FrontEnd project
builder.AddCSharpApp("api", "./api/api.cs");

// Traditional C# project added via same API just specifying project directory
builder.AddCSharpApp("frontend", "./WebFrontEnd/");

// Traditional C# project added via same API but specifying the project path
builder.AddCSharpApp("backend", "./Backend/Backend.csproj");

builder.Build().Run();

Project building has been updated to track whether a project resource requires building or not. Project resources added via the generated IProjectMetadata types that come from <ProjectReference /> items in the AppHost .csproj will continue to have build suppressed, as will existing path-based project resources added via AddProject("../some/path.csproj"). Projects added using the newly added AddCSharpApp method will not have build suppressed anymore when running from the command-line. The existing restrictions around .csproj files being added to the app model that aren't in the solution the AppHost project is in are not addressed by these changes.

Also updates the Aspire.AppHost.Sdk and project templates to support only specifying the Aspire.AppHost.Sdk as the project SDK in which case the Microsoft.NET.Sdk is auto-imported and the Aspire.Hosting.AppHost package reference is implicitly referenced. Setting the project to use the Microsoft.NET.Sdk and importing the Aspire.AppHost.Sdk via an <Sdk /> item is still supported of course. Aspire CLI aspire update is updated to support this syntax too.

e.g.

<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

</Project>

Fixes #11498

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
• Does the change make any security assumptions or guarantees?
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • [Update article]: Aspire orchestration overview - AddCSharpApp docs-aspire#5315
      • [Update article]: Aspire orchestration overview - implicit AppHost SDK & package references docs-aspire#5316

[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 -- 11502

Or

• Run remotely in PowerShell:

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

[mitchdenny]

Are you going to try and land this for 9.5?

[DamianEdwards]

Are you going to try and land this for 9.5?

@mitchdenny I'm going to make it experimental, but, it does touch a few things as it basically re-uses all of the existing infra for projects, but teaches them about the new stuff for file-based apps in a few places. So, I think this is likely too risky to take in 9.5 unless others feel more confident than me 😄

[mitchdenny]

I think punting for 9.6 is right. We can then make file-based AddProject work at the same time.

[DamianEdwards]

@mitchdenny

We can then make file-based AddProject work at the same time.

Sorry, what do you mean by this?

[mitchdenny]

Add the moment AddProject(path) does not work because we don't build the .NET project (unless you are using VS obviously).

[DamianEdwards]

@mitchdenny hmmm, I thought it did because we end up calling dotnet run on the project, and that the issue with AddProject is adding a project outside of the solution the AppHost project is in when using Visual Studio because then the building is deferred to VS via the IDE protocol and it won't build projects outside of the open solution?

OK I just re-read the code and it seems we pass --no-build when we call dotnet run so yeah that's a problem. Even for file-based apps actually, it should be letting it build on run.

[Copilot]

Pull Request Overview

This PR adds a new AddCSharpApp extension method that enables adding C# projects and file-based apps to the Aspire application model. The implementation supports three input types: paths to .cs files (file-based apps), .csproj files, or directories containing a single .csproj. Additionally, the PR updates the Aspire.AppHost.Sdk to support simplified project file syntax where the SDK can be specified directly in the Project element's Sdk attribute, automatically importing Microsoft.NET.Sdk and the Aspire.Hosting.AppHost package reference.

Key changes:

• Introduced AddCSharpApp API with support for C# projects and file-based apps (.cs files)
• Updated project build behavior to track whether build suppression is needed via new SuppressBuild property on IProjectMetadata
• Modified AppHost SDK to auto-import Microsoft.NET.Sdk and implicitly reference Aspire.Hosting.AppHost package
• Enhanced CLI update logic to handle both old and new SDK reference formats

Reviewed Changes

Copilot reviewed 46 out of 47 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/Shared/RepoTesting/Aspire.RepoTesting.props	Updated condition to use case-insensitive check for 'AppHost' suffix
tests/Aspire.Templates.Tests/BuildAndRunTemplateTests.cs	Added tests for CPM and explicit SDK reference scenarios
tests/Aspire.Hosting.Tests/Snapshots/MSBuildTests.ValidateMetadataSources.verified.txt	Updated snapshot with new SuppressBuild property and corrected comment
tests/Aspire.Dashboard.Tests/Model/ResourceIconHelpersTests.cs	Added test cases for .cs file icon resolution
tests/Aspire.Cli.Tests/Projects/ProjectUpdaterTests.cs	Added tests for SDK attribute and element format updates
src/Shared/LaunchProfiles/LaunchProfileExtensions.cs	Added support for .run.json files for file-based apps
src/Aspire.ProjectTemplates/templates/aspire-starter/13.0/Aspire-StarterApplication.1.AppHost/Aspire-StarterApplication.1.AppHost.csproj	Updated to use new SDK syntax and removed explicit AppHost package reference
src/Aspire.ProjectTemplates/templates/aspire-empty/13.0/AspireApplication.1.AppHost/AspireApplication.1.AppHost.csproj	Updated to use new SDK syntax and removed explicit AppHost package reference
src/Aspire.ProjectTemplates/templates/aspire-apphost/13.0/Aspire.AppHost1.csproj	Updated to use new SDK syntax and removed explicit AppHost package reference
src/Aspire.Hosting/Utils/DotnetSdkUtils.cs	New utility class for detecting .NET SDK version
src/Aspire.Hosting/ProjectResourceOptions.cs	Added FileBasedAppResourceOptions class (placeholder)
src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs	Added AddCSharpApp methods and updated configuration loading
src/Aspire.Hosting/IProjectMetadata.cs	Added SuppressBuild and IsFileBasedApp properties, enhanced ProjectMetadata to resolve directory paths
src/Aspire.Hosting/Dcp/DcpExecutor.cs	Updated to handle file-based apps and conditional build suppression
src/Aspire.Hosting/ApplicationModel/CSharpAppResource.cs	New resource type for C# apps
src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets	Added SuppressBuild property to generated metadata, corrected comment
src/Aspire.Dashboard/Model/ResourceIconHelpers.cs	Added .cs extension to C# icon mapping
src/Aspire.Cli/Projects/ProjectUpdater.cs	Enhanced to handle both SDK attribute and element formats
src/Aspire.AppHost.Sdk/SDK/Sdk.in.targets	Simplified to add implicit AppHost package reference for all projects
src/Aspire.AppHost.Sdk/SDK/Sdk.in.props	Updated to auto-import Microsoft.NET.Sdk, commented out some file-based app properties
playground/FileBasedApps/*	New playground project demonstrating file-based app functionality
playground/Directory.Build.targets	Fixed relative path to Analyzers project
Directory.Packages.props	Reorganized package versions with framework-specific conditions

[davidfowl]

Verified.

@mitchdenny We'll want to update aspire update to support the new SDK style project that auto includes the .NET SDK and auto adds the package ref.

cc @DamianEdwards

[DamianEdwards]

@davidfowl this PR already does that, or am I missing something?

[davidfowl]

OHHh I didnt see that part.