diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index 271ad710df..56dd885e2e 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -1,9 +1,9 @@ --- title: Build your first Aspire solution -description: Learn how to build your first Aspire solution using the Aspire Started Application template. -ms.date: 11/07/2024 +description: Learn how to build your first Aspire solution using the Aspire Starter application template. +ms.date: 10/08/2025 ms.topic: quickstart -zone_pivot_groups: dev-environment +zone_pivot_groups: dev-tools ms.custom: sfi-ropc-nochange --- @@ -15,20 +15,20 @@ In this quickstart, you explore the following tasks: > [!div class="checklist"] > -> - Create a basic .NET app that is set up to use Aspire. -> - Add and configure an Aspire integration to implement caching at project creation time. -> - Create an API and use service discovery to connect to it. -> - Orchestrate communication between a front end UI, a back end API, and a local Redis cache. +> - Create a basic app that is set up to use Aspire. +> - Test the basic functionality of the app. +> - Use the Aspire dashboard to monitor your app as it runs. +> - Understand the structure of an Aspire solution. [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)] -## Create the Aspire template +## Create the Aspire application -To create a new Aspire Starter Application, you can use either Visual Studio, Visual Studio Code, or the .NET CLI. +In this quickstart, you can choose whether to use the Aspire CLI or Visual Studio Code to create a new Aspire Starter application. -:::zone pivot="visual-studio" +:::zone pivot="aspire-cli" -[!INCLUDE [visual-studio-file-new](../includes/visual-studio-file-new.md)] +[!INCLUDE [aspire-cli-new-app](../includes/aspire-cli-new-app.md)] :::zone-end :::zone pivot="vscode" @@ -36,12 +36,15 @@ To create a new Aspire Starter Application, you can use either Visual Studio, Vi [!INCLUDE [vscode-file-new](../includes/vscode-file-new.md)] :::zone-end -:::zone pivot="dotnet-cli" +:::zone pivot="visual-studio" -[!INCLUDE [dotnet-cli-file-new](../includes/dotnet-cli-file-new.md)] +[!INCLUDE [visual-studio-file-new](../includes/visual-studio-file-new.md)] :::zone-end +> [!NOTE] +> You chose not to add a test project to the new solution. You can always add a test project later but it's not needed for this quickstart. + For more information on the available templates, see [Aspire templates](../fundamentals/aspire-sdk-templates.md). ## Test the app locally @@ -51,49 +54,42 @@ The sample app includes a frontend Blazor app that communicates with a Minimal A - Weather data is retrieved from the API project using service discovery and displayed on the weather page. - Subsequent requests are handled via the output caching configured by the Aspire Redis integration. -:::zone pivot="visual-studio" +> [!TIP] +> Make sure that your chosen container runtime, such as Docker Desktop or Podman, is running to host containers. -In Visual Studio, set the **AspireSample.AppHost** project as the startup project by right-clicking on the project in the **Solution Explorer** and selecting **Set as Startup Project**. It might already have been automatically set as the startup project. Once set, press F5 or (Ctrl + F5 to run without debugging) to run the app. +:::zone pivot="aspire-cli" -:::zone-end -:::zone pivot="dotnet-cli" +1. In the command prompt, navigate to the folder where you created the solution. It will be a subdirectory of the location where you ran the `aspire new` command. +1. To run the Aspire solution, execute this command: + + ```Aspire + aspire run + ``` -You need to trust the ASP.NET Core localhost certificate before running the app. Run the following command: +1. The `aspire run` command compiles all the projects in the solution, and then locates and runs the AppHost project. It displays information about the solution, including the location of the Aspire dashboard: -```dotnetcli -dotnet dev-certs https --trust -``` + :::image type="content" source="media/aspire-cli-run.png" lightbox="media/aspire-cli-run.png" alt-text="A screenshot of the Aspire CLI running an Aspire solution."::: -For more information, see [Troubleshoot untrusted localhost certificate in Aspire](../troubleshooting/untrusted-localhost-certificate.md). For in-depth details about troubleshooting localhost certificates on Linux, see [ASP.NET Core: GitHub repository issue #32842](https://github.com/dotnet/aspnetcore/issues/32842). +1. To browse the Aspire dashboard, hold down CTRL and select the **Dashboard** URL. :::zone-end :::zone pivot="vscode" -In Visual Studio Code, press F5 to launch the app. You're prompted to select which language, and C# is suggested. Select **C#** and then select the **AspireSample.AppHost** project with the **Default Configuration**: - -:::image type="content" loc-scope="vs-code" source="media/vscode-run.png" lightbox="media/vscode-run.png" alt-text="A screenshot of the Visual Studio Code launch configuration for the AspireSample.AppHost project."::: - -If this is the first time you're running Aspire, or it's a new machine with a new .NET installation, you're prompted to install a self-signed localhost certificate—and the project will fail to launch: - -:::image type="content" loc-scope="vs-code" source="media/vscode-run-accept-cert.png" lightbox="media/vscode-run-accept-cert.png" alt-text="A screenshot of the Visual Studio Code breaking on an exception and prompting to create a trusted self-signed certificate."::: +In Visual Studio Code, press F5 to launch the app. You're prompted to select a debugger, and **Aspire** is suggested. Select **Aspire**: -Select **Yes**, and you see an informational message indicating that the **Self-signed certificate successfully created**: +:::image type="content" loc-scope="vs-code" source="media/vscode-run.png" lightbox="media/vscode-run.png" alt-text="A screenshot of the Visual Studio Code launch configuration for the AspireFirstSolution.AppHost project."::: -:::image type="content" loc-scope="vs-code" source="media/vscode-run-cert-created.png" lightbox="media/vscode-run-cert-created.png" alt-text="A screenshot of the Visual Studio Code success message for creating a self-signed certificate."::: +Visual Studio Code opens a new debug console and runs the Aspire CLI to start your app. All projects are compiled, containers are deployed and information about the app is displayed. In the **Launch Aspire Dashboard** dialog, to view the dashboard, select **Open local URL**: -If you're still having an issue, close all browser windows and try again. For more information, see [Troubleshoot untrusted localhost certificate in Aspire](../troubleshooting/untrusted-localhost-certificate.md). +:::image type="content" loc-scope="vs-code" source="media/vscode-launch-dashboard.png" lightbox="media/vscode-launch-dashboard.png" alt-text="A screenshot of Visual Studio Code running the new Aspire app."::: > [!TIP] > If you're on MacOS and using Safari, when your browser opens if the page is blank, you might need to manually refresh the page. :::zone-end -:::zone pivot="dotnet-cli" - -```dotnetcli -dotnet run --project AspireSample/AspireSample.AppHost -``` +:::zone pivot="visual-studio" -For more information, see [dotnet run](/dotnet/core/tools/dotnet-run). +In Visual Studio, set the **AspireSample.AppHost** project as the startup project by right-clicking on the project in the **Solution Explorer** and selecting **Set as Startup Project**. It might already have been automatically set as the startup project. Once set, press F5 or (Ctrl + F5 to run without debugging) to run the app. :::zone-end @@ -108,11 +104,11 @@ For more information, see [dotnet run](/dotnet/core/tools/dotnet-run). :::image type="content" source="media/weather-page.png" lightbox="media/weather-page.png" alt-text="The Weather page of the webfrontend app showing the weather data retrieved from the API."::: -🤓 Congratulations! You created and ran your first Aspire solution! To stop the app, close the browser window. +🤓 Congratulations! You created and ran your first Aspire solution! Close the browser window. -:::zone pivot="visual-studio" +:::zone pivot="aspire-cli" -To stop the app in Visual Studio, select the **Stop Debugging** from the **Debug** menu. +To stop the app, switch to the command prompt where the `aspire run` command is still running and then press CTRL + C. :::zone-end :::zone pivot="vscode" @@ -122,9 +118,9 @@ To stop the app in Visual Studio Code, press Shift + F5, o :::image type="content" loc-scope="vs-code" source="media/vscode-stop.png" lightbox="media/vscode-stop.png" alt-text="A screenshot of the Visual Studio Code stop button."::: :::zone-end -:::zone pivot="dotnet-cli" +:::zone pivot="visual-studio" -To stop the app, press Ctrl + C in the terminal window. +To stop the app in Visual Studio, select the **Stop Debugging** from the **Debug** menu. :::zone-end @@ -138,8 +134,11 @@ When you run an Aspire project, a [dashboard](../fundamentals/dashboard/overview Visit each page using the left navigation to view different information about the Aspire resources: -- **Resources**: Lists basic information for all of the individual .NET projects in your Aspire project, such as the app state, endpoint addresses, and the environment variables that were loaded in. -- **Console**: Displays the console output from each of the projects in your app. +- **Resources**: Lists basic information for all of the individual .NET projects and other resources in your Aspire project, such as the app state, endpoint addresses, and the environment variables that were loaded in. The **Graph** tab displays dependencies between these components: + + :::image type="content" source="media/aspire-dashboard-graph.png" lightbox="media/aspire-dashboard-graph.png" alt-text="A screenshot showing the Graph page of the Aspire dashboard."::: + +- **Console**: Displays the console output from each of the resources in your app. - **Structured**: Displays structured logs in table format. These logs support basic filtering, free-form search, and log level filtering as well. You should see logs from the `apiservice` and the `webfrontend`. You can expand the details of each log entry by selecting the **View** button on the right end of the row. - **Traces**: Displays the traces for your application, which can track request paths through your apps. Locate a request for **/weather** and select **View** on the right side of the page. The dashboard should display the request in stages as it travels through the different parts of your app. @@ -164,70 +163,6 @@ Your _AspireSample_ directory should resemble the following structure: [!INCLUDE [template-directory-structure](../includes/template-directory-structure.md)] -## Explore the starter projects - -Each project in an Aspire solution plays a role in the composition of your app. The _*.Web_ project is a standard ASP.NET Core Blazor App that provides a front end UI. For more information, see [What's new in ASP.NET Core 9.0: Blazor](/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0&preserve-view=true#blazor). The _*.ApiService_ project is a standard ASP.NET Core Minimal API template project. Both of these projects depend on the _*.ServiceDefaults_ project, which is a shared project that's used to manage configurations that are reused across projects in your solution. - -The two projects of interest in this quickstart are the _*.AppHost_ and _*.ServiceDefaults_ projects detailed in the following sections. - -### Aspire host project - -The _*.AppHost_ project is responsible for acting as a local dev-orchestrator: - -:::code language="xml" source="snippets/quickstart/AspireSample/AspireSample.AppHost/AspireSample.AppHost.csproj" highlight="10"::: - -For more information, see [Aspire orchestration overview](../fundamentals/app-host-overview.md) and [Aspire SDK](../fundamentals/dotnet-aspire-sdk.md). - -Consider the _:::no-loc text="AppHost.cs":::_ file of the _AspireSample.AppHost_ project: - -:::code source="snippets/quickstart/AspireSample/AspireSample.AppHost/AppHost.cs"::: - -If you've used either the [.NET Generic Host](/dotnet/core/extensions/generic-host) or the [ASP.NET Core Web Host](/aspnet/core/fundamentals/host/web-host) before, the AppHost programming model and builder pattern should be familiar to you. The preceding code: - -- Creates an instance from calling . -- Calls with the name `"cache"` to add a Redis server to the app, assigning the returned value to a variable named `cache`, which is of type `IResourceBuilder`. -- Calls given the generic-type parameter with the project's details, adding the `AspireSample.ApiService` project to the application model. This is one of the fundamental building blocks of Aspire, and it's used to configure service discovery and communication between the projects in your app. The name argument `"apiservice"` is used to identify the project in the application model, and used later by projects that want to communicate with it. -- Calls `AddProject` again, this time adding the `AspireSample.Web` project to the application model. It also chains multiple calls to passing the `cache` and `apiService` variables. The `WithReference` API is another fundamental API of Aspire, which injects either service discovery information or connection string configuration into the project being added to the application model. Additionally, calls to the `WaitFor` API are used to ensure that the `cache` and `apiService` resources are available before the `AspireSample.Web` project is started. For more information, see [Aspire orchestration: Waiting for resources](../fundamentals/orchestrate-resources.md#waiting-for-resources). - -Finally, the app is built and run. The method is responsible for starting the app and all of its dependencies. For more information, see [Aspire orchestration overview](../fundamentals/app-host-overview.md). - -> [!TIP] -> The call to creates a local Redis container for the app to use. If you'd rather simply point to an existing Redis instance, you can use the `AddConnectionString` method to reference an existing connection string. For more information, see [Reference existing resources](../fundamentals/app-host-overview.md#reference-existing-resources). - -### Aspire service defaults project - -The _*.ServiceDefaults_ project is a shared project that's used to manage configurations that are reused across the projects in your solution. This project ensures that all dependent services share the same resilience, service discovery, and OpenTelemetry configuration. A shared Aspire project file contains the `IsAspireSharedProject` property set as `true`: - -:::code language="xml" source="snippets/quickstart/AspireSample/AspireSample.ServiceDefaults/AspireSample.ServiceDefaults.csproj" highlight="7"::: - -The service defaults project exposes an extension method on the type, named `AddServiceDefaults`. The service defaults project from the template is a starting point, and you can customize it to meet your needs. For more information, see [Aspire service defaults](../fundamentals/service-defaults.md). - -## Orchestrate service communication - -Aspire provides orchestration features to assist with configuring connections and communication between the different parts of your app. The _AspireSample.AppHost_ project added the _AspireSample.ApiService_ and _AspireSample.Web_ projects to the application model. It also declared their names as `"webfrontend"` for Blazor front end, `"apiservice"` for the API project reference. Additionally, a Redis server resource labeled `"cache"` was added. These names are used to configure service discovery and communication between the projects in your app. - -The front end app defines a typed that's used to communicate with the API project. - -:::code source="snippets/quickstart/AspireSample/AspireSample.Web/WeatherApiClient.cs"::: - -The `HttpClient` is configured to use service discovery. Consider the following code from the _:::no-loc text="Program.cs":::_ file of the _AspireSample.Web_ project: - -:::code source="snippets/quickstart/AspireSample/AspireSample.Web/Program.cs" highlight="7-8,14-19"::: - -The preceding code: - -- Calls `AddServiceDefaults`, configuring the shared defaults for the app. -- Calls with the same `connectionName` that was used when adding the Redis container `"cache"` to the application model. This configures the app to use Redis for output caching. -- Calls and configures the to be `"https+http://apiservice"`. This is the name that was used when adding the API project to the application model, and with service discovery configured, it automatically resolves to the correct address to the API project. - -For more information, see [Make HTTP requests with the `HttpClient`](/dotnet/fundamentals/networking/http/httpclient) class. - -## Aspire CLI - -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. - -For more information, see [Aspire CLI Overview](../cli/overview.md) and [Install Aspire CLI](../cli/install.md). - ## See also - [Aspire integrations overview](../fundamentals/integrations-overview.md) diff --git a/docs/get-started/media/aspire-cli-run.png b/docs/get-started/media/aspire-cli-run.png new file mode 100644 index 0000000000..08b34e95f2 Binary files /dev/null and b/docs/get-started/media/aspire-cli-run.png differ diff --git a/docs/get-started/media/aspire-dashboard-graph.png b/docs/get-started/media/aspire-dashboard-graph.png new file mode 100644 index 0000000000..a74d44de54 Binary files /dev/null and b/docs/get-started/media/aspire-dashboard-graph.png differ diff --git a/docs/get-started/media/aspire-dashboard-webfrontend.png b/docs/get-started/media/aspire-dashboard-webfrontend.png index 1c2494ae28..113f15c563 100644 Binary files a/docs/get-started/media/aspire-dashboard-webfrontend.png and b/docs/get-started/media/aspire-dashboard-webfrontend.png differ diff --git a/docs/get-started/media/aspire-dashboard.png b/docs/get-started/media/aspire-dashboard.png index 0793044bd8..aedcd85bc1 100644 Binary files a/docs/get-started/media/aspire-dashboard.png and b/docs/get-started/media/aspire-dashboard.png differ diff --git a/docs/get-started/media/vscode-launch-dashboard.png b/docs/get-started/media/vscode-launch-dashboard.png new file mode 100644 index 0000000000..e2e786c656 Binary files /dev/null and b/docs/get-started/media/vscode-launch-dashboard.png differ diff --git a/docs/get-started/media/vscode-run.png b/docs/get-started/media/vscode-run.png index 6de4e9ea04..a9330bf075 100644 Binary files a/docs/get-started/media/vscode-run.png and b/docs/get-started/media/vscode-run.png differ diff --git a/docs/includes/aspire-cli-new-app.md b/docs/includes/aspire-cli-new-app.md new file mode 100644 index 0000000000..56f7d4306d --- /dev/null +++ b/docs/includes/aspire-cli-new-app.md @@ -0,0 +1,18 @@ +The Aspire CLI can lead you through the choices necessary to create a new Aspire solution, based on one of the Aspire templates. Complete the following steps to create a project for this quickstart: + +1. Open a command prompt and navigate to a folder where you want to work. The Aspire CLI will create a new subdirectory and places the entire solution in it. +1. To run the Aspire CLI, execute the following command: + + ```Aspire + aspire new + ``` + +1. The Aspire CLI presents a list of templates for you to choose from. Select `Starter template` and then press Enter. + + :::image type="content" source="media/aspire-cli-new-select-template.png" lightbox="media/aspire-cli-new-select-template.png" alt-text="A screenshot of the command prompt running the Aspire CLI."::: + +1. Enter a name for the new solution, and then press Enter. +1. Enter a folder for the new solution. The default name is the solution name that you just entered. +1. Select the default version of Aspire, which is the latest version on NuGet. Alternatively you can select the latest daily or stable builds of Aspire. +1. Choose `Yes` to include a Redis Cache integration in the solution. +1. Choose `No` to exclude a test project from the solution. The Aspire CLI creates the new solution. diff --git a/docs/includes/media/aspire-cli-new-select-template.png b/docs/includes/media/aspire-cli-new-select-template.png new file mode 100644 index 0000000000..37229068ef Binary files /dev/null and b/docs/includes/media/aspire-cli-new-select-template.png differ diff --git a/docs/includes/media/vscode-create-starter-app.png b/docs/includes/media/vscode-create-starter-app.png index 89db4d5f8b..f52fd681f4 100644 Binary files a/docs/includes/media/vscode-create-starter-app.png and b/docs/includes/media/vscode-create-starter-app.png differ diff --git a/docs/includes/media/vscode-install-aspire-extension.png b/docs/includes/media/vscode-install-aspire-extension.png new file mode 100644 index 0000000000..4ebd6df8fb Binary files /dev/null and b/docs/includes/media/vscode-install-aspire-extension.png differ diff --git a/docs/includes/vscode-file-new.md b/docs/includes/vscode-file-new.md index 6c1b1fa976..27a6df5079 100644 --- a/docs/includes/vscode-file-new.md +++ b/docs/includes/vscode-file-new.md @@ -1,8 +1,21 @@ -Visual Studio Code provides Aspire project templates that handle some initial setup configurations for you. Complete the following steps to create a project for this quickstart: +Visual Studio Code provides Aspire project templates that handle some initial setup configurations for you and there is an Aspire official extension that integrates Visual Studio Code more closely with Aspire. Complete the following steps to install the extension: -1. From a new instance of Visual Studio Code (without a folder open), select **Create .NET project** button. -1. Select the **Aspire Starter App** template. +1. From a new instance of Visual Studio Code (without a folder open), select the **Extensions** tab or press CTRL + SHIFT + X. +1. In the **Search in Extensions in Marketplace** textbox, type **Aspire** and then select the official Aspire extension. +1. Select **Install**. Visual Studio Code installs the extension. + + :::image type="content" loc-scope="vs-code" source="media/vscode-install-aspire-extension.png" lightbox="media/vscode-install-aspire-extension.png" alt-text="A screenshot of the Visual Studio Code installing the Aspire official extension."::: + +Now, you can use the extension to create a new Aspire solution. Complete the following steps to create a solution for this quickstart: + +1. In Visual Studio Code, select **View** > **Command Palette** or press CTRL + SHIFT + P. +1. Type **Aspire**, and then select **Aspire: New Aspire project**. Visual Studio Code opens a new terminal and starts the Aspire CLI. :::image type="content" loc-scope="vs-code" source="media/vscode-create-starter-app.png" lightbox="media/vscode-create-starter-app.png" alt-text="A screenshot of the Aspire Starter App template."::: -1. Select a folder for the new project, and the enter a name for it. +1. When prompted for a project template, select **Starter template**. +1. Enter a name for the project, and then press ENTER. +1. Enter an output path for the new project, and then press ENTER. +1. Select a template version for the project. The default is the latest version on NuGet. Alternatively you can select the latest daily or stable builds of Aspire. +1. Choose `Yes` to include a Redis Cache integration in the solution. +1. Choose `No` to exclude a test project from the solution. The Aspire CLI creates the new solution. diff --git a/docs/zones/zone-pivot-groups.yml b/docs/zones/zone-pivot-groups.yml index 9bb6c5950c..436fd8c024 100644 --- a/docs/zones/zone-pivot-groups.yml +++ b/docs/zones/zone-pivot-groups.yml @@ -43,6 +43,16 @@ groups: title: Visual Studio - id: dotnet-cli title: .NET CLI +- id: dev-tools + title: Development tools + prompt: Choose your preferred development tools + pivots: + - id: aspire-cli + title: Aspire CLI + - id: vscode + title: Visual Studio Code + - id: visual-studio + title: Visual Studio - id: resp-host title: Hosting resource type prompt: Choose a hosting resource that supports the Redis protocol