From 5cf3a77c8d0b4acea1f5304df9715511a4f2ae65 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 1/6] 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 240401642e..bfa26a7425 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -101,6 +101,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 fb274b183a323a6726a8a128933406473a44849e 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 2/6] 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 ae367c399d044b5061e68afe2882922e629cd72c 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 3/6] 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 bfa26a7425..2d89d73851 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -101,13 +101,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 641c62f8d2dc826ee132b4c0dcbb2e5a72afac60 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 4/6] 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 01e828a7680e548015943aafc896637138b786e1 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 5/6] 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 508cc7a58dc67a03ce561039311e96f941ae3f36 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 6/6] Apply suggestions from code review Co-authored-by: David Pine --- docs/cli-reference/aspire.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md index a48d60b67b..705139cb45 100644 --- a/docs/cli-reference/aspire.md +++ b/docs/cli-reference/aspire.md @@ -47,7 +47,7 @@ The following options are available when `aspire` is used by itself, without spe | Command | Function | |-------------------------------------|----------------------------------------------------------------| -| [aspire new](aspire-new.md) | Create an Aspire sample project from a template. | +| [aspire new](aspire-new.md) | Create an Aspire sample project or solution 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. | @@ -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: ```dotnetcli aspire new aspire-starter