From 5c395bb080699c51b3e4bd523d7ee0d59cd4bec5 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 23:07:20 +0000 Subject: [PATCH] docs: document AspireCliInvocationMode for dotnet run DNX invocation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/get-started/aspire-sdk.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) 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 ad75e3510..f838a5471 100644 --- a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx @@ -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@` 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. + +Set `AspireCliInvocationMode` in your AppHost `.csproj`: + +```xml title="MyApp.AppHost.csproj" + + true + Dnx + +``` + +:::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. +:::