Skip to content

Latest commit

 

History

History
170 lines (104 loc) · 9.59 KB

setup-tooling.md

File metadata and controls

170 lines (104 loc) · 9.59 KB
Raw
title description ms.date
.NET Aspire tooling
Learn about essential tooling concepts for .NET Aspire.
12/01/2023

.NET Aspire setup and tooling

.NET Aspire includes tooling to help you create and configure cloud-native apps. The tooling includes useful starter project templates and other features to streamline getting started with .NET Aspire for both Visual Studio and CLI workflows. In the sections ahead, you'll learn how to work with .NET Aspire tooling and explore the following tasks:

[!div class="checklist"]

  • Install .NET Aspire and its dependencies
  • Create starter project templates using Visual Studio or the .NET CLI
  • Install .NET Aspire components
  • Work with the .NET Aspire dashboard

Install .NET Aspire

To work with .NET Aspire, you'll need the following installed locally:

The .NET Aspire workload installs internal dependencies and makes available other tooling, such as project templates and Visual Studio features. There are two ways to install the .NET Aspire workload. If you prefer to use Visual Studio Code, follow the .NET CLI instructions:

Visual Studio

To install the .NET Aspire workload in Visual Studio 2022 Preview, use the Visual Studio installer.

  1. Open the Visual Studio Installer.
  2. Select Modify next to Visual Studio 2022 Preview.
  3. Select the ASP.NET and web development workload.
  4. On the Installation details panel, select .NET Aspire SDK (Preview).
  5. Select Modify to install the .NET Aspire component.

:::image type="content" source="media/install-aspire-workload-visual-studio.png" lightbox="media/install-aspire-workload-visual-studio.png" alt-text="A screenshot showing how to install the .NET Aspire workload with the Visual Studio installer.":::

.NET CLI

To install the .NET Aspire workload from the .NET CLI, use the dotnet workload install command:

dotnet workload install aspire

If you've already installed the .NET Aspire workload, it's best to ensure that you're using the latest version. To ensure that you are, use the following dotnet workload update command:

dotnet workload update aspire

.NET Aspire project templates

The .NET Aspire workload makes available .NET Aspire project templates. These project templates allow you to create new apps pre-configured with the .NET Aspire project structure and default settings. These projects also provide a unified debugging experience across the different resources of your app.

There are currently two project templates available:

  • .NET Aspire Application: A minimal .NET Aspire app that includes the following:

    • AspireSample.AppHost: An orchestrator project designed to connect and configure the different projects and services of your app.

    • AspireSample.ServiceDefaults: A .NET Aspire shared project to manage configurations that are reused across the projects in your solution related to resilience, service discovery, and telemetry.

  • .NET Aspire Starter Application: In addition to the .AppHost and .ServiceDefaults projects, the .NET Aspire Starter Application also includes the following:

    • AspireSample.ApiService: An ASP.NET Core Minimal API project is used to provide data to the frontend. This project depends on the shared AspireSample.ServiceDefaults project.

    • AspireSample.Web: An ASP.NET Core Blazor App project with default .NET Aspire service configurations, this project depends on the AspireSample.ServiceDefaults project.

Use Visual Studio or the .NET CLI to create new apps using these project templates. Explore additional .NET Aspire project templates in the .NET Aspire samples repository.

Visual Studio

To create a .NET Aspire project using Visual Studio, search for Aspire in the Visual Studio new project window and select your desired template.

:::image type="content" source="media/aspire-templates.png" lightbox="media/aspire-templates.png" alt-text="The .NET Aspire project templates in VIsual Studio.":::

.NET CLI

To see which .NET Aspire project templates are available, use the dotnet new list command, passing in the search term aspire:

dotnet new list aspire

When the .NET Aspire workload is installed, you'll see the following .NET Aspire templates:

These templates matched your input: 'aspire'

Template Name                    Short Name      Language  Tags
-------------------------------  --------------  --------  -------------------------------------------------------
.NET Aspire Application          aspire          [C#]      Common/.NET Aspire/Cloud
.NET Aspire Starter Application  aspire-starter  [C#]      Common/.NET Aspire/Blazor/Web/Web API/API/Service/Cloud

To create a .NET Aspire project using the .NET CLI, use the dotnet new command and specify which template you would like to create.

To create a basic .NET Aspire project:

dotnet new aspire

To create a .NET Aspire project with a sample UI and API included:

dotnet new aspire-starter

.NET Aspire dashboard

.NET Aspire project templates also include a useful dashboard that can be used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app.

The .NET Aspire dashboard is only visible while the app is running and starts automatically when you start the .AppHost project. Visual Studio launches both your app and the .NET Aspire dashboard for you automatically in your browser. If you start the app using the .NET CLI, copy and paste the dashboard URL from the output into your browser.

:::image type="content" source="media/run-dashboard-cli.png" alt-text="A screenshot showing how to launch the dashboard using the CLI.":::

The left navigation provides links to the different parts of the dashboard, each of which you'll explore in the following sections.

:::image type="content" source="media/dashboard/projects.png" lightbox="media/dashboard/projects.png" alt-text="A screenshot of the .NET Aspire dashboard Projects page.":::

Visual Studio tooling

Visual Studio provides additional features for working with .NET Aspire components and the App Host orchestrator project. These features are currently not available in Visual Studio Code or through the CLI.

Enable .NET Aspire preview support

In Visual Studio, you can enable preview support for .NET Aspire components and project templates. To enable preview support, select Tools > Options > and in the Search Settings textbox enter "aspire", then ensure that the Enable .NET Aspire preview support is checked:

:::image type="content" source="media/visual-studio-tools-options-aspire.png" lightbox="media/visual-studio-tools-options-aspire.png" alt-text="Visual Studio 2022, enable .NET Aspire preview support.":::

Likewise, you can disable preview support by unchecking the Enable .NET Aspire preview support option.

Add a component

You can add .NET Aspire components to your app like any other NuGet package using Visual Studio. However, Visual Studio also provides UI options to add .NET Aspire components directly.

  1. In Visual Studio, right click on the project you want to add an .NET Aspire component to and select Add > .NET Aspire Component....
  2. The package manager will open with search results pre-configured for .NET Aspire components, allowing you to easily browse and select the desired component.

Add orchestration projects

You can add .NET Aspire orchestration projects to an existing app using the following steps:

  1. In Visual Studio, right click on an existing project and select Add > .NET Aspire Orchestrator Support...

  2. A dialog window will open with a summary of the .AppHost and .ServiceDefaults projects that will be added to your solution.

    :::image type="content" source="media/add-orchestrator-app.png" alt-text="A screenshot showing the Visual Studio add .NET Aspire orchestration summary.":::

  3. Select OK and the following changes will be applied:

    • The .AppHost and .ServiceDefault orchestration projects will be added to your solution.
    • A call to builder.AddServiceDefaults will be added to the Program.cs file of your original project.
    • A reference to your original project will be added to the Program.cs file of the .AppHost project.

Enlist in orchestration

Visual Studio provides the option to Enlist in Aspire orchestration during the new project workflow. Select this option to have Visual Studio create .AppHost and .ServiceDefault projects alongside your selected project template.

:::image type="content" source="media/aspire-enlist-orchestration.png" lightbox="media/aspire-enlist-orchestration.png" alt-text="A screenshot showing how to enlist in .NET Aspire orchestration.":::