docs update (#9408)

danmoseley · web-flow · commit 7615e1829c57 · 2025-05-20T02:01:45.000Z
diff --git a/docs/api-review-process.md b/docs/api-review-process.md
diff --git a/docs/area-owners.md b/docs/area-owners.md
@@ -10,7 +10,7 @@ If you need to tag folks on an issue or PR, you will generally want to tag the o
 | [area-app-model](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-app-model)                     | @adityamandaleeka | @aspire/area-app-model           | Issues/PRs related to the Aspire app model and Aspire AppHost                                                                      |
 | [area-app-testing](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-app-testing)                 | @ReubenBond       | @aspire/area-app-testing         | Issues/PRs related to the framework we provide for scenario testing of Aspire apps                                                 |
 | [area-components](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-components)                   | @sebastienros     | @aspire/area-components          | Issues/PRs related to Aspire Components                                                                                            |
-| [area-dashboard](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-dashboard)                     | @kvenkatrajan     | @aspire/area-dashboard           | Issues/PRs related to the Dashboard UI                                                                                             |
+| [area-dashboard](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-dashboard)                     | @JakeRadMSFT      | @aspire/area-dashboard           | Issues/PRs related to the Dashboard UI                                                                                             |
 | [area-deployment](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-deployment)                   | @davidfowl        | @aspire/area-deployment          | Issues/PRs related to deploying Aspire apps                                                                                        |
 | [area-docs](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-docs)                               | @IEvangelist      | @aspire/area-docs                | Issues/PRs related to documentation                                                                                                |
 | [area-engineering-systems](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-engineering-systems) | @joperezr         | @aspire/area-engineering-systems | Issues/PRs related to how the repository is built and tested (build and test infrastructure)                                       |
@@ -19,8 +19,8 @@ If you need to tag folks on an issue or PR, you will generally want to tag the o
 | [area-samples](https://github.com/dotnet/aspire-samples/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-samples)                 | @DamianEdwards    | @aspire/area-samples             | Issues/PRs related to the Aspire samples. These are in the [dotnet/aspire-samples](https://github.com/dotnet/aspire-samples) repo. |
 | [area-service-discovery](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-service-discovery)     | @ReubenBond       | @aspire/area-service-discovery   | Issues/PRs related to Aspire's Service Discovery and communication between services                                                |
 | [area-templates](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-templates)                     | @DamianEdwards    | @aspire/area-templates           | Issues/PRs related to the Aspire templates                                                                                         |
-| [area-telemetry](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-telemetry)                     | @samsp-msft       | @aspire/area-telemetry           | Issues/PRs related to telemetry (logs, metrics, tracing)                                                                           |
-| [area-tooling](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-tooling)                         | @vijayrkn         | @aspire/area-tooling             | Issues/PRs related to Visual Studio and Visual Studio Code tooling for Aspire                                                      |
+| [area-telemetry](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-telemetry)                     | @maddymontaquila  | @aspire/area-telemetry           | Issues/PRs related to telemetry (logs, metrics, tracing)                                                                           |
+| [area-tooling](https://github.com/dotnet/aspire/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-tooling)                         | @JakeRadMSFT      | @aspire/area-tooling             | Issues/PRs related to Visual Studio and Visual Studio Code tooling for Aspire                                                      |
 
 ## Community Triagers
 
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -7,24 +7,26 @@ These instructions will get you ready to contribute to this project. If you just
 See [machine-requirements.md](machine-requirements.md).
 
 ## Build the repo
-`.\build.cmd` (Windows) or `.\build.sh` (macOS and Linux)
+
+`.\build.sh` (macOS and Linux) or `.\build.cmd` (Windows)
 
 ## Run TestShop
 
 This will confirm that you're all set up.
 
-If you are using Visual Studio:
-
-1. Open `Aspire.slnx`
-1. Set the Startup Project to be the `AppHost` project (it's under `\playground\TestShop`). Make sure the launch profile is set to "http".
-1. <kbd>F5</kbd> to debug, or <kbd>Ctrl+F5</kbd> to launch without debugging.
+In your shell or in VS Code:
 
-Otherwise:
 ```shell
 dotnet restore playground/TestShop/TestShop.AppHost/TestShop.AppHost.csproj
 dotnet run --project playground/TestShop/TestShop.AppHost/TestShop.AppHost.csproj
 ```
 
+Or, if you are using Visual Studio:
+
+1. Open `Aspire.slnx`
+1. Set the Startup Project to be the `AppHost` project (it's under `\playground\TestShop`). Make sure the launch profile is set to "http".
+1. <kbd>F5</kbd> to debug, or <kbd>Ctrl+F5</kbd> to launch without debugging.
+
 ## View Dashboard
 
 When you start the sample app in Visual Studio, it will automatically open your browser to show the dashboard.
@@ -56,7 +58,7 @@ If you want to try local changes on a separate Aspire based project or solution
 in a local folder and use it as a package source.
 
 To do so simply execute:
-`.\build.cmd -pack` (Windows) or `.\build.sh -pack` (macOS and Linux)
+`.\build.sh -pack` (macOS and Linux) or `.\build.cmd -pack` (Windows)
 
 This will generate all the packages in the folder `./artifacts/packages/Debug/Shipping`. At this point from your solution folder run:
 
diff --git a/docs/getting-perf-traces.md b/docs/getting-perf-traces.md
@@ -1,20 +1,38 @@
 # Wall-clock time investigations
 
-## Collect the trace
-Collect the trace using PerfView (https://github.com/microsoft/perfview/releases). Use Collect menu, then Collect again, to open the collection dialog and make the following changes from defaults:
+Aspire has some built-in EventPipe providers that you can collect from during performance investigations.
+
+## Collection with dotnet trace
+
+You can use [dotnet trace](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace) to collect your managed code trace. Follow the documentation, but for extra context include the Aspire event pipe provider, as in the below example:
+
+```sh
+dotnet trace collect --providers *Microsoft-Aspire-Hosting --process-id 1234
+```
+
+or more elaborately
+```sh
+dotnet trace collect --providers Microsoft-DotNETCore-SampleProfiler:0x0000F00000000000:4,Microsoft-Windows-DotNETRuntime:0x00000014C14FCCBD:5,Microsoft-Aspire-Hosting --buffersize 8192
+```
+
+Then analyze using `dotnet trace report` or convert to a format such as Speedscope.
+
+## Collection with PerfView (Windows only)
+
+On Windows, you can collect the trace using PerfView instead (https://github.com/microsoft/perfview/releases). Use Collect menu, then Collect again, to open the collection dialog and make the following changes from defaults:
 
 1. If you do not intend to share the trace with anyone, uncheck the "Zip" and "Merge" option.
-1. Increase Circular MB to 8192.
-1. Check the "Thread Time" checkbox.
+1. Increase Circular MB to `8192`.
+1. Check the `Thread Time` checkbox.
 1. Expand Advanced Options panel and make sure you have Kernel Base, Cpu Samples, File I/O, .NET, and Task (TPL) options checked.
 1. In "Additional Providers" add `*Microsoft-Aspire-Hosting` (note the asterisk before the .NET Aspire provider name!).
 
 Once you are ready, git "Start Collection" button and run your scenario.
 
 When done with the scenario, hit "Stop Collection". Wait for PerfView to finish merging and analyzing data (the "working" status bar stops flashing).
 
-## Verify that the trace contains data .NET Aspire data
+### Verify that the trace contains data .NET Aspire data
 
 This is an optional step, but if you are wondering if your trace has been captured properly, you can check the following:
 
-1. Open the trace (usually named PerfViewData.etl, if you haven't changed the name) and double click Events view. Verify you have a bunch of events from Microsoft-Aspire-Hosting provider.
+1. Open the trace (usually named PerfViewData.etl, if you haven't changed the name) and double click Events view. Verify you have a bunch of events from the Microsoft-Aspire-Hosting provider.
diff --git a/docs/machine-requirements.md b/docs/machine-requirements.md
@@ -2,19 +2,6 @@
 
 Whether you want to contribute to Aspire, or just use the latest build of Aspire, these are the common pieces you need to install.
 
-## (Windows) Install Visual Studio
-
-On Windows, Visual Studio contains special tooling support for .NET Aspire that you will want to have.
-
-[Visual Studio 2022 version 17.12](https://visualstudio.microsoft.com/vs) or later
-
-When you install, ensure that both:
-* `ASP.NET and web development` Workload is checked.
-* `.NET Aspire SDK` component in `Individual components` is checked.
-
-## Install the latest .NET 8 SDK
-[.NET 8 SDK](https://github.com/dotnet/installer#installers-and-binaries)
-
 ## Install a supported container runtime
 
 ### Docker Desktop
@@ -27,21 +14,30 @@ When you install, ensure that both:
 * [macOS](https://podman.io/docs/installation#macos)
 * [Linux](https://podman.io/docs/installation#installing-on-linux)
 
-## (Windows / Linux / Mac) DevContainer in VS Code
+Then you can use either VS Code, Visual Studio, or Codespaces:
 
-On Windows you could also use VS Code with the DevContainers extension. This requires that you have installed a container engine.
-Currently it's only tested with Docker Desktop.
+## Using VS Code with DevContainers
+
+On Windows, Linux, or Mac you can use VS Code with the DevContainers extension. Currently it's only tested with Docker Desktop.
 
 > :warning: This will use around 16GB of RAM, after you loaded the solution.
 
-### Install VS Code with DevContainers Extension
+#### Install VS Code with DevContainers Extension
 
 * [VS Code](https://code.visualstudio.com/Download)
 * [DevContainers Extension](https://marketplace.visualstudio.com/items?itemName=ms-VSCode-remote.remote-containers)
 
-## (Browser) Codespaces
+Then choose "Open Folder In Container", choose the root of your cloned repo, then choose ".NET Aspire - Contribute".
+
+## Using Visual Studio
+
+To use Visual Studio, ensure you have [Visual Studio 2022 version 17.14](https://visualstudio.microsoft.com/vs) or later.
+
+When you install, ensure that `ASP.NET and web development` workload is checked.
+
+## Using Codespaces
 
-Just start the Codespaces in your fork. The initialization of the code space takes around 5 mins. After that you can open the solution.
+In your browser, start a Codespace in your fork. The initialization of the code space takes around 5 mins. After that you can open the solution.
 This will take on the free version of Codespace around 10 mins.
 
 > :warning: With the free version of Codespaces the development experience can be less than ideal. We recommend using at least a Codespace with 16GB of RAM or use your local VS Code / DevContainers instance.
diff --git a/docs/using-latest-daily.md b/docs/using-latest-daily.md
@@ -1,14 +1,16 @@
 # Set up your machine to use the latest Aspire builds
 
-These instructions will get you set up with the latest build of Aspire. If you just want the last preview release of .NET Aspire, the packages are on nuget.org, and install [Visual Studio 2022 version 17.12](https://visualstudio.microsoft.com/vs/preview/) or later for the tooling.
+If you just want an official release of .NET Aspire, you don't need this document. [The Aspire documentation](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview) will get you started.
+
+If you want the latest, unsupported build of Aspire to try, read on.
 
 ## Prepare the machine
 
 See [machine-requirements.md](machine-requirements.md).
 
 ## (Optional) Create a local nuget.config file
 
-Since dogfooding will require using daily build feeds, you may not want to add feeds globally which could alter how other code on your machine builds. To avoid this happening, you can create a local nuget.config file by running the following command in the root of your repository:
+Since this will require using daily build feeds, you may not want to add feeds globally which could alter how other code on your machine builds. To avoid this happening, you can create a local nuget.config file by running the following command in the root of your repository:
 
 ```bash
 dotnet new nugetconfig
@@ -42,11 +44,11 @@ dotnet new install Aspire.ProjectTemplates::*-* --force
 ```
 
 > [!TIP]
-> Release branches are a little different. For example, for the latest build from `release/X.X` branch change the above to be `Aspire.ProjectTemplates::X.X.*-*`. For example, if you want to use the latest build from the `release/9.2` branch, change the above to be `dotnet new install Aspire.ProjectTemplates::9.2.*-* --force`
+> Release branches are a little different. For example, for the latest build from `release/X.X` branch change the above to be `Aspire.ProjectTemplates::X.X.*-*`. For example, if you want to use the latest build from the `release/9.3` branch, change the above to be `dotnet new install Aspire.ProjectTemplates::9.3.*-* --force`
 
 <!-- break between blocks -->
 
-> [!NOTE]  
+> [!NOTE]
 > The `--force` parameter is required if you also have the legacy .NET Aspire Workload installed. The new templates have the same name as the old ones, so this command would override those.
 
 ## Create a new Project
@@ -84,3 +86,5 @@ Alternatively, if you are using Visual Studio, you can instead create a new Blaz
 ```sh
 dotnet tool install --global aspire.cli --prerelease --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json
 ```
+
+now `aspire` will be available as a tool.
