David Fowler (davidfowl) · Oct 13, 2026 · Oct 13, 2026 · Oct 16, 2026
@@ -1019,6 +1019,10 @@ export const docsTopics = {
                   label: 'Aspire SDK',
                   slug: 'get-started/aspire-sdk',
                 },
+                {
+                  label: 'Migrate from the AppHost SDK',
+                  slug: 'get-started/migrate-apphost-sdk',
+                },
                 {
                   label: 'Aspire templates',
                   slug: 'get-started/aspire-sdk-templates',

@@ -627,7 +627,7 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
             { label: 'ASPIRE002', link: '/diagnostics/aspire002' },
             { label: 'ASPIRE003', link: '/diagnostics/aspire003' },
             { label: 'ASPIRE004', link: '/diagnostics/aspire004' },
-            { label: 'ASPIRE010', link: '/diagnostics/aspire010' },
+            { label: 'ASPIRE012', link: '/diagnostics/aspire012' },
             {
               label: 'ASPIREEXPORT005',
               link: '/diagnostics/aspireexport005',
@@ -786,6 +786,7 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
             { label: 'ASPIRE007', link: '/diagnostics/aspire007' },
             { label: 'ASPIRE008', link: '/diagnostics/aspire008' },
             { label: 'ASPIRE009', link: '/diagnostics/aspire009' },
+            { label: 'ASPIRE010', link: '/diagnostics/aspire010' },
             { label: 'ASPIRE011', link: '/diagnostics/aspire011' },
             {
               label: 'ASPIREACADOMAIN001',

@@ -138,7 +138,13 @@ The version check runs only when:
 - The check hasn't been disabled via the `ASPIRE_VERSION_CHECK_DISABLED` configuration setting.
 - The app is not running in publish mode.
 
-Updates are manual. You need to edit your project file to upgrade the Aspire SDK and package versions.
+Use [`aspire update`](/reference/cli/commands/aspire-update/) or edit package versions manually. In Aspire 17.0, the default C# AppHost uses `Microsoft.NET.Sdk` and explicit `Aspire.Hosting.AppHost` and `Aspire.Hosting.Dotnet` packages. See [Migrate from the AppHost SDK](/get-started/migrate-apphost-sdk/) for existing SDK-based AppHosts.
+
+## CLI bundle configuration
+
+C# AppHosts in Aspire 17.0 require the Aspire CLI bundle. `AspireUseCliBundle` defaults to `true`; setting it to `false` produces error [ASPIRE010](/diagnostics/aspire010/) and can't be made valid with `NoWarn`. The bundle supplies the dashboard and DCP, including when the obsolete AppHost SDK is retained.
+
+`AspireCliPath` selects an executable; `AspireCliBundlePath` identifies an unpacked bundle layout. Invalid explicit paths remain authoritative and can produce [ASPIRE009](/diagnostics/aspire009/). For automatic discovery and DNX invocation modes, see [Use the Aspire CLI bundle](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies).
 
 ## Resource service
 
@@ -195,11 +201,11 @@ The `DcpCliPath` property specifies the path to the **Developer Control Plane (D
 
 #### How it works
 
-When you use the [Aspire SDK](/get-started/aspire-sdk/), the build system automatically:
+With the required [Aspire CLI bundle](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies), the AppHost targets automatically:
 
-1. Imports the platform-specific `Aspire.Hosting.Orchestration` NuGet package (for example, `Aspire.Hosting.Orchestration.win-x64`).
-2. Sets `DcpCliPath` to point to the `dcp` executable within that package.
-3. Embeds this path as assembly metadata in your compiled AppHost.
+1. Resolve DCP from the selected Aspire CLI bundle.
+2. Set `DcpCliPath` to point to the `dcp` executable within that bundle.
+3. Embed this path as assembly metadata in your compiled AppHost.
 
 At runtime, the AppHost reads this metadata to locate and start the DCP process, which then orchestrates your application's resources.
 
@@ -222,5 +228,5 @@ You might override `DcpCliPath` in these scenarios:
 - **Troubleshooting**: Temporarily pointing to a specific DCP version to diagnose issues.
 
 <Aside type="tip">
-If your AppHost fails to start with an error about missing DCP or orchestration dependencies, ensure you have the [Aspire SDK](/get-started/aspire-sdk/) properly configured rather than manually setting `DcpCliPath`.
+If your AppHost fails to start with an error about missing DCP or orchestration dependencies, correct the [CLI bundle configuration](/diagnostics/aspire009/) rather than manually setting `DcpCliPath` or disabling the bundle.
 </Aside>
@@ -15,7 +15,9 @@ import { Badge } from '@astrojs/starlight/components';
 
 > The project is missing a required Aspire.AppHost.Sdk with a version of at least 9.0.0. Please add the following line after the Project declaration `<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />`.
 
-The Aspire AppHost package references require Aspire SDK version 9.0.0 or greater. The SDK reference is either being omitted or is using a version older than 9.0.0.
+This diagnostic applies to the SDK requirement introduced with Aspire 9.0. With those package versions, the SDK reference is either omitted or uses a version older than 9.0.0. Aspire 17.0 still reports it for retained SDKs older than 9.0.0 or an invalid retained SDK reference. The legacy correction below is for SDK-based projects.
+
+Starting in Aspire 17.0, package-based AppHosts no longer require `Aspire.AppHost.Sdk`. Use `Microsoft.NET.Sdk` with explicit AppHost and Dotnet packages instead; see [Migrate from the AppHost SDK](/get-started/migrate-apphost-sdk/). Don't reintroduce the obsolete SDK into a package-based 17.0 AppHost to follow the legacy example.
 
 ## To correct this error
 

@@ -15,7 +15,7 @@ import { Badge } from '@astrojs/starlight/components';
 
 > '[ProjectName]' is configured to use the Aspire CLI bundle, but the bundle could not be resolved.
 
-This diagnostic error is reported when an AppHost project opts in to the Aspire CLI bundle (`AspireUseCliBundle=true`) but the SDK can't resolve a usable bundle layout for the developer control plane (DCP) and the Aspire Dashboard.
+This diagnostic error is reported when an AppHost project uses the Aspire CLI bundle (`AspireUseCliBundle=true`) but the AppHost targets can't resolve a usable bundle layout for the developer control plane (DCP) and the Aspire Dashboard. The bundle is enabled by default and required for C# AppHosts in Aspire 17.0.
 
 When neither `AspireCliPath` nor `AspireCliBundlePath` is set, a usable `dnx` host can resolve or prepare the required bundle layout through the selected Aspire CLI package. Therefore, a missing `aspire` command alone doesn't cause `ASPIRE009`. Explicit paths are authoritative: an invalid `AspireCliPath` or `AspireCliBundlePath` causes `ASPIRE009` even when `dnx` is available.
 
@@ -48,6 +48,6 @@ When no explicit path is set, either [install the Aspire CLI](https://get.aspire
 
 If `Dnx` or `DnxPinned` mode can't find `dnx`, the run preflight reports [`ASPIRE011`](/diagnostics/aspire011/). A missing `dnx` command isn't itself an `ASPIRE009` condition, although a separate bundle-resolution failure can still produce `ASPIRE009`.
 
-Alternatively, set `AspireUseCliBundle` to `false` to restore orchestration dependencies from NuGet packages. Doing so reports [`ASPIRE010`](/diagnostics/aspire010/) because some Aspire features require the CLI bundle.
+In Aspire 17.0, setting `AspireUseCliBundle` to `false` isn't a workaround: it produces error [`ASPIRE010`](/diagnostics/aspire010/), which can't be suppressed to disable the bundle. Correct the installation or invalid path instead.
 
 For more information, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies).
@@ -1,7 +1,7 @@
 ---
-title: Compiler Warning ASPIRE010
-seoTitle: 'ASPIRE010: Aspire CLI bundle opt-out warning · Aspire'
-description: Learn what causes Aspire compiler warning ASPIRE010 — the AppHost has opted out of the Aspire CLI bundle — and how to enable or suppress it.
+title: Compiler Error ASPIRE010
+seoTitle: 'ASPIRE010: The Aspire CLI bundle is required'
+description: Learn why disabling the required Aspire CLI bundle produces error ASPIRE010 in Aspire 17.0 and how to correct it.
 ---
 
 import { Badge } from '@astrojs/starlight/components';
@@ -13,9 +13,9 @@ import { Badge } from '@astrojs/starlight/components';
   class:list={'mb-1'}
 />
 
-> '[ProjectName]' is configured with AspireUseCliBundle=false. Some Aspire features require the Aspire CLI bundle. Set AspireUseCliBundle=true to enable those features, or suppress ASPIRE010 to continue without the bundle. See https://aka.ms/aspire/diagnostics/aspire010 for more information.
+> [ProjectName] requires the Aspire CLI bundle. Remove AspireUseCliBundle or set it to true, and install the matching Aspire CLI from https://get.aspire.dev. ASPIRE010 cannot be suppressed to disable the bundle. See https://aka.ms/aspire/diagnostics/aspire010 for more information.
 
-This diagnostic warning is reported when an AppHost project has `AspireUseCliBundle` set to `false` (the default). Launching the AppHost directly with `dotnet run` or an IDE continues to work without the Aspire CLI, but features that depend on the CLI bundle — such as resolving DCP and the Aspire Dashboard from the installed Aspire CLI instead of NuGet packages — remain unavailable.
+Introduced as a warning in Aspire 13.5, this diagnostic is an **error in Aspire 17.0** when a C# AppHost disables the required CLI bundle. `AspireUseCliBundle` now defaults to `true`. This applies both to package-based AppHosts and projects retaining `Aspire.AppHost.Sdk`.
 
 ## Example
 
@@ -27,29 +27,22 @@ The following configuration produces `ASPIRE010`:
 </PropertyGroup>
 ```
 
-`ASPIRE010` is also reported when `AspireUseCliBundle` isn't set at all, because `false` is the default.
+Leaving `AspireUseCliBundle` unset uses the enabled default and doesn't produce this error.
 
-## To correct this warning
+## To correct this error
 
-Set `AspireUseCliBundle` to `true` to opt in to CLI bundle delegation:
+Remove the `false` setting or set `AspireUseCliBundle` to `true`, and [install a compatible Aspire CLI](/get-started/install-cli/):
 
 ```xml title="MyApp.AppHost.csproj"
 <PropertyGroup>
   <AspireUseCliBundle>true</AspireUseCliBundle>
 </PropertyGroup>
 ```
 
-When you opt in, an explicit `AspireCliPath` is authoritative. Otherwise, the default `Path` invocation mode selects a compatible `aspire` on `PATH`, with the SDK-paired Aspire CLI package through DNX as a fallback. Setting `AspireCliInvocationMode=Dnx` selects the unversioned package through DNX so a tool manifest can apply, while `DnxPinned` selects the version paired with the AppHost SDK. `AspireCliBundlePath` is a bundle-layout input, not an executable invocation candidate.
+An explicit `AspireCliPath` is authoritative. Otherwise, the default `Path` invocation mode selects a compatible `aspire` on `PATH`, with the CLI package paired with `Aspire.Hosting.AppHost` through DNX as a fallback. `AspireCliInvocationMode=Dnx` selects the unversioned package through DNX so a tool manifest can apply, while `DnxPinned` selects the AppHost-package-paired version. `AspireCliBundlePath` is a bundle-layout input, not an executable invocation candidate.
 
 An unresolved bundle layout reports [`ASPIRE009`](/diagnostics/aspire009/). [`ASPIRE011`](/diagnostics/aspire011/) is limited to the run preflight when `Dnx` or `DnxPinned` mode can't find `dnx`; it doesn't represent every CLI resolution failure.
 
-If you intend to keep using NuGet-restored orchestration dependencies, suppress `ASPIRE010`:
-
-```xml title="MyApp.AppHost.csproj"
-<PropertyGroup>
-  <AspireUseCliBundle>false</AspireUseCliBundle>
-  <NoWarn>$(NoWarn);ASPIRE010</NoWarn>
-</PropertyGroup>
-```
+`NoWarn=ASPIRE010` doesn't suppress this error or make a bundle opt-out valid. Earlier versions' warning suppression guidance doesn't apply to Aspire 17.0.
 
 For more information, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies).
@@ -0,0 +1,39 @@
+---
+title: Compiler Warning ASPIRE012
+seoTitle: 'ASPIRE012: Aspire.AppHost.Sdk is obsolete'
+description: Learn why Aspire.AppHost.Sdk reports ASPIRE012, how to migrate to explicit packages, and how to suppress the warning during staged migration.
+---
+
+import { Badge } from '@astrojs/starlight/components';
+
+<Badge text="Version introduced: 17.0" variant="note" size="large" class:list={'mb-1'} />
+
+> [ProjectName] uses the Aspire.AppHost.Sdk, which is obsolete but remains available for staged migration. Switch the project's Sdk attribute to Microsoft.NET.Sdk, add explicit PackageReference items for Aspire.Hosting.AppHost and Aspire.Hosting.Dotnet, and migrate C# resource ProjectReference items to AddDotnetProject calls. See https://aka.ms/aspire/diagnostics/aspire012 for migration guidance.
+
+This warning is reported when a project uses `Aspire.AppHost.Sdk`. The SDK remains functional, including original `ProjectReference` and `AddProject` resources. No removal date has been agreed, and this warning doesn't deprecate `AddProject`.
+
+## To correct this warning
+
+Follow [Migrate from the AppHost SDK](/get-started/migrate-apphost-sdk/): use `Microsoft.NET.Sdk`, explicitly reference `Aspire.Hosting.AppHost` and `Aspire.Hosting.Dotnet`, and use `AddDotnetProject` for path-based resources. Keep the required CLI bundle enabled.
+
+For staged migration, retained `AddProject` resources require `IsAspireProjectResource="true"` and `ReferenceOutputAssembly="false"` on their project references after removing the SDK.
+
+## Suppress the warning temporarily
+
+While you retain the obsolete SDK, set:
+
+```xml
+<PropertyGroup>
+  <SuppressAspireAppHostSdkObsoleteWarning>true</SuppressAspireAppHostSdkObsoleteWarning>
+</PropertyGroup>
+```
+
+Alternatively, append `ASPIRE012` to `NoWarn`:
+
+```xml
+<PropertyGroup>
+  <NoWarn>$(NoWarn);ASPIRE012</NoWarn>
+</PropertyGroup>
+```
+
+Suppression doesn't change resource declarations or bundle requirements. Unlike this warning, [ASPIRE010](/diagnostics/aspire010/) is an error in Aspire 17.0 and can't be suppressed to disable the bundle.
@@ -18,7 +18,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
 | [ASPIRE007](/diagnostics/aspire007/)                                               | Error                  | 'Project' requires a reference to "Aspire.AppHost.Sdk" with version "9.0.0" or greater to work correctly.                                                                                      |
 | [ASPIRE008](/diagnostics/aspire008/)                                               | Error                  | 'Project' requires GenerateAssemblyInfo to be enabled for the AppHost to function correctly.                                                                                                   |
 | [ASPIRE009](/diagnostics/aspire009/)                                               | Error                  | 'Project' is configured to use the Aspire CLI bundle, but the bundle could not be resolved.                                                                                                    |
-| [ASPIRE010](/diagnostics/aspire010/)                                               | Warning                | 'Project' is configured with AspireUseCliBundle=false. Some Aspire features require the Aspire CLI bundle.                                                                                     |
+| [ASPIRE010](/diagnostics/aspire010/)                                               | Error (17.0 onward)     | The C# AppHost requires the Aspire CLI bundle. Remove AspireUseCliBundle or set it to true; warning suppression doesn't permit opting out. |
 | [ASPIRE011](/diagnostics/aspire011/)                                               | Error                  | 'Project' is configured to invoke the Aspire CLI through DNX, but the dnx command could not be found on PATH.                                                                                  |
 | [ASPIREACADOMAINS001](/diagnostics/aspireacadomains001/)                           | (Experimental) Error   | <ApiReference name="Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain" /> is for evaluation purposes only and is subject to change or removal in future updates.                                                                                 |
 | [ASPIREACAEXPRESS001](/diagnostics/aspireacaexpress001/)                           | (Experimental) Error   | <ApiReference name="Aspire.Hosting.AzureContainerAppExtensions.AsExpress" /> is for evaluation purposes only and is subject to change or removal in future updates.                                                                                             |