From f47d600e21277ee4384b722a8c9f4060e5694aeb Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Fri, 9 Oct 2026 00:36:44 +0000 Subject: [PATCH] Document AddCSharpApp obsoletion in favor of AddDotnetProject Documents the breaking change from microsoft/aspire#20825: AddCSharpApp (and the polyglot addCSharpApp export) is now marked [Obsolete] instead of [Experimental("ASPIRECSHARPAPPS001")], producing CS0618 instead of the experimental diagnostic. Adds migration guidance pointing consumers to AddDotnetProject from the Aspire.Hosting.Dotnet package. - Added a breaking-change entry to What's new in Aspire 17.0 - Added a Migrating to AddDotnetProject section to the C# file-based apps integration page, with updated Aside/limitations text - Updated the ASPIRECSHARPAPPS001 diagnostic page and the diagnostics overview table to note the obsoletion - Cross-referenced the migration guidance from the .NET host page, project-resources comparison, and the existing-app onboarding guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/diagnostics/aspirecsharpapps001.mdx | 11 +++ .../src/content/docs/diagnostics/overview.mdx | 2 +- .../get-started/add-aspire-existing-app.mdx | 4 +- .../dotnet/csharp-file-based-apps.mdx | 74 +++++++++++-------- .../integrations/dotnet/project-resources.mdx | 4 + .../frameworks/dotnet/dotnet-host.mdx | 2 + .../src/content/docs/whats-new/aspire-17.mdx | 20 +++++ 7 files changed, 82 insertions(+), 35 deletions(-) diff --git a/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx b/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx index 2289f091c..b72f9900d 100644 --- a/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx @@ -13,10 +13,16 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> +:::note[Obsolete in Aspire 17.0] +Starting with Aspire 17.0, `AddCSharpApp` (and the polyglot `addCSharpApp` export) is marked `[Obsolete]` instead of `[Experimental("ASPIRECSHARPAPPS001")]`. Existing calls now produce the `CS0618` compiler warning instead of this error. Add the `Aspire.Hosting.Dotnet` integration and use `AddDotnetProject` / `addDotnetProject` instead. See [Migrating to AddDotnetProject](/integrations/dotnet/csharp-file-based-apps/#migrating-to-adddotnetproject). +::: + > `AddCSharpApp` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. Aspire provides a way to add C# app resources to the Aspire AppHost with the `AddCSharpApp` extension. This allows you to reference C# file-based app files (.cs), project files (.csproj), or project directories (directories containing a .csproj file) directly without needing a `ProjectReference` from the AppHost project to the C# application. Since the shape of this API is expected to change in the future, it's experimental. +This diagnostic only applies to Aspire versions before 17.0. After upgrading to 17.0 or later, `AddCSharpApp` no longer produces `ASPIRECSHARPAPPS001`; instead it produces the `CS0618` obsolete-member warning. + ## Example The following code generates `ASPIRECSHARPAPPS001`: @@ -54,3 +60,8 @@ Suppress the error with either of the following methods: ``` - Suppress in code with the `#pragma warning disable ASPIRECSHARPAPPS001` directive. + +## See also + +- [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/) — including [migration guidance to `AddDotnetProject`](/integrations/dotnet/csharp-file-based-apps/#migrating-to-adddotnetproject) for Aspire 17.0 and later +- [Set up .NET / C# apps in the AppHost](/integrations/frameworks/dotnet/dotnet-host/) diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx index 9e0b41b8e..5f09711a8 100644 --- a/src/frontend/src/content/docs/diagnostics/overview.mdx +++ b/src/frontend/src/content/docs/diagnostics/overview.mdx @@ -46,7 +46,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors | [ASPIRECONTAINERRUNTIME001](/diagnostics/aspirecontainerruntime001/) | (Experimental) Warning | Type is for evaluation purposes only and is subject to change or removal in future updates. | | [ASPIRECONTAINERSHELLEXECUTION001](/diagnostics/aspirecontainershellexecution001/) | (Experimental) Warning | Container shell execution property is for evaluation purposes only and is subject to change or removal in future updates. | | [ASPIRECOSMOSDB001](/diagnostics/aspirecosmosdb001/) | (Experimental) Error | `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. | -| [ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/) | (Experimental) Error | `AddCSharpApp` is for evaluation purposes only and is subject to change or removal in future updates. | +| [ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/) | (Experimental) Error | `AddCSharpApp` is for evaluation purposes only and is subject to change or removal in future updates. Replaced by the `CS0618` obsolete warning starting in Aspire 17.0. | | [ASPIREDOCKERFILEBUILDER001](/diagnostics/aspiredockerfilebuilder001/) | (Experimental) Warning | Dockerfile builder types and members are for evaluation purposes only and are subject to change or removal in future updates. | | [ASPIREDOTNETPROJECT001](/diagnostics/aspiredotnetproject001/) | (Experimental) Warning | Removed from the prerelease `Aspire.Hosting.Dotnet` and `Aspire.Hosting.Blazor` packages in Aspire 13.6. Their APIs remain unstable and may change. | | [ASPIREDOTNETTOOL001](/diagnostics/aspiredotnettool001/) | (Experimental) Warning | .NET tool resource types and members are for evaluation purposes only and are subject to change or removal in future updates. | diff --git a/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx b/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx index b7820b0fd..c92dcb3a2 100644 --- a/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx +++ b/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx @@ -178,8 +178,8 @@ After setup, a typical repo layout looks like this: - MyApp.Worker.csproj -:::caution[AddCSharpApp is experimental] -`AddCSharpApp` is currently experimental. If you want details on limitations or diagnostic suppression, see [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/). +:::caution[AddCSharpApp is obsolete] +`AddCSharpApp` is obsolete starting in Aspire 17.0. For new AppHosts, prefer [`AddDotnetProject`](/integrations/frameworks/dotnet/dotnet-host/) from the `Aspire.Hosting.Dotnet` integration. If you want details on limitations, diagnostic suppression, or migrating from `AddCSharpApp`, see [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/). ::: #### Project-based AppHost (with a .sln) diff --git a/src/frontend/src/content/docs/integrations/dotnet/csharp-file-based-apps.mdx b/src/frontend/src/content/docs/integrations/dotnet/csharp-file-based-apps.mdx index 92daaef1d..f7885dcc4 100644 --- a/src/frontend/src/content/docs/integrations/dotnet/csharp-file-based-apps.mdx +++ b/src/frontend/src/content/docs/integrations/dotnet/csharp-file-based-apps.mdx @@ -9,10 +9,11 @@ import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; import csharpIcon from '@assets/icons/csharp.svg'; -