Skip to content

[docs] Document AspireCliInvocationMode for dotnet run DNX invocation #1484

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.5
Choose a base branch
from
+21 −0
Open

[docs] Document AspireCliInvocationMode for dotnet run DNX invocation #1484

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 21 additions & 0 deletions src/frontend/src/content/docs/get-started/aspire-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,3 +146,24 @@ Most apps don't need to set the CLI bundle path. If the Aspire CLI isn't on `PAT
#### Running with aspire run or aspire start

When you start an opted-in AppHost using `aspire run` or `aspire start`, the CLI automatically passes the resolved bundle paths through the `ASPIRE_DCP_PATH` and `ASPIRE_DASHBOARD_PATH` environment variables.

#### Running with dotnet run

When `AspireUseCliBundle` is `true` and you start the AppHost with `dotnet run` instead of `aspire run`, the SDK resolves and invokes the Aspire CLI itself. Set `AspireCliInvocationMode` to control how that invocation happens:

- **`Path`** (default) — resolves a compatible `aspire` command from `PATH`. If no compatible command is found, it falls back to invoking the `Aspire.Cli` version paired with `Aspire.AppHost.Sdk` through [`dnx`](https://learn.microsoft.com/dotnet/core/tools/dotnet-dnx).
- **`Dnx`** — always invokes the Aspire CLI through `dnx`, using the unversioned `aspire.cli` package. This honors an in-scope [.NET local tool manifest](https://learn.microsoft.com/dotnet/core/tools/local-tools-how-to-use#create-a-manifest-file) (`.config/dotnet-tools.json`) if one pins `Aspire.Cli`, or resolves the latest published package when no manifest applies.
- **`DnxPinned`** — always invokes the Aspire CLI through `dnx`, using `aspire.cli@<version>` pinned to the exact `Aspire.Cli` version paired with `Aspire.AppHost.Sdk`. Use this when the CLI must match the AppHost SDK version exactly, ignoring any local tool manifest.
Comment on lines +155 to +156

Set `AspireCliInvocationMode` in your AppHost `.csproj`:

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

:::note
`dotnet run` is noninteractive, so `dnx` restores and executes without prompting for confirmation. If `dnx` can't be found on `PATH` when `Dnx` or `DnxPinned` mode is configured, the build emits error `ASPIRE011`. Install or use the .NET SDK 10.0 or later, set `AspireCliInvocationMode` to `Path` to use the global `aspire` command, or set `AspireCliPath` to an explicit Aspire CLI executable.
:::
Loading