From 2700ca3ed48ff177cf18c131979d4347cd632620 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 26 Jun 2025 17:04:36 -0700 Subject: [PATCH 01/40] Initial drafts --- docs/cli/install.md | 40 ++++++++++++++++++++++++++++++++ docs/cli/overview.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ docs/toc.yml | 8 +++++++ 3 files changed, 102 insertions(+) create mode 100644 docs/cli/install.md create mode 100644 docs/cli/overview.md diff --git a/docs/cli/install.md b/docs/cli/install.md new file mode 100644 index 0000000000..07261a7cf8 --- /dev/null +++ b/docs/cli/install.md @@ -0,0 +1,40 @@ +--- +title: Install .NET Aspire CLI +description: Learn how to install .NET Aspire CLI, which is a .NET global tool. Use the .NET Aspire CLI to create, run, and manage .NET Aspire projects. +author: adegeo +ms.author: adegeo +ms.topic: install-set-up-deploy +ms.date: 06/26/2025 + +#customer intent: As a developer, I want to install the .NET Aspire CLI so that I can create, run, and manage .NET Aspire projects. + +--- + +# Install .NET Aspire CLI + +This article teaches you how to install .NET Aspire CLI, which is a .NET global tool used to manage your .NET Aspire projects. + +## Prerequisites + +- [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0). + +## Install the global tool + +Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is `Aspire.Cli`. + +1. Open a terminal. +1. Run `dotnet tool install -g Aspire.Cli --prerelease` to install the global tool. + +## Validation + +To validate that the global tool is installed, use the `--version` parameter to query Aspire CLI for a version number: + +``` +aspire --version +``` + +If that command works, you're presented with the version of the .NET Aspire CLI tool: + +``` +9.3.1-preview.1.25305.6+5bc26c78ff8c7be825d0ae33633a1ae9f1d64a67 +``` diff --git a/docs/cli/overview.md b/docs/cli/overview.md new file mode 100644 index 0000000000..fb0c6d6e53 --- /dev/null +++ b/docs/cli/overview.md @@ -0,0 +1,54 @@ +--- +title: .NET Aspire CLI Overview and Commands +description: Learn .NET Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +ms.date: 06/26/2025 +ms.topic: overview +ms.custom: + - ai-gen-docs-bap + - ai-gen-title + - ai-seo-date:06/26/2025 + - ai-gen-description +--- + +# .NET Aspire CLI Overview + +// TODO: More selling of why you want to use this instead of the .NET CLI you're probably already familiar with. + +The .NET Aspire CLI (`aspire` command) is a .NET global tool that provides command-line functionality to create, manage, run, and publish Aspire projects. Use the .NET Aspire CLI to streamline development workflows for distributed applications. + +- [Install .NET Aspire CLI](install.md) + +## Create projects + +The `aspire new` command creates one or more Aspire projects that the Aspire CLI tool installs the latest Aspire project templates into the `dotnet` system. + +Use the `aspire new` command to create an Aspire project from a list of templates. Once a template is selected, the name of the project is set, and the output folder is chosen, `aspire` downloads the latest templates and generates one or more projects. + +## Run the app host project + +// TODO: This also checks certs, and does it do anything else? What else should we point out? + +The `aspire run` command runs the app host project in development mode, which launches the dashboard and any projects configured with the app host. This is similar to running the app host project in your IDE of choice, however, a terminal dashboard is also visible. For example: + +```aspire +Dashboard: +📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0a + +╭─────────────┬─────────┬─────────┬────────────────────────╮ +│ Resource │ Type │ State │ Endpoint(s) │ +├─────────────┼─────────┼─────────┼────────────────────────┤ +│ apiservice │ Project │ Running │ https://localhost:7422 │ +│ │ │ │ http://localhost:5327 │ +│ webfrontend │ Project │ Running │ https://localhost:7241 │ +│ │ │ │ http://localhost:5185 │ +╰─────────────┴─────────┴─────────┴────────────────────────╯ +Press CTRL-C to stop the app host and exit. +``` + +## Add integrations + +The `aspire add` command is an easy way to add integration packages to your app host. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. + +## Publish Aspire applications + +// TODO: Stuff about publishing diff --git a/docs/toc.yml b/docs/toc.yml index a6912b9fc2..af46f70c88 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -108,6 +108,14 @@ items: - name: Microsoft-collected dashboard telemetry href: fundamentals/dashboard/microsoft-collected-dashboard-telemetry.md +- name: .NET Aspire CLI + displayName: aspire cli,aspire command line interface,aspire commands,cli + items: + - name: Overview + href: cli/overview.md + - name: Install + href: cli/install.md + - name: Testing items: - name: Overview From b5c7a2758203e302f469e7c499582e52f426a4ac Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Mon, 30 Jun 2025 16:03:46 -0700 Subject: [PATCH 02/40] Apply suggestions from code review Co-authored-by: David Pine --- docs/cli/install.md | 2 +- docs/cli/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli/install.md b/docs/cli/install.md index 07261a7cf8..89e8a6d48d 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -20,7 +20,7 @@ This article teaches you how to install .NET Aspire CLI, which is a .NET global ## Install the global tool -Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is `Aspire.Cli`. +Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). 1. Open a terminal. 1. Run `dotnet tool install -g Aspire.Cli --prerelease` to install the global tool. diff --git a/docs/cli/overview.md b/docs/cli/overview.md index fb0c6d6e53..1ceae7ab4b 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -20,7 +20,7 @@ The .NET Aspire CLI (`aspire` command) is a .NET global tool that provides comma ## Create projects -The `aspire new` command creates one or more Aspire projects that the Aspire CLI tool installs the latest Aspire project templates into the `dotnet` system. +The `aspire new` command creates one or more Aspire projects that the Aspire CLI tool installs the latest Aspire project templates into the `dotnet` system. Use the `aspire new` command to create an Aspire project from a list of templates. Once a template is selected, the name of the project is set, and the output folder is chosen, `aspire` downloads the latest templates and generates one or more projects. From 4f9898bde4591b755980388cc7dd8738738e7742 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 30 Jun 2025 16:29:03 -0700 Subject: [PATCH 03/40] Add first aspire cli ref doc --- docs/cli-reference/aspire.md | 75 ++++++++++++++++++++++++++++++++++++ docs/toc.yml | 6 ++- 2 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 docs/cli-reference/aspire.md diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md new file mode 100644 index 0000000000..a48d60b67b --- /dev/null +++ b/docs/cli-reference/aspire.md @@ -0,0 +1,75 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 06/26/2025 +--- +# dotnet command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire` - The generic driver for the Aspire CLI. + +## Synopsis + +To get information about the available commands and the environment: + +```dotnetcli +aspire [command] [options] +``` + +## Description + +The `aspire` command provides commands for working with Aspire projects. For example `aspire run` runs an Aspire AppHost project. + +## Options + +The following options are available when `aspire` is used by itself, without specifying a command. For example, `aspire --version`. + +- **`-?, -h, --help`** + + Prints out help and usage documentation for the available commands and options. + +- **`--version`** + + Prints the version of the .NET Aspire CLI tool. + +- **`-d, --debug`** + + Enable debug logging to the console, which prints out detailed information about what .NET Aspire CLI is doing when a command is run. + +- **`--wait-for-debugger`** + + Wait for a debugger to attach before running a command. + +## Commands + +| Command | Function | +|-------------------------------------|----------------------------------------------------------------| +| [aspire new](aspire-new.md) | Create an Aspire sample project from a template. | +| [aspire run](aspire-run.md) | Run an Aspire app host in development mode. | +| [aspire add](aspire-add.md) | Add an integration to the Aspire project. | +| [aspire publish](aspire-publish.md) | Generates deployment artifacts for an Aspire app host project. | +| [aspire config](aspire-config.md) | | +| [aspire exec](aspire-exec.md) | | + +## Examples + +Create an Aspire application: + +```dotnetcli +aspire new aspire-starter +``` + +Run an Aspire app host project: + +```command +aspire run +``` + +## See also + +- [Environment variables used by .NET SDK, .NET CLI, and .NET runtime](dotnet-environment-variables.md) +- [Runtime Configuration Files](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md) +- [.NET runtime configuration settings](../runtime-config/index.md) \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index af46f70c88..846f2aaf99 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -108,13 +108,17 @@ items: - name: Microsoft-collected dashboard telemetry href: fundamentals/dashboard/microsoft-collected-dashboard-telemetry.md -- name: .NET Aspire CLI +- name: Aspire CLI displayName: aspire cli,aspire command line interface,aspire commands,cli items: - name: Overview href: cli/overview.md - name: Install href: cli/install.md + - name: aspire command reference + items: + - name: aspire + href: cli-reference/aspire.md - name: Testing items: From 118898e1f3eb80293fe003168a45b4c45634c00b Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 30 Jun 2025 16:29:25 -0700 Subject: [PATCH 04/40] Feedback for install --- docs/cli/install.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/cli/install.md b/docs/cli/install.md index 89e8a6d48d..d8de103752 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -22,12 +22,16 @@ This article teaches you how to install .NET Aspire CLI, which is a .NET global Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). -1. Open a terminal. -1. Run `dotnet tool install -g Aspire.Cli --prerelease` to install the global tool. +01. Open a terminal. +01. Run the following command to install Aspire CLI: + + ```dotnetcli + dotnet tool install -g Aspire.Cli --prerelease + ``` ## Validation -To validate that the global tool is installed, use the `--version` parameter to query Aspire CLI for a version number: +To validate that the global tool is installed, use the `--version` option to query Aspire CLI for a version number: ``` aspire --version From 3557b67d759bedf450f5ee43ac01b0a141c9b8bf Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 30 Jun 2025 16:29:49 -0700 Subject: [PATCH 05/40] Update create and run sections --- docs/cli/overview.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 1ceae7ab4b..d17cad2c4f 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -16,21 +16,37 @@ ms.custom: The .NET Aspire CLI (`aspire` command) is a .NET global tool that provides command-line functionality to create, manage, run, and publish Aspire projects. Use the .NET Aspire CLI to streamline development workflows for distributed applications. +The Aspire CLI is an interactive-first experience. + - [Install .NET Aspire CLI](install.md) ## Create projects -The `aspire new` command creates one or more Aspire projects that the Aspire CLI tool installs the latest Aspire project templates into the `dotnet` system. +The `aspire new` command is an interactive-first CLI experience, and is used to create one or more Aspire projects. As part of creating a project, Azure CLI ensures that the latest Aspire project templates are installed into the `dotnet` system. + + Use the `aspire new` command to create an Aspire project from a list of templates. Once a template is selected, the name of the project is set, and the output folder is chosen, `aspire` downloads the latest templates and generates one or more projects. +While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. + ## Run the app host project -// TODO: This also checks certs, and does it do anything else? What else should we point out? +The `aspire run` command runs the app host project in development mode, which configures the Aspire environment, builds the app host, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the app host project in your IDE of choice, however, a terminal dashboard is also visible. + +When `aspire run` starts, it searches the current directory for an app host. If an app host isn't found, the sub directories are searched until an app host is found. If no app host is found, Aspire stops. Once an app host is found, Aspire CLI takes the following stesp: + +- Installs or verifies that Aspires local hosting certificates are installed and trusted. +- Builds the app host project. +- Starts the app host. +- Starts the dashboard. +- Displays a terminal-based dashboard. -The `aspire run` command runs the app host project in development mode, which launches the dashboard and any projects configured with the app host. This is similar to running the app host project in your IDE of choice, however, a terminal dashboard is also visible. For example: + -```aspire +The following snippet is an example of the terminal dashboard: + +```Aspire CLI Dashboard: 📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0a @@ -47,8 +63,14 @@ Press CTRL-C to stop the app host and exit. ## Add integrations -The `aspire add` command is an easy way to add integration packages to your app host. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. +The `aspire add` command is an easy way to add official integration packages to your app host. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. + + ## Publish Aspire applications // TODO: Stuff about publishing + +## Configure Aspire environment + + From 0709ceeb2cd5710915cc90c9fccaa5e8d3dbc2d2 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 10 Jul 2025 08:46:29 -0700 Subject: [PATCH 06/40] Checkpoint --- docs/cli/overview.md | 55 ++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/cli/overview.md b/docs/cli/overview.md index d17cad2c4f..1edc339c96 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -1,6 +1,6 @@ --- title: .NET Aspire CLI Overview and Commands -description: Learn .NET Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +description: Learn .NET Aspire CLI commands for creating projects, running an apphost, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. ms.date: 06/26/2025 ms.topic: overview ms.custom: @@ -12,14 +12,32 @@ ms.custom: # .NET Aspire CLI Overview -// TODO: More selling of why you want to use this instead of the .NET CLI you're probably already familiar with. - -The .NET Aspire CLI (`aspire` command) is a .NET global tool that provides command-line functionality to create, manage, run, and publish Aspire projects. Use the .NET Aspire CLI to streamline development workflows for distributed applications. +The Aspire CLI (`aspire` command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish polyglot Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications. The Aspire CLI is an interactive-first experience. - [Install .NET Aspire CLI](install.md) +## Commands + +The following table describes the basic commands provided by Aspire: + +| Command | Status | Function | +|------------------------------------------------------------|---------|---------------------------------------------------------------------------| +| [`aspire add`](#add-integrations) | Stable | Add an integration to the Aspire project. | +| [`aspire new`](#create-projects) | Stable | Create an Aspire sample project from a template. | +| [`aspire run`](#run-the-apphost-project) | Stable | Run an Aspire apphost in development mode. | +| [`aspire exec`](#run-commands-in-resource-context-preview) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire deploy`](#deploy-aspire-applications-preview) | Preview | Deploys the artifacts created by `aspire publish`. | +| [`aspire publish`](#publish-aspire-applications-preview) | Preview | Generates deployment artifacts for an Aspire apphost project. | + + + ## Create projects The `aspire new` command is an interactive-first CLI experience, and is used to create one or more Aspire projects. As part of creating a project, Azure CLI ensures that the latest Aspire project templates are installed into the `dotnet` system. @@ -30,15 +48,15 @@ Use the `aspire new` command to create an Aspire project from a list of template While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. -## Run the app host project +## Run the apphost project -The `aspire run` command runs the app host project in development mode, which configures the Aspire environment, builds the app host, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the app host project in your IDE of choice, however, a terminal dashboard is also visible. +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal dashboard is also visible. -When `aspire run` starts, it searches the current directory for an app host. If an app host isn't found, the sub directories are searched until an app host is found. If no app host is found, Aspire stops. Once an app host is found, Aspire CLI takes the following stesp: +When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following stesp: - Installs or verifies that Aspires local hosting certificates are installed and trusted. -- Builds the app host project. -- Starts the app host. +- Builds the apphost project. +- Starts the apphost. - Starts the dashboard. - Displays a terminal-based dashboard. @@ -48,7 +66,7 @@ The following snippet is an example of the terminal dashboard: ```Aspire CLI Dashboard: -📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0a +📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0b ╭─────────────┬─────────┬─────────┬────────────────────────╮ │ Resource │ Type │ State │ Endpoint(s) │ @@ -58,19 +76,26 @@ Dashboard: │ webfrontend │ Project │ Running │ https://localhost:7241 │ │ │ │ │ http://localhost:5185 │ ╰─────────────┴─────────┴─────────┴────────────────────────╯ -Press CTRL-C to stop the app host and exit. +Press CTRL-C to stop the apphost and exit. ``` ## Add integrations -The `aspire add` command is an easy way to add official integration packages to your app host. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. +The `aspire add` command is an easy way to add official integration packages to your apphost. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. -## Publish Aspire applications +## Publish Aspire applications (preview) + +The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. + +## Deploy Aspire applications (preview) -// TODO: Stuff about publishing +The `aspire deploy` command is similar to `aspire publish`, except that in addition to serializing resources, it also deploys resources that have registered a `DeployingCallbackAnnotation` annotation. -## Configure Aspire environment +> [!TIP] +> Consider this a good way to deploy your Aspire solution to a staging area for testing. +## Run commands in resource context (preview) +The `aspire exec` command runs commands in the context of a specific Aspire resource, inheriting that resource's configuration including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run `aspire exec --resource api -- dotnet ef migrations add Init` to run Entity Framework commands with the proper database connection strings automatically configured. From ed47d1b45f1511ad6872b64618dba6e05b24fc96 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 10 Jul 2025 08:47:35 -0700 Subject: [PATCH 07/40] Checkpoint 2 --- docs/cli-reference/aspire.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index a48d60b67b..ec1ddddc63 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -45,26 +45,26 @@ The following options are available when `aspire` is used by itself, without spe ## Commands -| Command | Function | -|-------------------------------------|----------------------------------------------------------------| -| [aspire new](aspire-new.md) | Create an Aspire sample project from a template. | -| [aspire run](aspire-run.md) | Run an Aspire app host in development mode. | -| [aspire add](aspire-add.md) | Add an integration to the Aspire project. | -| [aspire publish](aspire-publish.md) | Generates deployment artifacts for an Aspire app host project. | -| [aspire config](aspire-config.md) | | -| [aspire exec](aspire-exec.md) | | +| Command | Status | Function | +|---------------------------------------|---------|--------------------------------------------------------------------------| +| [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | +| [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | +| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | +| [`aspire exec`](aspire-exec.md) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | +| [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | ## Examples Create an Aspire application: -```dotnetcli +```Command aspire new aspire-starter ``` Run an Aspire app host project: -```command +```Command aspire run ``` From 84392e14ee2b5a4a2c8caed89998fe6ecb79c78c Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Tue, 1 Jul 2025 08:46:15 -0700 Subject: [PATCH 08/40] Apply suggestions from code review Co-authored-by: David Pine --- docs/cli-reference/aspire.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index ec1ddddc63..865fc2e02a 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -56,7 +56,7 @@ The following options are available when `aspire` is used by itself, without spe ## Examples -Create an Aspire application: +Create an Aspire solution from the template: ```Command aspire new aspire-starter From 426fd7ce30d750e84040caee9b8069bbaa19a0d2 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 08:22:31 -0700 Subject: [PATCH 09/40] Test include --- docs/cli-reference/aspire.md | 2 +- docs/cli-reference/includes/option-help.md | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/cli-reference/includes/option-help.md diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 865fc2e02a..2215a0375e 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -29,7 +29,7 @@ The following options are available when `aspire` is used by itself, without spe - **`-?, -h, --help`** - Prints out help and usage documentation for the available commands and options. + [!INCLUDE [option-help](includes/option-help.md)] - **`--version`** diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md new file mode 100644 index 0000000000..47998ac0bb --- /dev/null +++ b/docs/cli-reference/includes/option-help.md @@ -0,0 +1,7 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 06/26/2025 +ms.topic: include +--- +Prints out help and usage documentation for the available commands and options. From 79be31f8a8312f33459044c0c6ae6ae5b0b1ead0 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 08:26:07 -0700 Subject: [PATCH 10/40] Option test 2 --- docs/cli-reference/aspire.md | 4 +--- docs/cli-reference/includes/option-help.md | 2 +- docs/cli-reference/includes/option-version.md | 9 +++++++++ 3 files changed, 11 insertions(+), 4 deletions(-) create mode 100644 docs/cli-reference/includes/option-version.md diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 2215a0375e..1c99d99db4 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -31,9 +31,7 @@ The following options are available when `aspire` is used by itself, without spe [!INCLUDE [option-help](includes/option-help.md)] -- **`--version`** - - Prints the version of the .NET Aspire CLI tool. +- [!INCLUDE [option-version](includes/option-version.md)] - **`-d, --debug`** diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md index 47998ac0bb..0e1797a911 100644 --- a/docs/cli-reference/includes/option-help.md +++ b/docs/cli-reference/includes/option-help.md @@ -4,4 +4,4 @@ description: Learn about the aspire command (the generic driver for the Aspire C ms.date: 06/26/2025 ms.topic: include --- -Prints out help and usage documentation for the available commands and options. +Printaaas out help and usage documentation for the available commands and options. diff --git a/docs/cli-reference/includes/option-version.md b/docs/cli-reference/includes/option-version.md new file mode 100644 index 0000000000..8ea30073ef --- /dev/null +++ b/docs/cli-reference/includes/option-version.md @@ -0,0 +1,9 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 06/26/2025 +ms.topic: include +--- +**`--versiona`** + + Prints the version of the .NET Aspire CLI tool. \ No newline at end of file From 2d0b27410e7335e3bdb007b588ebbf56fe190a30 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 11:18:38 -0700 Subject: [PATCH 11/40] Fix up aspire cmd; add aspire-new cmd. --- docs/cli-reference/aspire-new.md | 85 +++++++++++++++++++ docs/cli-reference/aspire.md | 38 +++------ docs/cli-reference/includes/option-debug.md | 9 ++ docs/cli-reference/includes/option-help.md | 6 +- docs/cli-reference/includes/option-version.md | 6 +- docs/cli-reference/includes/option-wait.md | 9 ++ docs/toc.yml | 2 + 7 files changed, 125 insertions(+), 30 deletions(-) create mode 100644 docs/cli-reference/aspire-new.md create mode 100644 docs/cli-reference/includes/option-debug.md create mode 100644 docs/cli-reference/includes/option-wait.md diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md new file mode 100644 index 0000000000..7ec7cc561e --- /dev/null +++ b/docs/cli-reference/aspire-new.md @@ -0,0 +1,85 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +--- +# aspire new command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire new` - Create a new Aspire project, app, or solution. + +Supports: + +- ✔️ Interactive +- ✔️ Non-interactive + +## Synopsis + +Create a new Aspire project: + +```dotnetcli +aspire new [command] [options] +``` + +## Description + +The `aspire new` command is the driver for creating Aspire projects, apps, or solutions, based on the Aspire templates. Each command specifies the template to use, and the options for the driver specify the options for the template. + +This command defaults to **interactive** mode. By issuing the command without any options, the command prompts you for the project template and version, name, and output folder. input to fill out the options. When the `--name`, `--output`, and `--version` options are provided, the command runs **non-interactive** and generates files based on the command template. + +## Options + +The following options are available: + +- **`-n, --name`** + + The name of the project to create. + +- **`-o, --output`** + + The output path for the project. + +- **`-s, --source`** + + The NuGet source to use for the project templates. + +- **`-v, --version`** + + The version of the project templates to use. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Commands + +Each command represents a template. + +| Command | Function | +|--------------------------|------------------------------| +| `aspire-starter` | Aspire Starter App | +| `aspire` | Aspire Empty App | +| `aspire-apphost` | Aspire App Host | +| `aspire-servicedefaults` | Aspire Service Defaults | +| `aspire-mstest` | Aspire Test Project (MSTest) | +| `aspire-nunit` | Aspire Test Project (NUnit) | +| `aspire-xunit` | Aspire Test Project (xUnit) | + +## Examples + +Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. + +```Command +aspire new aspire-starter +``` + +Create an AppHost project named `aspireapp` from the **9.3.1** templates and place the output in a folder named `aspire1`. + +```Command +aspire new aspire-apphost --version 9.3.1 --name aspireapp1 --output ./aspire1 +``` diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 1c99d99db4..01052c23b6 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -1,9 +1,9 @@ --- title: aspire command description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. -ms.date: 06/26/2025 +ms.date: 07/11/2025 --- -# dotnet command +# aspire command **This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions @@ -27,19 +27,13 @@ The `aspire` command provides commands for working with Aspire projects. For exa The following options are available when `aspire` is used by itself, without specifying a command. For example, `aspire --version`. -- **`-?, -h, --help`** - - [!INCLUDE [option-help](includes/option-help.md)] +- [!INCLUDE [option-help](includes/option-help.md)] - [!INCLUDE [option-version](includes/option-version.md)] -- **`-d, --debug`** - - Enable debug logging to the console, which prints out detailed information about what .NET Aspire CLI is doing when a command is run. +- [!INCLUDE [option-debug](includes/option-debug.md)] -- **`--wait-for-debugger`** - - Wait for a debugger to attach before running a command. +- [!INCLUDE [option-wait](includes/option-wait.md)] ## Commands @@ -54,20 +48,14 @@ The following options are available when `aspire` is used by itself, without spe ## Examples -Create an Aspire solution from the template: +- Create an Aspire solution from the template: -```Command -aspire new aspire-starter -``` - -Run an Aspire app host project: - -```Command -aspire run -``` + ```Command + aspire new aspire-starter + ``` -## See also +- Run an Aspire AppHost project: -- [Environment variables used by .NET SDK, .NET CLI, and .NET runtime](dotnet-environment-variables.md) -- [Runtime Configuration Files](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md) -- [.NET runtime configuration settings](../runtime-config/index.md) \ No newline at end of file + ```Command + aspire run + ``` diff --git a/docs/cli-reference/includes/option-debug.md b/docs/cli-reference/includes/option-debug.md new file mode 100644 index 0000000000..5651de0b59 --- /dev/null +++ b/docs/cli-reference/includes/option-debug.md @@ -0,0 +1,9 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +ms.topic: include +--- +**`-d, --debug`** + + Enable debug logging to the console, which prints out detailed information about what .NET Aspire CLI is doing when a command is run. diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md index 0e1797a911..ee832b0071 100644 --- a/docs/cli-reference/includes/option-help.md +++ b/docs/cli-reference/includes/option-help.md @@ -1,7 +1,9 @@ --- title: aspire command description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. -ms.date: 06/26/2025 +ms.date: 07/11/2025 ms.topic: include --- -Printaaas out help and usage documentation for the available commands and options. +**`-?, -h, --help`** + + Prints out help and usage documentation for the available commands and options. diff --git a/docs/cli-reference/includes/option-version.md b/docs/cli-reference/includes/option-version.md index 8ea30073ef..cc1e65b6ad 100644 --- a/docs/cli-reference/includes/option-version.md +++ b/docs/cli-reference/includes/option-version.md @@ -1,9 +1,9 @@ --- title: aspire command description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. -ms.date: 06/26/2025 +ms.date: 07/11/2025 ms.topic: include --- -**`--versiona`** +**`--version`** - Prints the version of the .NET Aspire CLI tool. \ No newline at end of file + Prints the version of the .NET Aspire CLI tool. diff --git a/docs/cli-reference/includes/option-wait.md b/docs/cli-reference/includes/option-wait.md new file mode 100644 index 0000000000..f1a9b85482 --- /dev/null +++ b/docs/cli-reference/includes/option-wait.md @@ -0,0 +1,9 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +ms.topic: include +--- +**`--wait-for-debugger`** + + Wait for a debugger to attach before running a command. diff --git a/docs/toc.yml b/docs/toc.yml index 846f2aaf99..4607b027ae 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -119,6 +119,8 @@ items: items: - name: aspire href: cli-reference/aspire.md + - name: aspire new + href: cli-reference/aspire-new.md - name: Testing items: From 8f0d6d387d111aa082a8cc8a8dad070b895012ff Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 18:24:21 -0700 Subject: [PATCH 12/40] Minor updates to overview --- docs/cli/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 1edc339c96..cc9be04e80 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -27,7 +27,7 @@ The following table describes the basic commands provided by Aspire: | [`aspire add`](#add-integrations) | Stable | Add an integration to the Aspire project. | | [`aspire new`](#create-projects) | Stable | Create an Aspire sample project from a template. | | [`aspire run`](#run-the-apphost-project) | Stable | Run an Aspire apphost in development mode. | -| [`aspire exec`](#run-commands-in-resource-context-preview) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire exec`](#run-commands-in-resource-context-preview) | Preview | Similar to the `aspire run` command, but runs commands in the context of a resource. | | [`aspire deploy`](#deploy-aspire-applications-preview) | Preview | Deploys the artifacts created by `aspire publish`. | | [`aspire publish`](#publish-aspire-applications-preview) | Preview | Generates deployment artifacts for an Aspire apphost project. | @@ -50,9 +50,9 @@ While command line parameters can be used to automate the creation of an Aspire ## Run the apphost project -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal dashboard is also visible. +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal-based version dashboard is also visible. -When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following stesp: +When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following steps: - Installs or verifies that Aspires local hosting certificates are installed and trusted. - Builds the apphost project. From f5cc9d87076b6097eacaeece4082f784296eae27 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 18:24:30 -0700 Subject: [PATCH 13/40] More includes --- docs/cli-reference/includes/option-debug.md | 2 +- docs/cli-reference/includes/option-help.md | 2 +- docs/cli-reference/includes/option-project.md | 9 ++++++++ .../project-search-logic-description.md | 22 +++++++++++++++++++ 4 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 docs/cli-reference/includes/option-project.md create mode 100644 docs/cli-reference/includes/project-search-logic-description.md diff --git a/docs/cli-reference/includes/option-debug.md b/docs/cli-reference/includes/option-debug.md index 5651de0b59..d85a138475 100644 --- a/docs/cli-reference/includes/option-debug.md +++ b/docs/cli-reference/includes/option-debug.md @@ -6,4 +6,4 @@ ms.topic: include --- **`-d, --debug`** - Enable debug logging to the console, which prints out detailed information about what .NET Aspire CLI is doing when a command is run. + Enable debug logging to the console, which prints detailed information about what .NET Aspire CLI is doing when a command is run. diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md index ee832b0071..c02cb0e864 100644 --- a/docs/cli-reference/includes/option-help.md +++ b/docs/cli-reference/includes/option-help.md @@ -6,4 +6,4 @@ ms.topic: include --- **`-?, -h, --help`** - Prints out help and usage documentation for the available commands and options. + Prints help and usage documentation for the available commands and options. diff --git a/docs/cli-reference/includes/option-project.md b/docs/cli-reference/includes/option-project.md new file mode 100644 index 0000000000..e5984043b0 --- /dev/null +++ b/docs/cli-reference/includes/option-project.md @@ -0,0 +1,9 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +ms.topic: include +--- +**`--project`** + + The path to the Aspire apphost project file. diff --git a/docs/cli-reference/includes/project-search-logic-description.md b/docs/cli-reference/includes/project-search-logic-description.md new file mode 100644 index 0000000000..cfa98f11a4 --- /dev/null +++ b/docs/cli-reference/includes/project-search-logic-description.md @@ -0,0 +1,22 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +ms.topic: include +--- + +The Aspire CLI uses the following logic, in order, to determine which apphost project to process: + +- The `--project` option. + + This option specifies the path to a project to process. + +- The `.aspire/settings.json` config file. + + If the config file path exists in the current directory, it's used. If not, the CLI walks up the directory structure looking for the config file. If it finds a config file, it reads the `appHostPath` setting value as the project to process. + +- Searches the current directory and subdirectories. + + Starting in the current directory, the CLI gathers all apphost projects from that directory and below. If a single project is discovered, it's automatically selected. If mutliple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. + + Once a project selected, either automatically or manually, the path to the project is stored in the `.aspire/settings.json` config file. From f29b8ee0595b2237a34318225a0f8cda7dad8cf3 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 18:24:38 -0700 Subject: [PATCH 14/40] More commands --- docs/cli-reference/aspire-add.md | 68 +++++++++++++++++++++++ docs/cli-reference/aspire-exec.md | 58 +++++++++++++++++++ docs/cli-reference/aspire-new.md | 33 +++++------ docs/cli-reference/aspire-run.md | 92 +++++++++++++++++++++++++++++++ docs/cli-reference/aspire.md | 2 +- docs/toc.yml | 6 ++ 6 files changed, 238 insertions(+), 21 deletions(-) create mode 100644 docs/cli-reference/aspire-add.md create mode 100644 docs/cli-reference/aspire-exec.md create mode 100644 docs/cli-reference/aspire-run.md diff --git a/docs/cli-reference/aspire-add.md b/docs/cli-reference/aspire-add.md new file mode 100644 index 0000000000..16c80f0313 --- /dev/null +++ b/docs/cli-reference/aspire-add.md @@ -0,0 +1,68 @@ +--- +title: aspire add command +description: Learn about the aspire add command and its usage. This command adds an integration package to an Aspire apphost project. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire add` - Add an integration to the Aspire project. + +## Synopsis + +```dotnetcli +aspire add [] [options] +``` + +## Description + +The `aspire add` command searches NuGet for an integration package and adds it to the apphost project. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +## Arguments + +The following arguments are available: + +- **`integration`** + + The name of the integration to add (for example: redis, postgres). + + If a partial name or invalid name is provided, the CLI searches NuGet for approximate matches and prints them in the terminal for the user to select. If no results are found, all packages are listed. + +## Options + +The following options are available: + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-v, --version`** + + The version of the integration to add. + +- **`-s, --source`** + + The NuGet source to use for the integration. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Finds an apphost project and lists all Aspire integration packages from NuGet: + + ```Command + aspire add + ``` + +- Finds an apphost project and adds the **kafka** (Aspire.Hosting.Kafka) integration package: + + ```Command + aspire add kafka --version 9.3.2 + ``` diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md new file mode 100644 index 0000000000..d9358c2709 --- /dev/null +++ b/docs/cli-reference/aspire-exec.md @@ -0,0 +1,58 @@ +--- +title: aspire exec command +description: Learn about the aspire exec command and its usage. This command builds and runs an Aspire apphost project, then sends commands to a resource. +ms.date: 07/11/2025 +--- +# aspire exec command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire exec` - Run an Aspire app host to execute a command against the resource. + +## Synopsis + +```dotnetcli +aspire exec [options] [[--] ...]] +``` + +## Description + +The `aspire exec` command runs an apphost project and sends the provided commands to one of the resources. + +You must specify either the `--resource` or the `--start-resource` option, and you must provide parameters with the `--` option. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire exec from arguments for the resource. All arguments after this delimiter are passed to the resource. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-r, --resource`** + + The name of the target resource to execute the command against. + +- **`-s, --start-resource`** + + The name of the target resource to start and execute the command against. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Builds and runs the apphost project, then sends the command `migrate` to the `database1` resource: + + ```Command + aspire exec --resource database1 -- migrate + ``` diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md index 7ec7cc561e..389f3d859c 100644 --- a/docs/cli-reference/aspire-new.md +++ b/docs/cli-reference/aspire-new.md @@ -1,6 +1,6 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +title: aspire new command +description: Learn about the aspire new command and its usage. This command creates new Aspire projects or solutions. ms.date: 07/11/2025 --- # aspire new command @@ -9,17 +9,10 @@ ms.date: 07/11/2025 ## Name -`aspire new` - Create a new Aspire project, app, or solution. - -Supports: - -- ✔️ Interactive -- ✔️ Non-interactive +`aspire new` - Create a new Aspire project or solution. ## Synopsis -Create a new Aspire project: - ```dotnetcli aspire new [command] [options] ``` @@ -62,24 +55,24 @@ Each command represents a template. | Command | Function | |--------------------------|------------------------------| -| `aspire-starter` | Aspire Starter App | | `aspire` | Aspire Empty App | | `aspire-apphost` | Aspire App Host | -| `aspire-servicedefaults` | Aspire Service Defaults | | `aspire-mstest` | Aspire Test Project (MSTest) | | `aspire-nunit` | Aspire Test Project (NUnit) | +| `aspire-servicedefaults` | Aspire Service Defaults | +| `aspire-starter` | Aspire Starter App | | `aspire-xunit` | Aspire Test Project (xUnit) | ## Examples -Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. +- Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. -```Command -aspire new aspire-starter -``` + ```Command + aspire new aspire-starter + ``` -Create an AppHost project named `aspireapp` from the **9.3.1** templates and place the output in a folder named `aspire1`. +- Create an AppHost project named `aspireapp` from the **9.3.1** templates and place the output in a folder named `aspire1`. -```Command -aspire new aspire-apphost --version 9.3.1 --name aspireapp1 --output ./aspire1 -``` + ```Command + aspire new aspire-apphost --version 9.3.1 --name aspireapp1 --output ./aspire1 + ``` diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md new file mode 100644 index 0000000000..8681d51b25 --- /dev/null +++ b/docs/cli-reference/aspire-run.md @@ -0,0 +1,92 @@ +--- +title: aspire run command +description: Learn about the aspire run command and its usage. This command runs an Aspire app host. +ms.date: 07/11/2025 +--- +# aspire run command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire run` - Run an Aspire app host in development mode. + +## Synopsis + +```dotnetcli +aspire run [options] [[--] ...]] +``` + +## Description + +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal-based version dashboard is also visible. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an apphost project: + +- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. +- Installs or verifies that Aspires local hosting certificates are installed and trusted. +- Builds the apphost project. +- Starts the apphost. +- Starts the dashboard. +- Displays a terminal-based dashboard. + + + +The following snippet is an example of the terminal dashboard: + +```Aspire CLI +Dashboard: +📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0b + +╭─────────────┬─────────┬─────────┬────────────────────────╮ +│ Resource │ Type │ State │ Endpoint(s) │ +├─────────────┼─────────┼─────────┼────────────────────────┤ +│ apiservice │ Project │ Running │ https://localhost:7422 │ +│ │ │ │ http://localhost:5327 │ +│ webfrontend │ Project │ Running │ https://localhost:7241 │ +│ │ │ │ http://localhost:5185 │ +╰─────────────┴─────────┴─────────┴────────────────────────╯ +Press CTRL-C to stop the apphost and exit. +``` + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire run from arguments for the apphost being run. All arguments after this delimiter are passed to the apphost run. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-w, --watch`** + + Start project resources in watch mode. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for apphost projects to build and run: + + ```Command + aspire run + ``` + +- Run a specific apphost project: + + ```Command + aspire run --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Run a specific apphost project with arguments: + + ```Command + aspire run --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 01052c23b6..4eac3e125f 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -21,7 +21,7 @@ aspire [command] [options] ## Description -The `aspire` command provides commands for working with Aspire projects. For example `aspire run` runs an Aspire AppHost project. +The `aspire` command provides commands for working with Aspire projects. For example, `aspire run` runs an Aspire AppHost project. ## Options diff --git a/docs/toc.yml b/docs/toc.yml index 4607b027ae..944f968e0b 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -119,8 +119,14 @@ items: items: - name: aspire href: cli-reference/aspire.md + - name: aspire add + href: cli-reference/aspire-add.md + - name: aspire exec + href: cli-reference/aspire-exec.md - name: aspire new href: cli-reference/aspire-new.md + - name: aspire run + href: cli-reference/aspire-run.md - name: Testing items: From 5dc1cf4b53410c1ea6d0bf3088835bf696d1fc9e Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 11 Jul 2025 18:34:51 -0700 Subject: [PATCH 15/40] Update new command --- docs/cli-reference/aspire-new.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md index 389f3d859c..b0dd4dc1ad 100644 --- a/docs/cli-reference/aspire-new.md +++ b/docs/cli-reference/aspire-new.md @@ -51,9 +51,9 @@ The following options are available: ## Commands -Each command represents a template. +Each command represents a template. Pass the `--help` parameter to the template command to print the options available to the template. -| Command | Function | +| Command | Template | |--------------------------|------------------------------| | `aspire` | Aspire Empty App | | `aspire-apphost` | Aspire App Host | From 85b5f5fe468fdb7ad5575e702afc59c3395ada54 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 14 Jul 2025 11:20:41 -0700 Subject: [PATCH 16/40] Update output based on 9.4 --- docs/cli-reference/aspire-run.md | 30 ++++++++++++------------------ docs/cli/overview.md | 28 +++++++++++----------------- 2 files changed, 23 insertions(+), 35 deletions(-) diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 8681d51b25..2aa839e2f0 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire run command -**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions ## Name @@ -19,7 +19,7 @@ aspire run [options] [[--] ...]] ## Description -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal-based version dashboard is also visible. +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and prints a list of endpoints. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] @@ -30,25 +30,19 @@ The command performs the following steps to run an apphost project: - Builds the apphost project. - Starts the apphost. - Starts the dashboard. -- Displays a terminal-based dashboard. - - -The following snippet is an example of the terminal dashboard: +The following snippet is an example of the output displayed by the `aspire run` command: ```Aspire CLI -Dashboard: -📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0b - -╭─────────────┬─────────┬─────────┬────────────────────────╮ -│ Resource │ Type │ State │ Endpoint(s) │ -├─────────────┼─────────┼─────────┼────────────────────────┤ -│ apiservice │ Project │ Running │ https://localhost:7422 │ -│ │ │ │ http://localhost:5327 │ -│ webfrontend │ Project │ Running │ https://localhost:7241 │ -│ │ │ │ http://localhost:5185 │ -╰─────────────┴─────────┴─────────┴────────────────────────╯ -Press CTRL-C to stop the apphost and exit. +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + https://literate-eureka-55x5r74pwxv2vx7p-17178.app.github.dev/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log + +Endpoints: webfrontend has endpoint https://localhost:7294 + webfrontend has endpoint http://localhost:5131 + apiservice has endpoint https://localhost:7531 + apiservice has endpoint http://localhost:5573 ``` ## Options diff --git a/docs/cli/overview.md b/docs/cli/overview.md index cc9be04e80..d550cecc3c 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -50,7 +50,7 @@ While command line parameters can be used to automate the creation of an Aspire ## Run the apphost project -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal-based version dashboard is also visible. +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and prints a list of endpoints. When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following steps: @@ -58,25 +58,19 @@ When `aspire run` starts, it searches the current directory for an apphost. If a - Builds the apphost project. - Starts the apphost. - Starts the dashboard. -- Displays a terminal-based dashboard. - - -The following snippet is an example of the terminal dashboard: +The following snippet is an example of the output displayed by the `aspire run` command: ```Aspire CLI -Dashboard: -📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0b - -╭─────────────┬─────────┬─────────┬────────────────────────╮ -│ Resource │ Type │ State │ Endpoint(s) │ -├─────────────┼─────────┼─────────┼────────────────────────┤ -│ apiservice │ Project │ Running │ https://localhost:7422 │ -│ │ │ │ http://localhost:5327 │ -│ webfrontend │ Project │ Running │ https://localhost:7241 │ -│ │ │ │ http://localhost:5185 │ -╰─────────────┴─────────┴─────────┴────────────────────────╯ -Press CTRL-C to stop the apphost and exit. +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + https://literate-eureka-55x5r74pwxv2vx7p-17178.app.github.dev/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log + +Endpoints: webfrontend has endpoint https://localhost:7294 + webfrontend has endpoint http://localhost:5131 + apiservice has endpoint https://localhost:7531 + apiservice has endpoint http://localhost:5573 ``` ## Add integrations From 893337c9683ad93cbfd2ae0146f927a56a165df2 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 14 Jul 2025 11:25:54 -0700 Subject: [PATCH 17/40] Target 9.4 --- docs/cli-reference/aspire-add.md | 2 +- docs/cli-reference/aspire-exec.md | 4 ++-- docs/cli-reference/aspire-new.md | 2 +- docs/cli-reference/aspire-run.md | 4 ++-- docs/cli-reference/aspire.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/cli-reference/aspire-add.md b/docs/cli-reference/aspire-add.md index 16c80f0313..7c2b049b82 100644 --- a/docs/cli-reference/aspire-add.md +++ b/docs/cli-reference/aspire-add.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire add command -**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions ## Name diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index d9358c2709..4f21f1e319 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire exec command -**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. ## Name @@ -14,7 +14,7 @@ ms.date: 07/11/2025 ## Synopsis ```dotnetcli -aspire exec [options] [[--] ...]] +aspire exec [options] [[--] ...] ``` ## Description diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md index b0dd4dc1ad..b2c99396b5 100644 --- a/docs/cli-reference/aspire-new.md +++ b/docs/cli-reference/aspire-new.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire new command -**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. ## Name diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 2aa839e2f0..ab65d0a296 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire run command -**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. ## Name @@ -14,7 +14,7 @@ ms.date: 07/11/2025 ## Synopsis ```dotnetcli -aspire run [options] [[--] ...]] +aspire run [options] [[--] ...] ``` ## Description diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 4eac3e125f..14b1ffd9d6 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 --- # aspire command -**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. ## Name From e0ff977c16edee81ed5c7bdc51cd00ad9e1042b7 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 10:19:08 -0700 Subject: [PATCH 18/40] Table updates --- docs/cli-reference/aspire.md | 9 ++++++++- docs/cli/overview.md | 35 ++++++++++++++--------------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 14b1ffd9d6..5235d87e77 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -42,10 +42,17 @@ The following options are available when `aspire` is used by itself, without spe | [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | | [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | | [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | -| [`aspire exec`](aspire-exec.md) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | | [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | | [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | + + ## Examples - Create an Aspire solution from the template: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index d550cecc3c..66eb0619dc 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -16,30 +16,13 @@ The Aspire CLI (`aspire` command) is a cross-platform tool that provides command The Aspire CLI is an interactive-first experience. -- [Install .NET Aspire CLI](install.md) - -## Commands - -The following table describes the basic commands provided by Aspire: - -| Command | Status | Function | -|------------------------------------------------------------|---------|---------------------------------------------------------------------------| -| [`aspire add`](#add-integrations) | Stable | Add an integration to the Aspire project. | -| [`aspire new`](#create-projects) | Stable | Create an Aspire sample project from a template. | -| [`aspire run`](#run-the-apphost-project) | Stable | Run an Aspire apphost in development mode. | -| [`aspire exec`](#run-commands-in-resource-context-preview) | Preview | Similar to the `aspire run` command, but runs commands in the context of a resource. | -| [`aspire deploy`](#deploy-aspire-applications-preview) | Preview | Deploys the artifacts created by `aspire publish`. | -| [`aspire publish`](#publish-aspire-applications-preview) | Preview | Generates deployment artifacts for an Aspire apphost project. | - - +- [Install .NET Aspire CLI.](install.md) +- [`aspire` command reference.](../cli-reference/aspire.md) ## Create projects +[_Command reference: `aspire new`_](../cli-reference/aspire-new.md) + The `aspire new` command is an interactive-first CLI experience, and is used to create one or more Aspire projects. As part of creating a project, Azure CLI ensures that the latest Aspire project templates are installed into the `dotnet` system. @@ -50,6 +33,8 @@ While command line parameters can be used to automate the creation of an Aspire ## Run the apphost project +[_Command reference: `aspire run`_](../cli-reference/aspire-run.md) + The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and prints a list of endpoints. When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following steps: @@ -75,16 +60,22 @@ Endpoints: webfrontend has endpoint https://localhost:7294 ## Add integrations +[_Command reference: `aspire add`_](../cli-reference/aspire-add.md) + The `aspire add` command is an easy way to add official integration packages to your apphost. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. ## Publish Aspire applications (preview) +[_Command reference: `aspire publish`_](../cli-reference/aspire-publish.md) + The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. ## Deploy Aspire applications (preview) +[_Command reference: `aspire deploy`_](../cli-reference/aspire-deploy.md) + The `aspire deploy` command is similar to `aspire publish`, except that in addition to serializing resources, it also deploys resources that have registered a `DeployingCallbackAnnotation` annotation. > [!TIP] @@ -92,4 +83,6 @@ The `aspire deploy` command is similar to `aspire publish`, except that in addit ## Run commands in resource context (preview) +[_Command reference: `aspire exec`_](../cli-reference/aspire-exec.md) + The `aspire exec` command runs commands in the context of a specific Aspire resource, inheriting that resource's configuration including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run `aspire exec --resource api -- dotnet ef migrations add Init` to run Entity Framework commands with the proper database connection strings automatically configured. From dc0ddc20a8215a0c3d7c78e79ff49807cb0485a8 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 12:01:27 -0700 Subject: [PATCH 19/40] Feedback --- docs/cli-reference/aspire-run.md | 2 +- docs/cli/overview.md | 18 +++++++++++++----- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index ab65d0a296..29db238989 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -28,7 +28,7 @@ The command performs the following steps to run an apphost project: - Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. - Installs or verifies that Aspires local hosting certificates are installed and trusted. - Builds the apphost project. -- Starts the apphost. +- Starts the apphost and any services defined in the apphost. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 66eb0619dc..b890b22e84 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -31,17 +31,17 @@ Use the `aspire new` command to create an Aspire project from a list of template While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. -## Run the apphost project +## Start the apphost [_Command reference: `aspire run`_](../cli-reference/aspire-run.md) -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and prints a list of endpoints. +The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds and starts services defined by the apphost, launches the web dashboard, and prints a list of endpoints. When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following steps: - Installs or verifies that Aspires local hosting certificates are installed and trusted. - Builds the apphost project. -- Starts the apphost. +- Starts the apphost and any services defined in the apphost. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: @@ -70,13 +70,21 @@ The `aspire add` command is an easy way to add official integration packages to [_Command reference: `aspire publish`_](../cli-reference/aspire-publish.md) -The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. +The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. + +Some integrations automatically register a `PublishingCallbackAnnotation` for you, for example: + +- generates Bicep assets. +- generates docker-compose yaml. +- generates Kubernetes Helm charts. ## Deploy Aspire applications (preview) [_Command reference: `aspire deploy`_](../cli-reference/aspire-deploy.md) -The `aspire deploy` command is similar to `aspire publish`, except that in addition to serializing resources, it also deploys resources that have registered a `DeployingCallbackAnnotation` annotation. +The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations, it invokes resource's `DeployingCallbackAnnotation` annotations, in the order they're declared. + +As of Aspire 9.4, Aspire doesn't include any default deployment annotations for its resources, you must use the `DeployingCallbackAnnotation` to build your own. > [!TIP] > Consider this a good way to deploy your Aspire solution to a staging area for testing. From e7ff076c83fcb422b8ab591e4e9258e8958612b5 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 19:51:31 -0700 Subject: [PATCH 20/40] minor changes to overview --- docs/cli/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli/overview.md b/docs/cli/overview.md index b890b22e84..1aa5214422 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -70,7 +70,7 @@ The `aspire add` command is an easy way to add official integration packages to [_Command reference: `aspire publish`_](../cli-reference/aspire-publish.md) -The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. +The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered resource annotations, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. Some integrations automatically register a `PublishingCallbackAnnotation` for you, for example: @@ -82,7 +82,7 @@ Some integrations automatically register a `PublishingCallbackAnnotation` for yo [_Command reference: `aspire deploy`_](../cli-reference/aspire-deploy.md) -The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations, it invokes resource's `DeployingCallbackAnnotation` annotations, in the order they're declared. +The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. As of Aspire 9.4, Aspire doesn't include any default deployment annotations for its resources, you must use the `DeployingCallbackAnnotation` to build your own. From 7391b5e177eccdfc3f8a6705407b94ef33668543 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 19:51:43 -0700 Subject: [PATCH 21/40] Add remaining commands --- docs/cli-reference/aspire-config-delete.md | 45 +++++++++++++ docs/cli-reference/aspire-config-get.md | 45 +++++++++++++ docs/cli-reference/aspire-config-list.md | 32 +++++++++ docs/cli-reference/aspire-config-set.md | 44 ++++++++++++ docs/cli-reference/aspire-config.md | 43 ++++++++++++ docs/cli-reference/aspire-deploy.md | 75 +++++++++++++++++++++ docs/cli-reference/aspire-publish.md | 74 ++++++++++++++++++++ docs/cli-reference/aspire.md | 2 + docs/cli-reference/includes/mode-preview.md | 7 ++ docs/toc.yml | 16 +++++ 10 files changed, 383 insertions(+) create mode 100644 docs/cli-reference/aspire-config-delete.md create mode 100644 docs/cli-reference/aspire-config-get.md create mode 100644 docs/cli-reference/aspire-config-list.md create mode 100644 docs/cli-reference/aspire-config-set.md create mode 100644 docs/cli-reference/aspire-config.md create mode 100644 docs/cli-reference/aspire-deploy.md create mode 100644 docs/cli-reference/aspire-publish.md create mode 100644 docs/cli-reference/includes/mode-preview.md diff --git a/docs/cli-reference/aspire-config-delete.md b/docs/cli-reference/aspire-config-delete.md new file mode 100644 index 0000000000..0fda17e8e9 --- /dev/null +++ b/docs/cli-reference/aspire-config-delete.md @@ -0,0 +1,45 @@ +--- +title: aspire config delete command +description: Learn about the aspire config delete command and its usage. This command deletes an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config delete` - Delete a configuration value. + +## Synopsis + +```dotnetcli +aspire config delete [options] +``` + +## Description + +The `aspire config delete` command delete's a config value by key name. + +The command returns the following exit codes: + +- `0`—The command succeeded. +- `1`—The supplied key doesn't exist in the config file, or the config file is missing. + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to delete. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-get.md b/docs/cli-reference/aspire-config-get.md new file mode 100644 index 0000000000..79794c2c05 --- /dev/null +++ b/docs/cli-reference/aspire-config-get.md @@ -0,0 +1,45 @@ +--- +title: aspire config get command +description: Learn about the aspire config get command and its usage. This command gets an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config get` - Get a configuration value. + +## Synopsis + +```dotnetcli +aspire config get [options] +``` + +## Description + +The `aspire config get` command retrieves a config value by key name. + +The command returns the following exit codes: + +- `0`—The command succeeded. +- `10`—The supplied key doesn't exist in the config file, or the config file is missing. + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to retrieve. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-list.md b/docs/cli-reference/aspire-config-list.md new file mode 100644 index 0000000000..900e0da06c --- /dev/null +++ b/docs/cli-reference/aspire-config-list.md @@ -0,0 +1,32 @@ +--- +title: aspire config list command +description: Learn about the aspire config list command and its usage. This command lists all Aspire CLI config values. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config list` - List all configuration values. + +## Synopsis + +```dotnetcli +aspire config list [options] +``` + +## Description + +The `aspire config list` command delete's a config value by key name. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md new file mode 100644 index 0000000000..0905c03e30 --- /dev/null +++ b/docs/cli-reference/aspire-config-set.md @@ -0,0 +1,44 @@ +--- +title: aspire config set command +description: Learn about the aspire config set command and its usage. This command sets an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config set` - Set a configuration value. + +## Synopsis + +```dotnetcli +aspire config set [options] +``` + +## Description + +The `aspire config set` command sets a config value by key name. + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to set. + +- **`value`** + + The configuration value to set. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md new file mode 100644 index 0000000000..b105edf801 --- /dev/null +++ b/docs/cli-reference/aspire-config.md @@ -0,0 +1,43 @@ +--- +title: aspire config command +description: Learn about the aspire config command and its usage. This command driver is used to manage the Aspire CLI config settings. +ms.date: 07/11/2025 +--- +# aspire config command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config` - Manage configuration settings. + +## Synopsis + +```dotnetcli +aspire config [command] [options] +``` + +## Description + +The `aspire config` command driver provides commands to manage the Aspire CLI config settings. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Commands + +The following commands are available: + +| Command | Status | Function | +|----------------------------------------------------|--------|--------------------------------| +| [`aspire config get `](aspire-add.md) | Stable | Get a configuration value. | +| [`aspire config set `](aspire-new.md) | Stable | Set a configuration value. | +| [`aspire config list`](aspire-run.md) | Stable | List all configuration values. | +| [`aspire config delete `](aspire-exec.md) | Stable | Delete a configuration value. | diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md new file mode 100644 index 0000000000..a5039a4f13 --- /dev/null +++ b/docs/cli-reference/aspire-deploy.md @@ -0,0 +1,75 @@ +--- +title: aspire deploy command +description: Learn about the aspire deploy command and its usage. This command first runs publishing mode, then invokes resource deployments declared by the app host. +ms.date: 07/11/2025 +--- +# aspire deploy command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire deploy` - Deploy an Aspire app host project to its supported deployment targets. + +[!INCLUDE [mode-preview](includes/mode-preview.md)] + +## Synopsis + +```dotnetcli +aspire deploy [options] [[--] ...] +``` + +## Description + +The `aspire deploy` command is similar to [`aspire publish`](./aspire-publish.md). After Aspire has invoked the publishing annotations, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an apphost project: + +- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. +- Installs or verifies that Aspires local hosting certificates are installed and trusted. +- Builds the apphost project. +- Starts the apphost in publish mode. +- Invokes all resource annotations. +- Invokes all `DeployingCallbackAnnotation` resource annotations. + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire publish from arguments for the apphost. All arguments after this delimiter are passed to the apphost. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-o, --output-path`** + + The output path for deployment artifacts. Defaults the a folder named _deploy_ in the current directory. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for apphost projects to build, publish, and deploy: + + ```Command + aspire deploy + ``` + +- Publish and deploy a specific apphost project: + + ```Command + aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Publish and deploy a specific apphost project with arguments: + + ```Command + aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md new file mode 100644 index 0000000000..e367e786f7 --- /dev/null +++ b/docs/cli-reference/aspire-publish.md @@ -0,0 +1,74 @@ +--- +title: aspire publish command +description: Learn about the aspire publish command and its usage. This command invokes resource publishers declared by the app host to serialize resources to disk. +ms.date: 07/11/2025 +--- +# aspire publish command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire publish` - Generates deployment artifacts for an Aspire app host project. + +[!INCLUDE [mode-preview](includes/mode-preview.md)] + +## Synopsis + +```dotnetcli +aspire publish [options] [[--] ...] +``` + +## Description + +The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an apphost project: + +- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. +- Installs or verifies that Aspires local hosting certificates are installed and trusted. +- Builds the apphost project. +- Starts the apphost in publish mode. +- Invokes all annotations for resources. + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire publish from arguments for the apphost. All arguments after this delimiter are passed to the apphost. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-o, --output-path`** + + The output path for the generated artifacts. Defaults the current directory. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for apphost projects to build and publish: + + ```Command + aspire publish + ``` + +- Publish a specific apphost project: + + ```Command + aspire publish --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Publish a specific apphost project with arguments: + + ```Command + aspire publish --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 5235d87e77..fe2ca34e84 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -37,6 +37,8 @@ The following options are available when `aspire` is used by itself, without spe ## Commands +The following commands are available: + | Command | Status | Function | |---------------------------------------|---------|--------------------------------------------------------------------------| | [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | diff --git a/docs/cli-reference/includes/mode-preview.md b/docs/cli-reference/includes/mode-preview.md new file mode 100644 index 0000000000..d220c730c7 --- /dev/null +++ b/docs/cli-reference/includes/mode-preview.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- + +> [!IMPORTANT] +> This command is in preview and subject to change. diff --git a/docs/toc.yml b/docs/toc.yml index 944f968e0b..ef8546bdc5 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -121,10 +121,26 @@ items: href: cli-reference/aspire.md - name: aspire add href: cli-reference/aspire-add.md + - name: aspire deploy + href: cli-reference/aspire-deploy.md + - name: aspire config + items: + - name: aspire config [command] + href: cli-reference/aspire-config.md + - name: aspire config list + href: cli-reference/aspire-config-list.md + - name: aspire config get + href: cli-reference/aspire-config-get.md + - name: aspire config set + href: cli-reference/aspire-config-set.md + - name: aspire config delete + href: cli-reference/aspire-config-delete.md - name: aspire exec href: cli-reference/aspire-exec.md - name: aspire new href: cli-reference/aspire-new.md + - name: aspire publish + href: cli-reference/aspire-publish.md - name: aspire run href: cli-reference/aspire-run.md From d29fe543dc453f0f0d29b1e2539727bb027c5079 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 20:00:03 -0700 Subject: [PATCH 22/40] Fix headers --- docs/cli-reference/aspire-config-delete.md | 2 +- docs/cli-reference/aspire-config-get.md | 2 +- docs/cli-reference/aspire-config-list.md | 2 +- docs/cli-reference/aspire-config-set.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli-reference/aspire-config-delete.md b/docs/cli-reference/aspire-config-delete.md index 0fda17e8e9..e689589068 100644 --- a/docs/cli-reference/aspire-config-delete.md +++ b/docs/cli-reference/aspire-config-delete.md @@ -3,7 +3,7 @@ title: aspire config delete command description: Learn about the aspire config delete command and its usage. This command deletes an Aspire CLI config value by key name. ms.date: 07/11/2025 --- -# aspire add command +# aspire config delete command **This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions diff --git a/docs/cli-reference/aspire-config-get.md b/docs/cli-reference/aspire-config-get.md index 79794c2c05..25ca23a526 100644 --- a/docs/cli-reference/aspire-config-get.md +++ b/docs/cli-reference/aspire-config-get.md @@ -3,7 +3,7 @@ title: aspire config get command description: Learn about the aspire config get command and its usage. This command gets an Aspire CLI config value by key name. ms.date: 07/11/2025 --- -# aspire add command +# aspire config add command **This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions diff --git a/docs/cli-reference/aspire-config-list.md b/docs/cli-reference/aspire-config-list.md index 900e0da06c..cf414ae59a 100644 --- a/docs/cli-reference/aspire-config-list.md +++ b/docs/cli-reference/aspire-config-list.md @@ -3,7 +3,7 @@ title: aspire config list command description: Learn about the aspire config list command and its usage. This command lists all Aspire CLI config values. ms.date: 07/11/2025 --- -# aspire add command +# aspire config list command **This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md index 0905c03e30..3e7b5bf75f 100644 --- a/docs/cli-reference/aspire-config-set.md +++ b/docs/cli-reference/aspire-config-set.md @@ -3,7 +3,7 @@ title: aspire config set command description: Learn about the aspire config set command and its usage. This command sets an Aspire CLI config value by key name. ms.date: 07/11/2025 --- -# aspire add command +# aspire config set command **This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions From 70d4bfe6a6c03570d64d78e9edeed5c7c4d78814 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 20:01:17 -0700 Subject: [PATCH 23/40] fix table links --- docs/cli-reference/aspire-config.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md index b105edf801..53c8292a76 100644 --- a/docs/cli-reference/aspire-config.md +++ b/docs/cli-reference/aspire-config.md @@ -35,9 +35,9 @@ The following options are available: The following commands are available: -| Command | Status | Function | -|----------------------------------------------------|--------|--------------------------------| -| [`aspire config get `](aspire-add.md) | Stable | Get a configuration value. | -| [`aspire config set `](aspire-new.md) | Stable | Set a configuration value. | -| [`aspire config list`](aspire-run.md) | Stable | List all configuration values. | -| [`aspire config delete `](aspire-exec.md) | Stable | Delete a configuration value. | +| Command | Status | Function | +|-----------------------------------------------------------|--------|--------------------------------| +| [`aspire config list`](aspire-config-list.md) | Stable | List all configuration values. | +| [`aspire config get `](aspire-config-get.md) | Stable | Get a configuration value. | +| [`aspire config set `](aspire-config-set.md) | Stable | Set a configuration value. | +| [`aspire config delete `](aspire-config-delete.md) | Stable | Delete a configuration value. | From 1af5fb815b47c8041b7dc64ababe086b3e668741 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 16 Jul 2025 20:03:08 -0700 Subject: [PATCH 24/40] minor --- docs/cli-reference/aspire-publish.md | 2 +- docs/cli/overview.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index e367e786f7..d7c2ad379d 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -21,7 +21,7 @@ aspire publish [options] [[--] ...] ## Description -The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. +The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 1aa5214422..71de1259ff 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -70,7 +70,7 @@ The `aspire add` command is an easy way to add official integration packages to [_Command reference: `aspire publish`_](../cli-reference/aspire-publish.md) -The `aspire publish` command publishes resources, serializing resources to disk. When this command is run, Aspire invokes registered resource annotations, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. +The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire invokes registered resource annotations, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. Some integrations automatically register a `PublishingCallbackAnnotation` for you, for example: @@ -82,7 +82,7 @@ Some integrations automatically register a `PublishingCallbackAnnotation` for yo [_Command reference: `aspire deploy`_](../cli-reference/aspire-deploy.md) -The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. +The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations to serialize resources to disk, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. As of Aspire 9.4, Aspire doesn't include any default deployment annotations for its resources, you must use the `DeployingCallbackAnnotation` to build your own. From 9e38441a23048b6b222656103bd1e34581caf605 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 10:03:56 -0700 Subject: [PATCH 25/40] Minor --- docs/cli-reference/aspire-exec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 4f21f1e319..606b505203 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -19,7 +19,7 @@ aspire exec [options] [[--] ...] ## Description -The `aspire exec` command runs an apphost project and sends the provided commands to one of the resources. +The `aspire exec` command runs an apphost project and runs a command in the context of one of the resources. You must specify either the `--resource` or the `--start-resource` option, and you must provide parameters with the `--` option. From 1f73f7afe7141a8c65804a7ac140c30ded6e50f4 Mon Sep 17 00:00:00 2001 From: Ankit Jain Date: Thu, 17 Jul 2025 23:15:53 +0000 Subject: [PATCH 26/40] build-you-first-aspire-app, and setup-tooling: Add instructions to get cli --- docs/fundamentals/setup-tooling.md | 18 ++++++++++++++++++ .../get-started/build-your-first-aspire-app.md | 18 ++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index 7a722dbe0c..2ac25f3dec 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -259,6 +259,24 @@ Once you create a new .NET Aspire project, you run and debug the app, stepping t :::zone-end +## 🖥️ Aspire CLI + +🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. + +📦 To install: + +On Windows: + +```powershell +iex "& { $(irm https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.ps1) }" +``` + +On Linux, or macOS: + +```sh +curl -sSL https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.sh | bash +``` + ## See also - [Unable to install .NET Aspire workload](../troubleshooting/unable-to-install-workload.md) diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index 48a29a2a04..26d30e9720 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -221,6 +221,24 @@ The preceding code: For more information, see [Make HTTP requests with the `HttpClient`](/dotnet/fundamentals/networking/http/httpclient) class. +## 🖥️ Aspire CLI + +🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. + +📦 To install: + +On Windows: + +```powershell +iex "& { $(irm https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.ps1) }" +``` + +On Linux, or macOS: + +```sh +curl -sSL https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.sh | bash +``` + ## See also - [.NET Aspire integrations overview](../fundamentals/integrations-overview.md) From 18e613c2dbccd133288b313b59cb9de4d934b949 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 10:35:51 -0700 Subject: [PATCH 27/40] Update wording around aspire run --- docs/cli-reference/aspire-run.md | 10 +++++----- docs/cli/overview.md | 18 +++++++++--------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 29db238989..7767a09fcd 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -19,16 +19,16 @@ aspire run [options] [[--] ...] ## Description -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and prints a list of endpoints. +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] The command performs the following steps to run an apphost project: -- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. -- Installs or verifies that Aspires local hosting certificates are installed and trusted. -- Builds the apphost project. -- Starts the apphost and any services defined in the apphost. +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 71de1259ff..8c979faec5 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -1,6 +1,6 @@ --- title: .NET Aspire CLI Overview and Commands -description: Learn .NET Aspire CLI commands for creating projects, running an apphost, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +description: Learn .NET Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. ms.date: 06/26/2025 ms.topic: overview ms.custom: @@ -31,17 +31,17 @@ Use the `aspire new` command to create an Aspire project from a list of template While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. -## Start the apphost +## Start the app host [_Command reference: `aspire run`_](../cli-reference/aspire-run.md) -The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds and starts services defined by the apphost, launches the web dashboard, and prints a list of endpoints. +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. -When `aspire run` starts, it searches the current directory for an apphost. If an apphost isn't found, the sub directories are searched until an apphost is found. If no apphost is found, Aspire stops. Once an apphost is found, Aspire CLI takes the following steps: +When `aspire run` starts, it searches the current directory for an AppHost project. If a project isn't found, the sub directories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps: -- Installs or verifies that Aspires local hosting certificates are installed and trusted. -- Builds the apphost project. -- Starts the apphost and any services defined in the apphost. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: @@ -62,7 +62,7 @@ Endpoints: webfrontend has endpoint https://localhost:7294 [_Command reference: `aspire add`_](../cli-reference/aspire-add.md) -The `aspire add` command is an easy way to add official integration packages to your apphost. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. +The `aspire add` command is an easy way to add official integration packages to your AppHost project. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package, If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value. @@ -93,4 +93,4 @@ As of Aspire 9.4, Aspire doesn't include any default deployment annotations for [_Command reference: `aspire exec`_](../cli-reference/aspire-exec.md) -The `aspire exec` command runs commands in the context of a specific Aspire resource, inheriting that resource's configuration including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run `aspire exec --resource api -- dotnet ef migrations add Init` to run Entity Framework commands with the proper database connection strings automatically configured. +The `aspire exec` command runs a command in the context of a specific Aspire resource, inheriting that resource's configuration, including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run `aspire exec --resource api -- dotnet ef migrations add Init` to run Entity Framework commands with the proper database connection strings automatically configured. From e1905bc8f791d7466bfc8fd7892d9ab42c8c2b5e Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 11:23:32 -0700 Subject: [PATCH 28/40] Fix up AppHost vs app host --- docs/cli-reference/aspire-add.md | 8 ++++---- docs/cli-reference/aspire-deploy.md | 19 ++++++++++--------- docs/cli-reference/aspire-exec.md | 6 +++--- docs/cli-reference/aspire-publish.md | 19 ++++++++++--------- docs/cli-reference/aspire-run.md | 8 ++++---- docs/cli-reference/includes/option-project.md | 2 +- .../project-search-logic-description.md | 4 ++-- 7 files changed, 34 insertions(+), 32 deletions(-) diff --git a/docs/cli-reference/aspire-add.md b/docs/cli-reference/aspire-add.md index 7c2b049b82..28b2b1a142 100644 --- a/docs/cli-reference/aspire-add.md +++ b/docs/cli-reference/aspire-add.md @@ -1,6 +1,6 @@ --- title: aspire add command -description: Learn about the aspire add command and its usage. This command adds an integration package to an Aspire apphost project. +description: Learn about the aspire add command and its usage. This command adds an integration package to an Aspire AppHost project. ms.date: 07/11/2025 --- # aspire add command @@ -19,7 +19,7 @@ aspire add [] [options] ## Description -The `aspire add` command searches NuGet for an integration package and adds it to the apphost project. +The `aspire add` command searches NuGet for an integration package and adds it to the AppHost project. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] @@ -55,13 +55,13 @@ The following options are available: ## Examples -- Finds an apphost project and lists all Aspire integration packages from NuGet: +- Finds an AppHost project and lists all Aspire integration packages from NuGet: ```Command aspire add ``` -- Finds an apphost project and adds the **kafka** (Aspire.Hosting.Kafka) integration package: +- Finds an AppHost project and adds the **kafka** (Aspire.Hosting.Kafka) integration package: ```Command aspire add kafka --version 9.3.2 diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index a5039a4f13..1f61a803d7 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -25,12 +25,13 @@ The `aspire deploy` command is similar to [`aspire publish`](./aspire-publish.md [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] -The command performs the following steps to run an apphost project: +The command performs the following steps to run an AppHost project: -- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. -- Installs or verifies that Aspires local hosting certificates are installed and trusted. -- Builds the apphost project. -- Starts the apphost in publish mode. +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the app host in publish mode. - Invokes all resource annotations. - Invokes all `DeployingCallbackAnnotation` resource annotations. @@ -40,7 +41,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire publish from arguments for the apphost. All arguments after this delimiter are passed to the apphost. + Delimits arguments to aspire publish from arguments for the app host. All arguments after this delimiter are passed to the app host. - [!INCLUDE [option-project](includes/option-project.md)] @@ -56,19 +57,19 @@ The following options are available: ## Examples -- Search the current directory structure for apphost projects to build, publish, and deploy: +- Search the current directory structure for AppHost projects to build, publish, and deploy: ```Command aspire deploy ``` -- Publish and deploy a specific apphost project: +- Publish and deploy a specific AppHost project: ```Command aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' ``` -- Publish and deploy a specific apphost project with arguments: +- Publish and deploy a specific AppHost project with arguments: ```Command aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' -- -fast diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 606b505203..336b261be9 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -1,6 +1,6 @@ --- title: aspire exec command -description: Learn about the aspire exec command and its usage. This command builds and runs an Aspire apphost project, then sends commands to a resource. +description: Learn about the aspire exec command and its usage. This command builds and runs an Aspire AppHost project, then sends commands to a resource. ms.date: 07/11/2025 --- # aspire exec command @@ -19,7 +19,7 @@ aspire exec [options] [[--] ...] ## Description -The `aspire exec` command runs an apphost project and runs a command in the context of one of the resources. +The `aspire exec` command runs an AppHost project and runs a command in the context of one of the resources. You must specify either the `--resource` or the `--start-resource` option, and you must provide parameters with the `--` option. @@ -51,7 +51,7 @@ The following options are available: ## Examples -- Builds and runs the apphost project, then sends the command `migrate` to the `database1` resource: +- Builds and runs the AppHost project, then sends the command `migrate` to the `database1` resource: ```Command aspire exec --resource database1 -- migrate diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index d7c2ad379d..aaf4cc82f5 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -25,12 +25,13 @@ The `aspire publish` command publishes resources by serializing them to disk. Wh [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] -The command performs the following steps to run an apphost project: +The command performs the following steps to run an AppHost project: -- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory. -- Installs or verifies that Aspires local hosting certificates are installed and trusted. -- Builds the apphost project. -- Starts the apphost in publish mode. +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the app host in publish mode. - Invokes all annotations for resources. ## Options @@ -39,7 +40,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire publish from arguments for the apphost. All arguments after this delimiter are passed to the apphost. + Delimits arguments to aspire publish from arguments for the AppHost. All arguments after this delimiter are passed to the AppHost. - [!INCLUDE [option-project](includes/option-project.md)] @@ -55,19 +56,19 @@ The following options are available: ## Examples -- Search the current directory structure for apphost projects to build and publish: +- Search the current directory structure for AppHost projects to build and publish: ```Command aspire publish ``` -- Publish a specific apphost project: +- Publish a specific AppHost project: ```Command aspire publish --project './projects/apphost/orchestration.AppHost.csproj' ``` -- Publish a specific apphost project with arguments: +- Publish a specific AppHost project with arguments: ```Command aspire publish --project './projects/apphost/orchestration.AppHost.csproj' -- -fast diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 7767a09fcd..6f6863973e 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -51,7 +51,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire run from arguments for the apphost being run. All arguments after this delimiter are passed to the apphost run. + Delimits arguments to aspire run from arguments for the app host being run. All arguments after this delimiter are passed to the app host run. - [!INCLUDE [option-project](includes/option-project.md)] @@ -67,19 +67,19 @@ The following options are available: ## Examples -- Search the current directory structure for apphost projects to build and run: +- Search the current directory structure for AppHost projects to build and run: ```Command aspire run ``` -- Run a specific apphost project: +- Run a specific AppHost project: ```Command aspire run --project './projects/apphost/orchestration.AppHost.csproj' ``` -- Run a specific apphost project with arguments: +- Run a specific AppHost project with arguments: ```Command aspire run --project './projects/apphost/orchestration.AppHost.csproj' -- -fast diff --git a/docs/cli-reference/includes/option-project.md b/docs/cli-reference/includes/option-project.md index e5984043b0..111334abf6 100644 --- a/docs/cli-reference/includes/option-project.md +++ b/docs/cli-reference/includes/option-project.md @@ -6,4 +6,4 @@ ms.topic: include --- **`--project`** - The path to the Aspire apphost project file. + The path to the Aspire AppHost project file. diff --git a/docs/cli-reference/includes/project-search-logic-description.md b/docs/cli-reference/includes/project-search-logic-description.md index cfa98f11a4..8dbadebf9b 100644 --- a/docs/cli-reference/includes/project-search-logic-description.md +++ b/docs/cli-reference/includes/project-search-logic-description.md @@ -5,7 +5,7 @@ ms.date: 07/11/2025 ms.topic: include --- -The Aspire CLI uses the following logic, in order, to determine which apphost project to process: +The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: - The `--project` option. @@ -17,6 +17,6 @@ The Aspire CLI uses the following logic, in order, to determine which apphost pr - Searches the current directory and subdirectories. - Starting in the current directory, the CLI gathers all apphost projects from that directory and below. If a single project is discovered, it's automatically selected. If mutliple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. + Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it's automatically selected. If mutliple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. Once a project selected, either automatically or manually, the path to the project is stored in the `.aspire/settings.json` config file. From 5feabe3f64ad7e7e807b694d3f08937dfd393f47 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 11:24:44 -0700 Subject: [PATCH 29/40] adjust heading --- docs/cli/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 8c979faec5..dba03e19f2 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -19,7 +19,7 @@ The Aspire CLI is an interactive-first experience. - [Install .NET Aspire CLI.](install.md) - [`aspire` command reference.](../cli-reference/aspire.md) -## Create projects +## Use templates [_Command reference: `aspire new`_](../cli-reference/aspire-new.md) From 932bfca27c047027fc2b3e1902b23df83c332f21 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 14:08:05 -0700 Subject: [PATCH 30/40] Remove title/desc from include --- docs/cli-reference/includes/option-debug.md | 2 -- docs/cli-reference/includes/option-help.md | 2 -- docs/cli-reference/includes/option-project.md | 2 -- docs/cli-reference/includes/option-version.md | 2 -- docs/cli-reference/includes/option-wait.md | 2 -- docs/cli-reference/includes/project-search-logic-description.md | 2 -- 6 files changed, 12 deletions(-) diff --git a/docs/cli-reference/includes/option-debug.md b/docs/cli-reference/includes/option-debug.md index d85a138475..da55b77ef0 100644 --- a/docs/cli-reference/includes/option-debug.md +++ b/docs/cli-reference/includes/option-debug.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md index c02cb0e864..43cb668cda 100644 --- a/docs/cli-reference/includes/option-help.md +++ b/docs/cli-reference/includes/option-help.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- diff --git a/docs/cli-reference/includes/option-project.md b/docs/cli-reference/includes/option-project.md index 111334abf6..a078225fea 100644 --- a/docs/cli-reference/includes/option-project.md +++ b/docs/cli-reference/includes/option-project.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- diff --git a/docs/cli-reference/includes/option-version.md b/docs/cli-reference/includes/option-version.md index cc1e65b6ad..c78237c61e 100644 --- a/docs/cli-reference/includes/option-version.md +++ b/docs/cli-reference/includes/option-version.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- diff --git a/docs/cli-reference/includes/option-wait.md b/docs/cli-reference/includes/option-wait.md index f1a9b85482..2e8097aaf5 100644 --- a/docs/cli-reference/includes/option-wait.md +++ b/docs/cli-reference/includes/option-wait.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- diff --git a/docs/cli-reference/includes/project-search-logic-description.md b/docs/cli-reference/includes/project-search-logic-description.md index 8dbadebf9b..8b06f7cc2a 100644 --- a/docs/cli-reference/includes/project-search-logic-description.md +++ b/docs/cli-reference/includes/project-search-logic-description.md @@ -1,6 +1,4 @@ --- -title: aspire command -description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. ms.date: 07/11/2025 ms.topic: include --- From a8e7ab0e1115672c4869b88dbc537c3c41eabfbc Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 14:08:23 -0700 Subject: [PATCH 31/40] Update config docs for global --- docs/cli-reference/aspire-config-delete.md | 6 ++++++ docs/cli-reference/aspire-config-get.md | 6 +++++- docs/cli-reference/aspire-config-list.md | 6 +++++- docs/cli-reference/aspire-config-set.md | 6 ++++++ docs/cli-reference/aspire-config.md | 2 ++ .../includes/config-file-description.md | 14 ++++++++++++++ 6 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 docs/cli-reference/includes/config-file-description.md diff --git a/docs/cli-reference/aspire-config-delete.md b/docs/cli-reference/aspire-config-delete.md index e689589068..c25b2e7a55 100644 --- a/docs/cli-reference/aspire-config-delete.md +++ b/docs/cli-reference/aspire-config-delete.md @@ -21,6 +21,8 @@ aspire config delete [options] The `aspire config delete` command delete's a config value by key name. +[!INCLUDE [config-file-description](includes/config-file-description.md)] + The command returns the following exit codes: - `0`—The command succeeded. @@ -38,6 +40,10 @@ The following arguments are available: The following options are available: +- **`-g, --global`** + + Delete the configuration value from the global `$HOME/.aspire/settings.json` instead of the local settings file. + - [!INCLUDE [option-help](includes/option-help.md)] - [!INCLUDE [option-debug](includes/option-debug.md)] diff --git a/docs/cli-reference/aspire-config-get.md b/docs/cli-reference/aspire-config-get.md index 25ca23a526..d0406d39f2 100644 --- a/docs/cli-reference/aspire-config-get.md +++ b/docs/cli-reference/aspire-config-get.md @@ -3,7 +3,7 @@ title: aspire config get command description: Learn about the aspire config get command and its usage. This command gets an Aspire CLI config value by key name. ms.date: 07/11/2025 --- -# aspire config add command +# aspire config get command **This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions @@ -21,6 +21,10 @@ aspire config get [options] The `aspire config get` command retrieves a config value by key name. +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +If the config value doesn't exist in a local settings file, the config file is retrieved from the global settings file. + The command returns the following exit codes: - `0`—The command succeeded. diff --git a/docs/cli-reference/aspire-config-list.md b/docs/cli-reference/aspire-config-list.md index cf414ae59a..8af315a42a 100644 --- a/docs/cli-reference/aspire-config-list.md +++ b/docs/cli-reference/aspire-config-list.md @@ -19,7 +19,11 @@ aspire config list [options] ## Description -The `aspire config list` command delete's a config value by key name. +The `aspire config list` command lists all config value by key name. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +This command lists both the global and local settings. If a local setting overrides a global setting, only the local setting is displayed. ## Options diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md index 3e7b5bf75f..3c66ce0d20 100644 --- a/docs/cli-reference/aspire-config-set.md +++ b/docs/cli-reference/aspire-config-set.md @@ -21,6 +21,8 @@ aspire config set [options] The `aspire config set` command sets a config value by key name. +[!INCLUDE [config-file-description](includes/config-file-description.md)] + ## Arguments The following arguments are available: @@ -37,6 +39,10 @@ The following arguments are available: The following options are available: +- **`-g, --global`** + + Set the configuration value globally in `$HOME/.aspire/settings.json` instead of the local settings file. + - [!INCLUDE [option-help](includes/option-help.md)] - [!INCLUDE [option-debug](includes/option-debug.md)] diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md index 53c8292a76..331c0efcf9 100644 --- a/docs/cli-reference/aspire-config.md +++ b/docs/cli-reference/aspire-config.md @@ -21,6 +21,8 @@ aspire config [command] [options] The `aspire config` command driver provides commands to manage the Aspire CLI config settings. +[!INCLUDE [config-file-description](includes/config-file-description.md)] + ## Options The following options are available: diff --git a/docs/cli-reference/includes/config-file-description.md b/docs/cli-reference/includes/config-file-description.md new file mode 100644 index 0000000000..6c140adc2f --- /dev/null +++ b/docs/cli-reference/includes/config-file-description.md @@ -0,0 +1,14 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- + +Aspire supports a local and global settings file. Settings defined in a local settings file override those set in the global settings file. + +- **Local settings** + + A local settings file is stored at `.aspire/settings.json` under the current directory. + +- **Global settings** + + The global settings file is stored at `$HOME/.aspire/settings.json`. From 25d8347732b18bd03f5d4357e8a4d10c173e3442 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 14:08:29 -0700 Subject: [PATCH 32/40] feedback --- docs/cli-reference/aspire-deploy.md | 2 +- docs/cli-reference/aspire-run.md | 1 - docs/cli-reference/aspire.md | 18 +++++++++--------- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index 1f61a803d7..e9814386ad 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -47,7 +47,7 @@ The following options are available: - **`-o, --output-path`** - The output path for deployment artifacts. Defaults the a folder named _deploy_ in the current directory. + The output path for deployment artifacts. Defaults to a folder named _deploy_ in the current directory. - [!INCLUDE [option-help](includes/option-help.md)] diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 6f6863973e..427219398f 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -35,7 +35,6 @@ The following snippet is an example of the output displayed by the `aspire run` ```Aspire CLI Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 - https://literate-eureka-55x5r74pwxv2vx7p-17178.app.github.dev/login?t=17f974bf68e390b0d4548af8d7e38b65 Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index fe2ca34e84..5c6423fc50 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -39,18 +39,18 @@ The following options are available when `aspire` is used by itself, without spe The following commands are available: -| Command | Status | Function | -|---------------------------------------|---------|--------------------------------------------------------------------------| -| [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | -| [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | -| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | -| [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | -| [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | -| [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | +| Command | Status | Function | +|--------------------------------------------------|---------|--------------------------------------------------------------------------| +| [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | +| [`aspire config`](#configure-aspire-environment) | Stable | Configures the Aspire environment. | +| [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | +| [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | +| [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | +| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | From c91c6869025ca75c3a543c9277515b019ec38965 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 18 Jul 2025 14:07:26 -0700 Subject: [PATCH 33/40] Apply suggestions from code review Co-authored-by: David Pine Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/cli-reference/includes/option-version.md | 2 +- .../includes/project-search-logic-description.md | 2 +- docs/cli/overview.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/cli-reference/includes/option-version.md b/docs/cli-reference/includes/option-version.md index c78237c61e..6db6a6547f 100644 --- a/docs/cli-reference/includes/option-version.md +++ b/docs/cli-reference/includes/option-version.md @@ -4,4 +4,4 @@ ms.topic: include --- **`--version`** - Prints the version of the .NET Aspire CLI tool. + Prints the version of the Aspire CLI tool. diff --git a/docs/cli-reference/includes/project-search-logic-description.md b/docs/cli-reference/includes/project-search-logic-description.md index 8b06f7cc2a..1a1c49d51a 100644 --- a/docs/cli-reference/includes/project-search-logic-description.md +++ b/docs/cli-reference/includes/project-search-logic-description.md @@ -15,6 +15,6 @@ The Aspire CLI uses the following logic, in order, to determine which AppHost pr - Searches the current directory and subdirectories. - Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it's automatically selected. If mutliple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. + Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it's automatically selected. If multiple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. Once a project selected, either automatically or manually, the path to the project is stored in the `.aspire/settings.json` config file. diff --git a/docs/cli/overview.md b/docs/cli/overview.md index dba03e19f2..cc9903ac92 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -1,6 +1,6 @@ --- title: .NET Aspire CLI Overview and Commands -description: Learn .NET Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +description: Learn about the Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. ms.date: 06/26/2025 ms.topic: overview ms.custom: @@ -10,7 +10,7 @@ ms.custom: - ai-gen-description --- -# .NET Aspire CLI Overview +# Aspire CLI Overview The Aspire CLI (`aspire` command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish polyglot Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications. @@ -87,7 +87,7 @@ The `aspire deploy` command is similar to `aspire publish`. After Aspire has inv As of Aspire 9.4, Aspire doesn't include any default deployment annotations for its resources, you must use the `DeployingCallbackAnnotation` to build your own. > [!TIP] -> Consider this a good way to deploy your Aspire solution to a staging area for testing. +> Consider this a good way to deploy your Aspire solution to a staging or testing environment. ## Run commands in resource context (preview) From 87c95286691b6e225f20c7b08f90ec38284693e4 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 18 Jul 2025 14:18:38 -0700 Subject: [PATCH 34/40] minor --- docs/cli-reference/aspire.md | 2 +- docs/cli/overview.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 5c6423fc50..8ba9e7159c 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -42,7 +42,7 @@ The following commands are available: | Command | Status | Function | |--------------------------------------------------|---------|--------------------------------------------------------------------------| | [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | -| [`aspire config`](#configure-aspire-environment) | Stable | Configures the Aspire environment. | +| [`aspire config`](aspire-configure.md) | Stable | Configures the Aspire environment. | | [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | | [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | | [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | diff --git a/docs/cli/overview.md b/docs/cli/overview.md index cc9903ac92..cae03ae01f 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -48,7 +48,6 @@ The following snippet is an example of the output displayed by the `aspire run` ```Aspire CLI Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 - https://literate-eureka-55x5r74pwxv2vx7p-17178.app.github.dev/login?t=17f974bf68e390b0d4548af8d7e38b65 Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log From 6d3b02c23af0c55f3fb025ba85ee8dfb25f0d005 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Sun, 20 Jul 2025 18:20:35 -0700 Subject: [PATCH 35/40] feedback --- docs/cli-reference/aspire-config-set.md | 6 ++++++ docs/cli-reference/aspire-config.md | 6 ++++++ docs/cli-reference/aspire-run.md | 11 +++-------- .../cli-reference/includes/config-settings-table.md | 13 +++++++++++++ docs/cli/install.md | 2 +- docs/cli/overview.md | 11 +++-------- 6 files changed, 32 insertions(+), 17 deletions(-) create mode 100644 docs/cli-reference/includes/config-settings-table.md diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md index 3c66ce0d20..73b52e3811 100644 --- a/docs/cli-reference/aspire-config-set.md +++ b/docs/cli-reference/aspire-config-set.md @@ -48,3 +48,9 @@ The following options are available: - [!INCLUDE [option-debug](includes/option-debug.md)] - [!INCLUDE [option-wait](includes/option-wait.md)] + +## Settings + +The following config settings are available: + +[!INCLUDE [config-settings-table](includes/config-settings-table.md)] diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md index 331c0efcf9..107dba8df4 100644 --- a/docs/cli-reference/aspire-config.md +++ b/docs/cli-reference/aspire-config.md @@ -43,3 +43,9 @@ The following commands are available: | [`aspire config get `](aspire-config-get.md) | Stable | Get a configuration value. | | [`aspire config set `](aspire-config-set.md) | Stable | Set a configuration value. | | [`aspire config delete `](aspire-config-delete.md) | Stable | Delete a configuration value. | + +## Settings + +The following config settings are available: + +[!INCLUDE [config-settings-table](includes/config-settings-table.md)] diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 427219398f..95acd8d172 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -34,14 +34,9 @@ The command performs the following steps to run an apphost project: The following snippet is an example of the output displayed by the `aspire run` command: ```Aspire CLI -Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 - - Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log - -Endpoints: webfrontend has endpoint https://localhost:7294 - webfrontend has endpoint http://localhost:5131 - apiservice has endpoint https://localhost:7531 - apiservice has endpoint http://localhost:5573 +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log ``` ## Options diff --git a/docs/cli-reference/includes/config-settings-table.md b/docs/cli-reference/includes/config-settings-table.md new file mode 100644 index 0000000000..383a8669b7 --- /dev/null +++ b/docs/cli-reference/includes/config-settings-table.md @@ -0,0 +1,13 @@ +--- +ms.date: 07/20/2025 +ms.topic: include +--- + +| Setting | Description | +| ------------- | ----------- | +| `appHostPath` | The path to the AppHost project Aspire CLI uses by default. This setting is set by Aspire CLI when you select a project or when Aspire is first run and detects an AppHost project. | + + diff --git a/docs/cli/install.md b/docs/cli/install.md index d8de103752..e56d7766eb 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -16,7 +16,7 @@ This article teaches you how to install .NET Aspire CLI, which is a .NET global ## Prerequisites -- [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0). +- [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0). ## Install the global tool diff --git a/docs/cli/overview.md b/docs/cli/overview.md index cae03ae01f..e94866146a 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -47,14 +47,9 @@ When `aspire run` starts, it searches the current directory for an AppHost proje The following snippet is an example of the output displayed by the `aspire run` command: ```Aspire CLI -Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 - - Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log - -Endpoints: webfrontend has endpoint https://localhost:7294 - webfrontend has endpoint http://localhost:5131 - apiservice has endpoint https://localhost:7531 - apiservice has endpoint http://localhost:5573 +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log ``` ## Add integrations From 4d66b0edb415cebc41d9298eec5928bad7852e75 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Sun, 20 Jul 2025 18:45:12 -0700 Subject: [PATCH 36/40] Update install with script --- docs/cli/install.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/cli/install.md b/docs/cli/install.md index e56d7766eb..b85e183b02 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -18,9 +18,28 @@ This article teaches you how to install .NET Aspire CLI, which is a .NET global - [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0). -## Install the global tool +## Install as a native executable -Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). +The compiled version of the Aspire CLI can be installd using the Aspire CLI Installation Script. + +01. Open a terminal. +01. Run the following command to download and run the script. + + Windows: + + ```powershell + Invoke-Expression "& { $(Invoke-RestMethod https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.ps1) }" + ``` + + Linux or macOS: + + ```bash + curl -sSL https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.sh | bash + ``` + +## Install as a .NET global tool + +Use the `dotnet tool` command to install the Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). 01. Open a terminal. 01. Run the following command to install Aspire CLI: @@ -37,8 +56,8 @@ To validate that the global tool is installed, use the `--version` option to que aspire --version ``` -If that command works, you're presented with the version of the .NET Aspire CLI tool: +If that command works, you're presented with the version of the Aspire CLI tool: ``` -9.3.1-preview.1.25305.6+5bc26c78ff8c7be825d0ae33633a1ae9f1d64a67 +9.4.0 ``` From 0bada4c6c4cbad96bbb06922a42c02b3a4b5cd8e Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Sun, 20 Jul 2025 18:45:20 -0700 Subject: [PATCH 37/40] feedback --- docs/cli-reference/aspire-deploy.md | 11 +++++------ docs/cli-reference/aspire-exec.md | 2 +- docs/cli-reference/aspire-publish.md | 7 +++---- docs/cli-reference/aspire-run.md | 6 +++--- docs/cli/overview.md | 4 ++-- 5 files changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index e9814386ad..5451b0400d 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -9,7 +9,7 @@ ms.date: 07/11/2025 ## Name -`aspire deploy` - Deploy an Aspire app host project to its supported deployment targets. +`aspire deploy` - Deploy a codebase orchestrated with Aspire to specified targets. [!INCLUDE [mode-preview](includes/mode-preview.md)] @@ -21,17 +21,16 @@ aspire deploy [options] [[--] ...] ## Description -The `aspire deploy` command is similar to [`aspire publish`](./aspire-publish.md). After Aspire has invoked the publishing annotations, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. +The `aspire deploy` command first invokes the [`aspire publish`](./aspire-publish.md) command. After which, Aspire invokes all `DeployingCallbackAnnotation` resource annotations, in the order they're declared. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] -The command performs the following steps to run an AppHost project: +The command performs the following steps to deploy an app orchestrated with Aspire: - Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. - Installs or verifies that Aspire's local hosting certificates are installed and trusted. -- Builds the AppHost project. -- Starts the app host and its resources. -- Starts the app host in publish mode. +- Builds the AppHost project and its resources. +- Starts the AppHost and its resources. - Invokes all resource annotations. - Invokes all `DeployingCallbackAnnotation` resource annotations. diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 336b261be9..34d488080e 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -31,7 +31,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire exec from arguments for the resource. All arguments after this delimiter are passed to the resource. + Delimits arguments to `aspire exec` from arguments for the resource. All arguments after this delimiter are passed to the resource. - [!INCLUDE [option-project](includes/option-project.md)] diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index aaf4cc82f5..c17fa5db99 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -29,9 +29,8 @@ The command performs the following steps to run an AppHost project: - Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. - Installs or verifies that Aspire's local hosting certificates are installed and trusted. -- Builds the AppHost project. -- Starts the app host and its resources. -- Starts the app host in publish mode. +- Builds the AppHost project and its resources. +- Starts the AppHost and its resources. - Invokes all annotations for resources. ## Options @@ -40,7 +39,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire publish from arguments for the AppHost. All arguments after this delimiter are passed to the AppHost. + Delimits arguments to `aspire publish` from arguments for the AppHost. All arguments after this delimiter are passed to the AppHost. - [!INCLUDE [option-project](includes/option-project.md)] diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 95acd8d172..9d187dfd49 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -27,8 +27,8 @@ The command performs the following steps to run an apphost project: - Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. - Installs or verifies that Aspire's local hosting certificates are installed and trusted. -- Builds the AppHost project. -- Starts the app host and its resources. +- Builds the AppHost project and its resources. +- Starts the AppHost and its resources. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: @@ -45,7 +45,7 @@ The following options are available: - **`--`** - Delimits arguments to aspire run from arguments for the app host being run. All arguments after this delimiter are passed to the app host run. + Delimits arguments to `aspire run` from arguments for the app host being run. All arguments after this delimiter are passed to the app host run. - [!INCLUDE [option-project](includes/option-project.md)] diff --git a/docs/cli/overview.md b/docs/cli/overview.md index e94866146a..a815cf86d4 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -40,8 +40,8 @@ The `aspire run` command runs the AppHost project in development mode, which con When `aspire run` starts, it searches the current directory for an AppHost project. If a project isn't found, the sub directories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps: - Installs or verifies that Aspire's local hosting certificates are installed and trusted. -- Builds the AppHost project. -- Starts the app host and its resources. +- Builds the AppHost project and its resources. +- Starts the AppHost and its resources. - Starts the dashboard. The following snippet is an example of the output displayed by the `aspire run` command: From a859602c11f89175f5e92aa38e1d90686a465d93 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Sun, 20 Jul 2025 18:48:34 -0700 Subject: [PATCH 38/40] Apply suggestions from code review Co-authored-by: Maddy Montaquila (Leger) --- docs/cli-reference/aspire-exec.md | 2 +- docs/cli/install.md | 2 +- docs/cli/overview.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 34d488080e..5602521d53 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -19,7 +19,7 @@ aspire exec [options] [[--] ...] ## Description -The `aspire exec` command runs an AppHost project and runs a command in the context of one of the resources. +The `aspire exec` command runs a command in the context of one of the resources defined in the AppHost. You must specify either the `--resource` or the `--start-resource` option, and you must provide parameters with the `--` option. diff --git a/docs/cli/install.md b/docs/cli/install.md index b85e183b02..10b5cdc040 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -12,7 +12,7 @@ ms.date: 06/26/2025 # Install .NET Aspire CLI -This article teaches you how to install .NET Aspire CLI, which is a .NET global tool used to manage your .NET Aspire projects. +This article teaches you how to install the Aspire CLI, which is a CLI tool used to manage your .NET Aspire projects. ## Prerequisites diff --git a/docs/cli/overview.md b/docs/cli/overview.md index a815cf86d4..80437d219d 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -16,7 +16,7 @@ The Aspire CLI (`aspire` command) is a cross-platform tool that provides command The Aspire CLI is an interactive-first experience. -- [Install .NET Aspire CLI.](install.md) +- [Install the Aspire CLI.](install.md) - [`aspire` command reference.](../cli-reference/aspire.md) ## Use templates @@ -31,7 +31,7 @@ Use the `aspire new` command to create an Aspire project from a list of template While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. -## Start the app host +## Start the Aspire AppHost [_Command reference: `aspire run`_](../cli-reference/aspire-run.md) From 1eec6f4312147f0d7c3db3938e701baf29b35a98 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Sun, 20 Jul 2025 18:51:52 -0700 Subject: [PATCH 39/40] feedback --- docs/cli-reference/aspire-exec.md | 2 ++ docs/cli-reference/aspire-publish.md | 2 +- docs/cli-reference/aspire-run.md | 2 +- docs/cli-reference/aspire.md | 4 ++-- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 5602521d53..97c8897e6e 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -11,6 +11,8 @@ ms.date: 07/11/2025 `aspire exec` - Run an Aspire app host to execute a command against the resource. +[!INCLUDE [mode-preview](includes/mode-preview.md)] + ## Synopsis ```dotnetcli diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index c17fa5db99..4d9b7b81cf 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -25,7 +25,7 @@ The `aspire publish` command publishes resources by serializing them to disk. Wh [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] -The command performs the following steps to run an AppHost project: +The command performs the following steps to run an Aspire AppHost: - Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. - Installs or verifies that Aspire's local hosting certificates are installed and trusted. diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 9d187dfd49..fa37945d40 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -23,7 +23,7 @@ The `aspire run` command runs the AppHost project in development mode, which con [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] -The command performs the following steps to run an apphost project: +The command performs the following steps to run an Aspire AppHost: - Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. - Installs or verifies that Aspire's local hosting certificates are installed and trusted. diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 8ba9e7159c..6ef881d86b 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -42,9 +42,9 @@ The following commands are available: | Command | Status | Function | |--------------------------------------------------|---------|--------------------------------------------------------------------------| | [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | -| [`aspire config`](aspire-configure.md) | Stable | Configures the Aspire environment. | +| [`aspire config`](aspire-config.md) | Stable | Configures the Aspire environment. | | [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | -| [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire exec`](aspire-exec.md) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | | [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | | [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | | [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | From c643ab137a78549dcd699efa1c4a246ecf4c1291 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Sun, 20 Jul 2025 19:07:26 -0700 Subject: [PATCH 40/40] minor fixes and feedback --- docs/cli-reference/aspire-add.md | 4 ++-- docs/cli-reference/aspire-config-delete.md | 2 +- docs/cli-reference/aspire-config-get.md | 2 +- docs/cli-reference/aspire-config-list.md | 2 +- docs/cli-reference/aspire-config-set.md | 2 +- docs/cli-reference/aspire-config.md | 2 +- docs/cli-reference/aspire-deploy.md | 6 +++--- docs/cli-reference/aspire-exec.md | 2 +- docs/cli-reference/aspire-new.md | 2 +- docs/cli-reference/aspire-publish.md | 2 +- docs/cli-reference/aspire-run.md | 2 +- docs/cli-reference/aspire.md | 8 ++++---- 12 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/cli-reference/aspire-add.md b/docs/cli-reference/aspire-add.md index 28b2b1a142..b382c486d3 100644 --- a/docs/cli-reference/aspire-add.md +++ b/docs/cli-reference/aspire-add.md @@ -13,13 +13,13 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire add [] [options] ``` ## Description -The `aspire add` command searches NuGet for an integration package and adds it to the AppHost project. +The `aspire add` command searches for an integration package and adds it to the Aspire AppHost. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] diff --git a/docs/cli-reference/aspire-config-delete.md b/docs/cli-reference/aspire-config-delete.md index c25b2e7a55..6c4fdba3d0 100644 --- a/docs/cli-reference/aspire-config-delete.md +++ b/docs/cli-reference/aspire-config-delete.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire config delete [options] ``` diff --git a/docs/cli-reference/aspire-config-get.md b/docs/cli-reference/aspire-config-get.md index d0406d39f2..40326a5f03 100644 --- a/docs/cli-reference/aspire-config-get.md +++ b/docs/cli-reference/aspire-config-get.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire config get [options] ``` diff --git a/docs/cli-reference/aspire-config-list.md b/docs/cli-reference/aspire-config-list.md index 8af315a42a..d2b3a1b75e 100644 --- a/docs/cli-reference/aspire-config-list.md +++ b/docs/cli-reference/aspire-config-list.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire config list [options] ``` diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md index 73b52e3811..4b53ed3685 100644 --- a/docs/cli-reference/aspire-config-set.md +++ b/docs/cli-reference/aspire-config-set.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire config set [options] ``` diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md index 107dba8df4..f18856abc2 100644 --- a/docs/cli-reference/aspire-config.md +++ b/docs/cli-reference/aspire-config.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire config [command] [options] ``` diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index 5451b0400d..245bfe2eff 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -15,7 +15,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire deploy [options] [[--] ...] ``` @@ -62,13 +62,13 @@ The following options are available: aspire deploy ``` -- Publish and deploy a specific AppHost project: +- Publish and deploy an Aspire apphost and its dependencies: ```Command aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' ``` -- Publish and deploy a specific AppHost project with arguments: +- Publish and deploy an Aspire AppHost with arguments: ```Command aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' -- -fast diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md index 97c8897e6e..301f432abf 100644 --- a/docs/cli-reference/aspire-exec.md +++ b/docs/cli-reference/aspire-exec.md @@ -15,7 +15,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire exec [options] [[--] ...] ``` diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md index b2c99396b5..9f0fff615c 100644 --- a/docs/cli-reference/aspire-new.md +++ b/docs/cli-reference/aspire-new.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire new [command] [options] ``` diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index 4d9b7b81cf..33fc754f15 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -15,7 +15,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire publish [options] [[--] ...] ``` diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index fa37945d40..80c9d2397f 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -13,7 +13,7 @@ ms.date: 07/11/2025 ## Synopsis -```dotnetcli +```Command aspire run [options] [[--] ...] ``` diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index 6ef881d86b..8ba31e7476 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -15,13 +15,13 @@ ms.date: 07/11/2025 To get information about the available commands and the environment: -```dotnetcli +```Command aspire [command] [options] ``` ## Description -The `aspire` command provides commands for working with Aspire projects. For example, `aspire run` runs an Aspire AppHost project. +The `aspire` command provides commands for working with Aspire projects. For example, `aspire run` runs your Aspire AppHost. ## Options @@ -47,7 +47,7 @@ The following commands are available: | [`aspire exec`](aspire-exec.md) | Preview | Similar to the `aspire run` command, but passes commands to the apphost. | | [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | | [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | -| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | +| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost for local development. |