diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index bc05f97d8..4b7c912e9 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -598,6 +598,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: 'ASPIREEXPORT005', link: '/diagnostics/aspireexport005', @@ -715,6 +716,8 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { { label: 'ASPIRE006', link: '/diagnostics/aspire006' }, { label: 'ASPIRE007', link: '/diagnostics/aspire007' }, { label: 'ASPIRE008', link: '/diagnostics/aspire008' }, + { label: 'ASPIRE009', link: '/diagnostics/aspire009' }, + { label: 'ASPIRE011', link: '/diagnostics/aspire011' }, { label: 'ASPIREACADOMAIN001', link: '/diagnostics/aspireacadomains001', diff --git a/src/frontend/src/content/docs/diagnostics/aspire009.mdx b/src/frontend/src/content/docs/diagnostics/aspire009.mdx new file mode 100644 index 000000000..d8c46fa66 --- /dev/null +++ b/src/frontend/src/content/docs/diagnostics/aspire009.mdx @@ -0,0 +1,53 @@ +--- +title: Compiler Error ASPIRE009 +seoTitle: 'ASPIRE009: The Aspire CLI bundle could not be resolved · Aspire' +description: Learn what causes Aspire compiler error ASPIRE009 — the AppHost is configured to use the Aspire CLI bundle, but the bundle could not be resolved — and how to fix it. +--- + +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. + +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. + +## Example + +The following configuration produces `ASPIRE009` when the specified directory isn't a valid Aspire CLI bundle layout: + +```xml title="MyApp.AppHost.csproj" + + true + /path/to/missing-or-invalid/bundle + +``` + +## To correct this error + +If you set `AspireCliPath` or `AspireCliBundlePath`, correct or remove the invalid property: + +```xml title="MyApp.AppHost.csproj" {3-4} + + true + + /usr/local/bin/aspire + + + +``` + +When no explicit path is set, either [install the Aspire CLI](https://get.aspire.dev) so `aspire` and its bundle are available, or install and use .NET SDK 10.0 or later so a usable `dnx` host can run the Aspire CLI package selected by the invocation mode. + +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. + +For more information, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies). diff --git a/src/frontend/src/content/docs/diagnostics/aspire010.mdx b/src/frontend/src/content/docs/diagnostics/aspire010.mdx new file mode 100644 index 000000000..f99552d71 --- /dev/null +++ b/src/frontend/src/content/docs/diagnostics/aspire010.mdx @@ -0,0 +1,55 @@ +--- +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. +--- + +import { Badge } from '@astrojs/starlight/components'; + + + +> '[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. + +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. + +## Example + +The following configuration produces `ASPIRE010`: + +```xml title="MyApp.AppHost.csproj" + + false + +``` + +`ASPIRE010` is also reported when `AspireUseCliBundle` isn't set at all, because `false` is the default. + +## To correct this warning + +Set `AspireUseCliBundle` to `true` to opt in to CLI bundle delegation: + +```xml title="MyApp.AppHost.csproj" + + true + +``` + +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 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" + + false + $(NoWarn);ASPIRE010 + +``` + +For more information, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies). diff --git a/src/frontend/src/content/docs/diagnostics/aspire011.mdx b/src/frontend/src/content/docs/diagnostics/aspire011.mdx new file mode 100644 index 000000000..960833676 --- /dev/null +++ b/src/frontend/src/content/docs/diagnostics/aspire011.mdx @@ -0,0 +1,58 @@ +--- +title: Compiler Error ASPIRE011 +seoTitle: 'ASPIRE011: DNX command not found on PATH · Aspire' +description: Learn what causes Aspire compiler error ASPIRE011 when Dnx or DnxPinned mode can't find the dnx command, and how to correct it. +--- + +import { Badge } from '@astrojs/starlight/components'; + + + +> '[ProjectName]' is configured to invoke the Aspire CLI through DNX, but the dnx command could not be found on PATH. + +This diagnostic error is reported during run preflight when an AppHost project sets `AspireCliInvocationMode` to `Dnx` or `DnxPinned` but a usable `dnx` command can't be resolved on `PATH`. The emitted error identifies the configured mode. A regular build doesn't emit `ASPIRE011` because the SDK checks forced DNX availability when it prepares the run command. + +## Example + +The following configuration produces `ASPIRE011` when `dnx` isn't installed or isn't on `PATH`. Using `DnxPinned` instead produces the same diagnostic: + +```xml title="MyApp.AppHost.csproj" + + true + Dnx + +``` + +## To correct this error + +Use one of the following remedies: + +1. Install or use .NET SDK 10.0 or later, which provides `dnx`. +2. Set `AspireCliInvocationMode` to `Path` to use a global `aspire` command: + + ```xml title="MyApp.AppHost.csproj" + + true + Path + + ``` + +3. Set `AspireCliPath` to an explicit Aspire CLI executable: + + ```xml title="MyApp.AppHost.csproj" + + true + /usr/local/bin/aspire + + ``` + +Removing `AspireCliInvocationMode` is equivalent to the default `Path` behavior. An explicit `AspireCliPath` remains authoritative even when `AspireCliInvocationMode` is set to `Dnx` or `DnxPinned`. + +Both modes invoke DNX noninteractively. `Dnx` uses `dnx --yes aspire.cli -- ...`, allowing an in-scope tool manifest to select the package or DNX to use the latest package when no manifest applies. `DnxPinned` uses `dnx --yes aspire.cli@$(AspireHostingSDKVersion) -- ...` to select the version paired with the AppHost SDK. If DNX is found but can't restore, probe, or run the selected package, the launch fails with a separate error; `ASPIRE011` only indicates that a forced DNX mode couldn't find a usable `dnx` command. + +For more information, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies). diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx index f22708a22..3e894cdb8 100644 --- a/src/frontend/src/content/docs/diagnostics/overview.mdx +++ b/src/frontend/src/content/docs/diagnostics/overview.mdx @@ -15,6 +15,9 @@ The following table lists the possible MSBuild and analyzer warnings and errors | [ASPIRE006](/diagnostics/aspire006/) | (Experimental) Error | Application model items must have valid names. | | [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. | +| [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 | `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. | | [ASPIREEXPORT001](/diagnostics/aspireexport001/) | Error | `[AspireExport]` method must be static. | | [ASPIREEXPORT002](/diagnostics/aspireexport002/) | Error | Invalid export ID format (must match `[a-zA-Z][a-zA-Z0-9.]*`). | diff --git a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx index 3ef9858a9..e48e3e4de 100644 --- a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx @@ -108,17 +108,48 @@ Today, the Aspire SDK restores the binaries for these dependencies from platform Aspire is moving toward using the installed **Aspire CLI bundle** as the source for those orchestration dependencies. With this model, those binaries update when you update the Aspire CLI through [`aspire update --self`](/reference/cli/commands/aspire-update/) instead of being tied to RID-specific `Aspire.Hosting.Orchestration.*` and `Aspire.Dashboard.Sdk.*` package references in each AppHost project. -Set `AspireUseCliBundle` to `true` to opt in during the transition before this behavior becomes the default. +Set `AspireUseCliBundle` to `true` to opt in during the transition before this behavior becomes the default. `AspireUseCliBundle` defaults to `false`, so launching a C# AppHost with `dotnet run` or an IDE continues to work without requiring the Aspire CLI. Leaving it unset (or explicitly `false`) reports warning [`ASPIRE010`](/diagnostics/aspire010/) as a reminder that some Aspire features require the bundle; suppress it if you intend to keep using NuGet-restored orchestration dependencies. When `AspireUseCliBundle` is `true`: - `Aspire.AppHost.Sdk` still sets AppHost properties and adds the implicit `Aspire.Hosting.AppHost` package. - Your AppHost uses the DCP and Dashboard versions installed with the Aspire CLI. -- At build time, the SDK resolves the DCP and Dashboard executables in this priority order: - 1. Explicit `AspireCliBundlePath` / `AspireCliPath` properties in the project file. - 2. The `aspire` executable on `PATH`. -- If the resolved Aspire CLI has a bundle that hasn't been extracted yet, the build runs `aspire setup` through the selected `aspire` (or paired `dnx`) invocation to extract it, then resolves the bundle again. This recovers installations that didn't run the release install scripts, so an AppHost can build and launch directly from an IDE without first running an Aspire CLI command. -- If the bundle still cannot be found or resolved after setup runs, the build emits error `ASPIRE009` with a message directing you to [get.aspire.dev](https://get.aspire.dev) to install the Aspire CLI. +- The SDK selects the executable used to launch the AppHost as follows: + 1. An explicit `AspireCliPath` is always authoritative. + 2. When `AspireCliInvocationMode` is set to `Dnx` or `DnxPinned`, the SDK selects a usable `dnx` host. + 3. Otherwise, the default `Path` mode selects a compatible `aspire` on `PATH`, then falls back to the SDK-paired Aspire CLI package through DNX. +- `AspireCliBundlePath` isn't an executable candidate. It explicitly identifies a bundle layout for DCP and Dashboard resolution. +- If the resolved Aspire CLI has a bundle that hasn't been extracted yet, the build runs `aspire setup` through the selected `aspire` or paired DNX invocation to extract it, then resolves the bundle again. This lets an AppHost build and launch from an IDE even when the CLI installation didn't run the release install scripts. +- If a required bundle layout can't be resolved, the build emits error [`ASPIRE009`](/diagnostics/aspire009/). Invalid explicit `AspireCliPath` and `AspireCliBundlePath` values remain authoritative and can produce this error. +- If `Dnx` or `DnxPinned` mode can't find `dnx`, the run preflight emits error [`ASPIRE011`](/diagnostics/aspire011/) when it prepares the launch command. A regular build doesn't emit this diagnostic. + +#### Delegating through DNX + +The DNX package selection depends on `AspireCliInvocationMode`: + +- `Path` is the default. The AppHost prefers a compatible `aspire` on `PATH`. If the command is missing or can't support the run hook, the AppHost can fall back to `dnx --yes aspire.cli@$(AspireHostingSDKVersion) -- ...`, which selects the version paired with the AppHost SDK. +- `Dnx` skips `aspire` on `PATH` and invokes `dnx --yes aspire.cli -- ...`. The unversioned package reference allows an in-scope tool manifest to select the package; when no manifest applies, DNX uses the latest package. +- `DnxPinned` skips `aspire` on `PATH` and invokes `dnx --yes aspire.cli@$(AspireHostingSDKVersion) -- ...`, selecting the version paired with the AppHost SDK. + +All DNX invocations are noninteractive and use your configured NuGet sources. If DNX can't restore or probe the selected package, the launch fails explicitly instead of falling back to an incomplete direct launch. An explicit `AspireCliPath` remains authoritative and isn't replaced by DNX fallback. + +To force manifest-aware DNX delegation instead of preferring `aspire` on `PATH`, set `AspireCliInvocationMode`: + +```xml title="MyApp.AppHost.csproj" + + true + Dnx + +``` + +To force the SDK-paired package through DNX, use `DnxPinned`: + +```xml title="MyApp.AppHost.csproj" + + true + DnxPinned + +``` #### Enable the opt-in @@ -131,14 +162,14 @@ Set `AspireUseCliBundle` in your AppHost `.csproj`: ``` :::note[Advanced scenario: Override the bundle path] -Most apps don't need to set the CLI bundle path. If the Aspire CLI isn't on `PATH`, provide an explicit path using `AspireCliBundlePath` (path to the CLI bundle directory) or `AspireCliPath` (path to the `aspire` executable): +Most apps don't need to set either path. `AspireCliPath` selects an explicit `aspire` executable for invocation and bundle discovery. `AspireCliBundlePath` supplies an explicit unpacked bundle layout for DCP and Dashboard resolution, but it doesn't select the executable used to launch the AppHost: ```xml title="MyApp.AppHost.csproj" true - + /usr/local/bin/aspire - + ```