Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/frontend/.starlight-icons/safelist.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,11 @@
"i-material-icon-theme:folder-src-open",
"i-material-icon-theme:folder-template",
"i-material-icon-theme:folder-template-open",
"i-material-icon-theme:folder-vscode",
"i-material-icon-theme:folder-vscode-open",
"i-material-icon-theme:git",
"i-material-icon-theme:go",
"i-material-icon-theme:go-mod",
"i-material-icon-theme:gradle",
"i-material-icon-theme:html",
"i-material-icon-theme:http",
Expand Down
1 change: 1 addition & 0 deletions src/frontend/config/sidebar/reference.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -826,6 +826,7 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
{ label: 'ASPIRE008', link: '/diagnostics/aspire008' },
{ label: 'ASPIRE009', link: '/diagnostics/aspire009' },
{ label: 'ASPIRE011', link: '/diagnostics/aspire011' },
{ label: 'ASPIRE013', link: '/diagnostics/aspire013' },
{
label: 'ASPIREACADOMAIN001',
link: '/diagnostics/aspireacadomains001',
Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/diagnostics/aspire009.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,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.
C# AppHosts require the CLI bundle, and setting `AspireUseCliBundle` to `false` reports [`ASPIRE013`](/diagnostics/aspire013/). Non-C# AppHosts can set it to `false` to restore orchestration dependencies from NuGet packages, which reports the suppressible warning [`ASPIRE010`](/diagnostics/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).
16 changes: 8 additions & 8 deletions src/frontend/src/content/docs/diagnostics/aspire010.mdx
Original file line number Diff line number Diff line change
@@ -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.
description: Learn what causes Aspire compiler warning ASPIRE010 — a non-C# AppHost has opted out of the Aspire CLI bundle — and how to enable or suppress it.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -15,25 +15,25 @@ 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.
This diagnostic warning is reported when a non-C# AppHost project, such as an F# (`.fsproj`) or Visual Basic (`.vbproj`) project, has `AspireUseCliBundle` set to `false`. Because `false` is the default for these projects, the warning is also reported when the property isn't set. 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.

C# AppHosts require the CLI bundle and report error [`ASPIRE013`](/diagnostics/aspire013/) instead. The two diagnostics are mutually exclusive.

## Example

The following configuration produces `ASPIRE010`:
The following configuration in a non-C# AppHost produces `ASPIRE010`:

```xml title="MyApp.AppHost.csproj"
```xml title="MyApp.AppHost.fsproj"
<PropertyGroup>
<AspireUseCliBundle>false</AspireUseCliBundle>
</PropertyGroup>
```

`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"
```xml title="MyApp.AppHost.fsproj"
<PropertyGroup>
<AspireUseCliBundle>true</AspireUseCliBundle>
</PropertyGroup>
Expand All @@ -45,7 +45,7 @@ An unresolved bundle layout reports [`ASPIRE009`](/diagnostics/aspire009/). [`AS

If you intend to keep using NuGet-restored orchestration dependencies, suppress `ASPIRE010`:

```xml title="MyApp.AppHost.csproj"
```xml title="MyApp.AppHost.fsproj"
<PropertyGroup>
<AspireUseCliBundle>false</AspireUseCliBundle>
<NoWarn>$(NoWarn);ASPIRE010</NoWarn>
Expand Down
42 changes: 42 additions & 0 deletions src/frontend/src/content/docs/diagnostics/aspire013.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Compiler Error ASPIRE013
seoTitle: 'ASPIRE013: Aspire CLI bundle required · Aspire'
description: Learn what causes Aspire compiler error ASPIRE013 when a C# AppHost disables the required Aspire CLI bundle, and how to correct it.
---

import { Badge } from '@astrojs/starlight/components';

<Badge
text="Version introduced: 17.0"
variant="note"
size="large"
class:list={'mb-1'}
/>

> '[ProjectName]' requires the Aspire CLI bundle. Remove AspireUseCliBundle or set it to true, and install the matching Aspire CLI from https://get.aspire.dev. ASPIRE013 cannot be suppressed to disable the bundle. See https://aka.ms/aspire/diagnostics/aspire013 for more information.

This diagnostic error is reported when a C# AppHost project has `AspireUseCliBundle` set to anything other than `true`. The CLI bundle is required for C# AppHosts. Adding `ASPIRE013` (or [`ASPIRE010`](/diagnostics/aspire010/)) to `NoWarn` doesn't bypass the requirement.

Non-C# AppHosts that opt out of the bundle report the suppressible warning [`ASPIRE010`](/diagnostics/aspire010/) instead. The two diagnostics are mutually exclusive.

## Example

The following configuration produces `ASPIRE013`:

```xml title="MyApp.AppHost.csproj"
<PropertyGroup>
<AspireUseCliBundle>false</AspireUseCliBundle>
</PropertyGroup>
```

## To correct this error

Remove the `AspireUseCliBundle` property, or set it to `true`, and install the matching Aspire CLI from [get.aspire.dev](https://get.aspire.dev):

```xml title="MyApp.AppHost.csproj"
<PropertyGroup>
<AspireUseCliBundle>true</AspireUseCliBundle>
</PropertyGroup>
```

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 change: 1 addition & 0 deletions src/frontend/src/content/docs/diagnostics/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [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. |
| [ASPIRE013](/diagnostics/aspire013/) | Error | 'Project' requires the Aspire CLI bundle. Remove AspireUseCliBundle or set it to true. |
| [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. |
| [ASPIREACANAMING001](/diagnostics/aspireacanaming001/) | (Experimental) Warning | <ApiReference name="Aspire.Hosting.AzureContainerAppExtensions.WithCompactResourceNaming" /> is for evaluation purposes only and is subject to change or removal in future updates. |
Expand Down
12 changes: 3 additions & 9 deletions src/frontend/src/content/docs/get-started/aspire-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ The Aspire SDK can source the binaries for these dependencies from platform-spec

When it uses the Aspire CLI bundle, those binaries update when you update the Aspire CLI through [`aspire update --self`](/reference/cli/commands/aspire-update/). Without the bundle, the Aspire SDK version used by the AppHost determines the binaries by adding implicit references to the RID-specific `Aspire.Hosting.Orchestration.*` and `Aspire.Dashboard.Sdk.*` packages.

New C# AppHost projects created with `aspire new` or `dotnet new`, and new single-file AppHosts created with `aspire init`, set `AspireUseCliBundle` to `true` automatically. For existing AppHosts, set `AspireUseCliBundle` to `true` to enable the CLI bundle. We recommend enabling it now because the CLI bundle will become the only supported source for orchestration dependencies in an upcoming Aspire release. The SDK property currently 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.
C# AppHosts (`.csproj` projects and single-file `apphost.cs` AppHosts) require the Aspire CLI bundle. `AspireUseCliBundle` defaults to `true` for them, so you don't need to set it. Setting it to any other value reports error [`ASPIRE013`](/diagnostics/aspire013/), and suppressing `ASPIRE013` doesn't bypass the requirement. Non-C# AppHosts, such as F# or Visual Basic projects, default to `false` and restore orchestration dependencies from NuGet packages. They report the suppressible warning [`ASPIRE010`](/diagnostics/aspire010/) until you set `AspireUseCliBundle` to `true`.

When `AspireUseCliBundle` is `true`:

Expand All @@ -122,20 +122,14 @@ When `AspireUseCliBundle` is `true`:

#### Enable the CLI bundle

Set `AspireUseCliBundle` in your AppHost `.csproj`:
C# AppHosts use the CLI bundle by default. To opt a non-C# AppHost, such as an F# project, in to the bundle, set `AspireUseCliBundle` in its project file:

```xml title="MyApp.AppHost.csproj"
```xml title="MyApp.AppHost.fsproj"
<PropertyGroup>
<AspireUseCliBundle>true</AspireUseCliBundle>
</PropertyGroup>
```

For an existing single-file AppHost, set the equivalent `#:property` directive:

```csharp title="apphost.cs"
#:property AspireUseCliBundle=true
```

:::note[Advanced scenario: Override the bundle path]
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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,7 @@ The destroy command requires --yes when the --non-interactive option is specifie

### Unknown arguments

`aspire destroy` rejects unrecognized options and positional arguments before it discovers or starts the AppHost, so a mistyped option can't silently run the destroy pipeline. The command exits with code `1`:

```bash title="Aspire CLI"
aspire destroy --force
```
`aspire destroy` rejects unrecognized options and positional arguments before it discovers or starts the AppHost, so a mistyped option can't silently run the destroy pipeline. For example, passing `--force`, which isn't an `aspire destroy` option, exits with code `1` and reports:

```text title="Output"
Unrecognized command or argument '--force'.
Expand Down
Loading