Add Developer Experience docs: debugging, startup performance, and hot reload - #464
Add Developer Experience docs: debugging, startup performance, and hot reload#464David Pine (IEvangelist) with Copilot wants to merge 9 commits into
Conversation
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback. Copilot
| <Steps> | ||
|
|
||
| 1. Install the [Aspire VS Code extension](/get-started/aspire-vscode-extension/). | ||
| 1. Open the Command Palette (<kbd>Ctrl+Shift+P</kbd> / <kbd>Cmd+Shift+P</kbd>). |
There was a problem hiding this comment.
Please import the { Kbd } component and use that instead <kbd> throughout this doc.
There was a problem hiding this comment.
Done in cf34df5 — imported { Kbd } from starlight-kbd/components and replaced all three <kbd> instances with <Kbd windows='...' mac='...' /> props.
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
…ading DOTNET_WATCH example Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Doc-tester validation complete (823379b). Two issues were found and fixed:
All internal links, imports, |
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. Copilot
|
|
||
| <Steps> | ||
|
|
||
| 1. Open your Aspire solution (`.sln`) in Visual Studio. |
There was a problem hiding this comment.
| 1. Open your Aspire solution (`.sln`) in Visual Studio. | |
| 1. Open your Aspire solution (`.sln` or `.slnx`) in Visual Studio. |
|
|
||
| 1. Open your Aspire solution (`.sln`) in Visual Studio. | ||
| 1. Set the AppHost project as the startup project if it isn't already. | ||
| 1. Press **F5** or select **Debug** > **Start Debugging**. |
There was a problem hiding this comment.
| 1. Press **F5** or select **Debug** > **Start Debugging**. | |
| 1. Press <Kbd window='F5' /> or select **Debug** > **Start Debugging**. |
There was a problem hiding this comment.
Done in 784b660 — using <Kbd windows='F5' /> to match the pattern used elsewhere in the docs.
|
|
||
| 1. Open your Aspire solution in Rider. | ||
| 1. In the **Run/Debug Configurations** dropdown, select the AppHost project configuration. | ||
| 1. Press **Shift+F9** or select **Run** > **Debug** to start debugging. |
There was a problem hiding this comment.
| 1. Press **Shift+F9** or select **Run** > **Debug** to start debugging. | |
| 1. Press <Kbd window='Shift+F9' /> or select **Run** > **Debug** to start debugging. |
| 1. Add a development-time Dockerfile for your Linux service that includes the .NET debugger tools: | ||
|
|
||
| ```dockerfile title="Dockerfile — Linux service with debugger" | ||
| FROM mcr.microsoft.com/dotnet/sdk:9.0 AS debug |
There was a problem hiding this comment.
| FROM mcr.microsoft.com/dotnet/sdk:9.0 AS debug | |
| FROM mcr.microsoft.com/dotnet/sdk:10.0 AS debug |
| WORKDIR /app | ||
| EXPOSE 4024 | ||
| # Install vsdbg (the .NET debugger) | ||
| RUN curl -sSL https://aka.ms/getvsdbg | bash /dev/stdin -v latest -l /vsdbg |
There was a problem hiding this comment.
This run command is wrong since the aka.ms link is 404, should instead be something like this:
RUN apt-get update \
&& apt-get install -y unzip \
&& curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg
There was a problem hiding this comment.
Fixed in 784b660 — updated to apt-get install -y unzip + https://aka.ms/getvsdbgsh.
| ## What is hot reload? | ||
|
|
||
| .NET hot reload lets you apply code changes to a running application without stopping and restarting it. It works by patching the running process in place. There are two related features: | ||
|
|
||
| - **.NET Hot Reload** — applies C# code changes to a running .NET process during a debug session or via `dotnet watch` | ||
| - **Browser hot reload (CSS/Razor)** — applies CSS and Razor component changes to the browser without a page refresh (supported in Blazor and ASP.NET Core) |
There was a problem hiding this comment.
I haven't tried this with .NET (and I know there's been issues with it in the past - still seeing nearly 30 open issues: https://github.com/dotnet/aspire/issues?q=is%3Aissue%20state%3Aopen%20hot%20reload). I've had more success with JS/TS apps using their native hot reload and that just works (but it's really unrelated to Aspire).
There was a problem hiding this comment.
Added a <Aside type="caution"> at the top of the "Hot reload with Aspire" section in 784b660 to reflect that .NET hot reload has known limitations and open issues within Aspire, and that the workarounds (persistent containers, minimal service sets) are more reliable.
… caution note Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Doc-tester re-run complete on commit 784b660 — all checks pass:
|
| 1. Add a development-time Dockerfile for your Linux service that includes the .NET debugger tools: | ||
|
|
||
| ```dockerfile title="Dockerfile — Linux service with debugger" | ||
| FROM mcr.microsoft.com/dotnet/sdk:10.0 AS debug | ||
| WORKDIR /app | ||
| EXPOSE 4024 | ||
| # Install vsdbg (the .NET debugger) | ||
| RUN apt-get update \ | ||
| && apt-get install -y unzip \ | ||
| && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg | ||
| ENTRYPOINT ["dotnet", "MyLinuxService.dll"] | ||
| ``` |
There was a problem hiding this comment.
I think we may also want to mention something about being sure that in these scenarios, the Dockerfile publishes with -c Debug and copies the .pdb files. Right? Copilot
There was a problem hiding this comment.
Done in 2e65512. Expanded the Dockerfile into a proper multi-stage build: a build stage runs dotnet publish -c Debug so .pdb symbol files are included in the output, and the debug stage copies the published output (assemblies + pdbs) before installing vsdbg. Added an inline explanation that the Debug configuration is required for the remote debugger to map execution back to source.
…nfig, and pdb files Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds new Developer Experience documentation covering debugging workflows, startup performance optimization, and hot reload/watch-mode limitations for Aspire applications.
Changes:
- Adds new fundamentals pages for debugging, startup performance, and hot reload.
- Documents IDE-specific debugging flows, container/startup optimization tips, and hot reload workarounds.
- Adds the three new pages to the Fundamentals sidebar.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 13 comments.
| File | Description |
|---|---|
src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx |
New guide for debugging Aspire apps across IDEs and environments. |
src/frontend/src/content/docs/fundamentals/startup-performance.mdx |
New guide for improving restore, build, container pull, and AppHost startup performance. |
src/frontend/src/content/docs/fundamentals/hot-reload.mdx |
New guide explaining hot reload/watch mode capabilities and limitations. |
src/frontend/config/sidebar/docs.topics.ts |
Adds the new fundamentals pages to the docs sidebar. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 1. Run the service with watch: | ||
|
|
||
| ```bash title="Bash — Start with hot reload" | ||
| dotnet watch run |
| 1. Run the Aspire solution so containers and other services start. | ||
| 1. In a separate terminal, run the Blazor project with watch: | ||
|
|
||
| ```bash title="Bash — Blazor hot reload" | ||
| cd src/MyApp.Web | ||
| dotnet watch run |
|
|
||
| ### Pin container image versions | ||
|
|
||
| Using `latest` or a floating tag forces the container runtime to check for updates. Pin to a specific digest or version tag to use the cached image: |
| If restore consistently takes over 2 minutes even after the first run, check: | ||
|
|
||
| - **NuGet cache is working**: Run `dotnet nuget locals all --list` to confirm the cache directory is accessible. | ||
| - **No floating versions**: Search for `*` or `latest` version constraints in your project files. |
| && apt-get install -y unzip \ | ||
| && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg |
| <PackageReference Include="Aspire.Hosting.Redis" Version="*" /> | ||
|
|
||
| <!-- Fast: resolves from local cache immediately --> | ||
| <PackageReference Include="Aspire.Hosting.Redis" Version="9.3.1" /> |
|
|
||
| ### Set breakpoints across services | ||
|
|
||
| Visual Studio allows you to set breakpoints in any service project. When a breakpoint is hit, Visual Studio pauses that service's execution, while all other services continue to run normally. |
| builder.Build().Run(); | ||
| ``` | ||
|
|
||
| Containers (like Redis and PostgreSQL above) never have the .NET debugger attached by default. Only `.AddProject<T>()` resources receive debugger attachment. |
|
|
||
| ### Cannot debug a service | ||
|
|
||
| - Confirm the service is added with `AddProject<T>()`, not as a container or executable, for automatic debugger attachment. |
|
|
||
| ### Start a VS Code debug session from the CLI | ||
|
|
||
| If you're using VS Code or an editor that supports the VS Code debug adapter protocol, you can start a debug session from the terminal: |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
![aspire-repo-bot[bot]](https://avatars.githubusercontent.com/in/3085065?s=60&v=4){kind=small}
|
|
||
| ## Debug in JetBrains Rider | ||
|
|
||
| JetBrains Rider includes Aspire support through its bundled .NET Aspire plugin. You can run and debug Aspire solutions directly from the IDE. |
There was a problem hiding this comment.
Use "Aspire" instead of ".NET Aspire".
| JetBrains Rider includes Aspire support through its bundled .NET Aspire plugin. You can run and debug Aspire solutions directly from the IDE. | |
| JetBrains Rider includes Aspire support through its bundled Aspire plugin. You can run and debug Aspire solutions directly from the IDE. |
|
|
||
| ### Troubleshooting Rider | ||
|
|
||
| - **Missing run configuration**: If no Aspire run configuration appears, update Rider and ensure the bundled [.NET Aspire plugin](https://plugins.jetbrains.com/plugin/23289--net-aspire) is enabled under **Settings** > **Plugins** > **Installed**. |
There was a problem hiding this comment.
Use "Aspire" instead of ".NET Aspire".
| - **Missing run configuration**: If no Aspire run configuration appears, update Rider and ensure the bundled [.NET Aspire plugin](https://plugins.jetbrains.com/plugin/23289--net-aspire) is enabled under **Settings** > **Plugins** > **Installed**. | |
| - **Missing run configuration**: If no Aspire run configuration appears, update Rider and ensure the bundled [Aspire plugin](https://plugins.jetbrains.com/plugin/23289--net-aspire) is enabled under **Settings** > **Plugins** > **Installed**. |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
Addresses documentation gaps surfaced by 60+ GitHub Discussions on DevEx/tooling — no guides existed for debugging across IDEs, diagnosing slow startups, or understanding hot reload limitations.
New pages
fundamentals/debug-aspire-apps.mdxlaunch.jsonvia Aspire extension), JetBrains Rider (2024.1+ native support), Neovim/DAP (--start-debug-session+ process attach)vsdbg(multi-stage Dockerfile publishing with-c Debugto include.pdbsymbol files), WSL2 + VS Code Remoteaspire run, then attach to specific process; explains that onlyAddProject<T>()resources get debugger attachmentfundamentals/startup-performance.mdxdotnet nuget locals), pinning away from floating versions, mirror/proxy configdotnet restore --verbosity detailedfor diagnosing slow restoresaspire doctorfundamentals/hot-reload.mdxdotnet watch runin a separate terminal, Blazor CSS/Razor hot reloadSidebar
Three entries added to the Fundamentals section in
docs.topics.ts.Original prompt
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.