aspire-repo-bot · Oct 9, 2026
@@ -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/) &mdash; 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/)
@@ -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.                                                                  |

@@ -178,8 +178,8 @@ After setup, a typical repo layout looks like this:
             - MyApp.Worker.csproj
 </FileTree>
 
-:::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)

@@ -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';
 
-<Aside type="danger" title="Experimental">
-  The `AddCSharpApp` API is experimental and may change or be removed in future
-  releases. You must suppress the
-  [ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/) diagnostic to use it.
+<Aside type="danger" title="Obsolete">
+  `AddCSharpApp` (and the polyglot `addCSharpApp` export) is obsolete starting
+  in Aspire 17.0. Add the [`Aspire.Hosting.Dotnet`](/integrations/frameworks/dotnet/dotnet-host/)
+  integration and use `AddDotnetProject` / `addDotnetProject` instead. See
+  [Migrating to AddDotnetProject](#migrating-to-adddotnetproject) below.
 </Aside>
 
 <Image
@@ -47,7 +48,7 @@ Call `AddCSharpApp` with a resource name and the relative path to a `.cs` file.
 <TabItem id='csharp' label='C#'>
 
 ```csharp title="AppHost.cs"
-#pragma warning disable ASPIRECSHARPAPPS001
+#pragma warning disable CS0618
 
 var builder = DistributedApplication.CreateBuilder(args);
 
@@ -78,7 +79,7 @@ You can also point to a `.csproj` file or a directory that contains one:
 <TabItem id='csharp' label='C#'>
 
 ```csharp title="AppHost.cs"
-#pragma warning disable ASPIRECSHARPAPPS001
+#pragma warning disable CS0618
 
 var builder = DistributedApplication.CreateBuilder(args);
 
@@ -127,7 +128,7 @@ File-based apps integrate fully with Aspire's resource model. You can reference
 <TabItem id='csharp' label='C#'>
 
 ```csharp title="AppHost.cs"
-#pragma warning disable ASPIRECSHARPAPPS001
+#pragma warning disable CS0618
 
 var builder = DistributedApplication.CreateBuilder(args);
 
@@ -175,7 +176,7 @@ The C# `AddCSharpApp` method accepts an optional `Action<ProjectResourceOptions>
 <TabItem id='csharp' label='C#'>
 
 ```csharp title="AppHost.cs"
-#pragma warning disable ASPIRECSHARPAPPS001
+#pragma warning disable CS0618
 
 var builder = DistributedApplication.CreateBuilder(args);
 
@@ -215,7 +216,7 @@ You can also write the AppHost itself as a file-based C# app using the `#:sdk` d
 #:sdk Aspire.AppHost.Sdk@%ASPIRE_VERSION%
 #:package Aspire.Hosting.Redis@%ASPIRE_VERSION%
 
-#pragma warning disable ASPIRECSHARPAPPS001
+#pragma warning disable CS0618
 
 var builder = DistributedApplication.CreateBuilder(args);
 
@@ -249,52 +250,61 @@ The Visual Studio Code extension explicitly advertises support for launching fil
 
 ## Limitations
 
-Since this feature is experimental, be aware of the following limitations:
+Be aware of the following limitations:
 
-- **Experimental status** &mdash; the API is marked with `[Experimental("ASPIRECSHARPAPPS001")]` and may change in future releases.
+- **Obsolete** &mdash; the API is marked `[Obsolete]` starting in Aspire 17.0. See [Migrating to AddDotnetProject](#migrating-to-adddotnetproject).
 - **Single-file only** &mdash; file-based apps are limited to a single `.cs` file per resource.
 - **.NET 10 SDK required** &mdash; file-based app execution requires the .NET 10 SDK or later.
 - **No deployment support** &mdash; file-based apps are designed for local development scenarios.
 
-## Suppress the diagnostic
+## Migrating to AddDotnetProject
 
-To use `AddCSharpApp` in a C# AppHost, suppress the `ASPIRECSHARPAPPS001` diagnostic using one of these methods:
+Starting in Aspire 17.0, `AddCSharpApp` and the polyglot `addCSharpApp` export are obsolete. Existing C# calls now produce the `CS0618` compiler warning instead of the `ASPIRECSHARPAPPS001` experimental error, and the TypeScript API surface emits `@deprecated` instead of `@experimental`. Signatures, defaults, validation, callbacks, path handling, and launch/publish behavior are unchanged for existing `AddCSharpApp` calls &mdash; only the diagnostic metadata changed.
 
-**In code** with a pragma directive:
+Add the [📦 Aspire.Hosting.Dotnet](https://www.nuget.org/packages/Aspire.Hosting.Dotnet) integration and replace `AddCSharpApp` / `addCSharpApp` calls with `AddDotnetProject` / `addDotnetProject`:
 
-```csharp title="AppHost.cs"
-#pragma warning disable ASPIRECSHARPAPPS001
-builder.AddCSharpApp("worker", "../worker/Program.cs");
-#pragma warning restore ASPIRECSHARPAPPS001
+```bash title="Terminal"
+aspire add Aspire.Hosting.Dotnet
 ```
 
-**In your project file** with `NoWarn`:
+<Tabs syncKey='aspire-lang'>
+<TabItem id='csharp' label='C#'>
 
-```xml title="C# project file"
-<PropertyGroup>
-    <NoWarn>$(NoWarn);ASPIRECSHARPAPPS001</NoWarn>
-</PropertyGroup>
+```csharp title="AppHost.cs"
+builder.AddDotnetProject("worker", "../worker/Program.cs");
 ```
 
-**In an _.editorconfig_ file**:
+</TabItem>
+<TabItem id='typescript' label='TypeScript'>
 
-```ini title=".editorconfig"
-[*.{cs,vb}]
-dotnet_diagnostic.ASPIRECSHARPAPPS001.severity = none
+```typescript title="apphost.mts"
+await builder.addDotnetProject("worker", "../worker/Program.cs");
 ```
 
-:::note
-`ASPIRECSHARPAPPS001` is a C# compiler diagnostic. TypeScript AppHosts call `addCSharpApp` without any diagnostic suppression needed.
-:::
+</TabItem>
+</Tabs>
+
+`AddDotnetProject` accepts the same kinds of paths &mdash; a `.cs` file, a `.csproj` file, or a directory containing a single `.csproj` &mdash; but returns a `DotnetProjectResource` instead of a `ProjectResource` / `CSharpAppResource`. Explicitly typed resource builders and project-specific customizations might need updating. Unlike `AddDotnetProject`, `AddCSharpApp` still supports automatic publishing, so keep using `AddCSharpApp` if you rely on `aspire publish` / `aspire deploy` for the resource until `DotnetProjectResource` gains publishing support.
+
+If you keep using `AddCSharpApp` and treat warnings as errors, suppress `CS0618` for the retained calls:
+
+```csharp title="AppHost.cs"
+#pragma warning disable CS0618
+builder.AddCSharpApp("worker", "../worker/Program.cs");
+#pragma warning restore CS0618
+```
 
 <LearnMore>
-  Learn more about [ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/).
+  See [Set up .NET / C# apps in the AppHost](/integrations/frameworks/dotnet/dotnet-host/)
+  for the full `AddDotnetProject` reference, and
+  [What's new in Aspire 17.0](/whats-new/aspire-17/#breaking-changes) for the
+  obsoletion announcement.
 </LearnMore>
 
 ## See also
 
 - [What is the AppHost?](/get-started/app-host/)
-- [Compiler Error ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/)
+- [Set up .NET / C# apps in the AppHost](/integrations/frameworks/dotnet/dotnet-host/)
 - [Project resources](/integrations/dotnet/project-resources/)
 - [Aspire SDK](/get-started/aspire-sdk/)
 - [Executable resources](/app-host/executable-resources/)

@@ -550,6 +550,10 @@ await builder.build().run();
 
 ## AddProject vs. AddCSharpApp
 
+:::note
+`AddCSharpApp` is obsolete starting in Aspire 17.0. Use [`AddDotnetProject`](/integrations/frameworks/dotnet/dotnet-host/) from `Aspire.Hosting.Dotnet` for new path-based project or file-based app resources instead. See [Migrating to AddDotnetProject](/integrations/dotnet/csharp-file-based-apps/#migrating-to-adddotnetproject).
+:::
+
 In a **C# AppHost**, use `AddProject<T>` when you have a standard `.csproj`, can add a `ProjectReference` from the AppHost, and want generated `Projects.*` types plus launch-profile integration. Use `AddCSharpApp` when you want to run a single `.cs` file, or when you want to point at a project path directly without adding a `ProjectReference` from the AppHost.
 
 In a **TypeScript AppHost**, `addProject(name, path)` always takes a path, so the distinction between `AddProject<T>` and `AddCSharpApp` doesn't apply in the same way.

@@ -27,6 +27,8 @@ If you're new to the Dotnet integration, start with the [Get started with the .N
 `Aspire.Hosting.Dotnet` is a prerelease package. Its APIs remain unstable and may change in future releases.
 
 Starting with Aspire 13.6, `AddDotnetProject`, `DotnetProjectResource`, and the related `WithBuildEnvironment` overloads no longer require suppressing [`ASPIREDOTNETPROJECT001`](/diagnostics/aspiredotnetproject001/). You can remove existing suppressions for these APIs after upgrading.
+
+Starting with Aspire 17.0, `AddCSharpApp` / `addCSharpApp` is obsolete. If you're migrating existing `AddCSharpApp` calls to this integration, see [Migrating to AddDotnetProject](/integrations/dotnet/csharp-file-based-apps/#migrating-to-adddotnetproject).
 :::
 
 If your C# AppHost needs to reference the resource type directly — for example, to declare a strongly typed variable or a method parameter — import it from the `Aspire.Hosting.Dotnet` namespace, matching the pattern used by the Go, Python, and JavaScript hosting integrations:

@@ -76,3 +76,23 @@ The service registration calls, `AddRabbitMQClient` and `AddMongoDBClient`, rema
   current client setup guidance. For the removal details, see
   [microsoft/aspire#20608](https://github.com/microsoft/aspire/pull/20608).
 </LearnMore>
+
+#### `AddCSharpApp` is obsolete
+
+`AddCSharpApp` (and the polyglot `addCSharpApp` export) has always been experimental. Starting in Aspire 17.0, the public overloads and the internal dispatcher are marked `[Obsolete]` instead of `[Experimental("ASPIRECSHARPAPPS001")]`. Existing calls now produce the compiler warning `CS0618` instead of the `ASPIRECSHARPAPPS001` error, and the TypeScript API surface emits `@deprecated` instead of `@experimental`.
+
+Add the [📦 Aspire.Hosting.Dotnet](https://www.nuget.org/packages/Aspire.Hosting.Dotnet) integration and replace calls with `AddDotnetProject` / `addDotnetProject`:
+
+```csharp title="AppHost.cs" del={1} ins={2}
+builder.AddCSharpApp("api", "./api/api.cs");
+builder.AddDotnetProject("api", "./api/api.cs");
+```
+
+`AddDotnetProject` accepts the same kinds of paths — a `.cs` file, a `.csproj` file, or a directory containing a single `.csproj` — but returns a `DotnetProjectResource` rather than a `ProjectResource` / `CSharpAppResource`. Explicitly typed resource builders and project-specific customizations might need updating. This change doesn't automatically migrate or alter the runtime behavior of existing `AddCSharpApp` consumers; legacy calls keep their current launch and publishing behavior and only need an explicit `#pragma warning disable CS0618` (or equivalent `NoWarn`/`.editorconfig` suppression) if you treat warnings as errors.
+
+<LearnMore>
+  See [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/) and
+  [Set up .NET / C# apps in the AppHost](/integrations/frameworks/dotnet/dotnet-host/)
+  for migration guidance. For the obsoletion details, see
+  [microsoft/aspire#20825](https://github.com/microsoft/aspire/pull/20825).
+</LearnMore>