Add Developer Experience docs: debugging, startup performance, and hot reload by Copilot · Pull Request #464 · microsoft/aspire.dev

Copilot · 2026-02-20T21:49:20Z

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.mdx`

IDE coverage: Visual Studio (F5 + attach), VS Code (launch.json via Aspire extension), JetBrains Rider (2024.1+ native support), Neovim/DAP (--start-debug-session + process attach)
Linux-only project debugging: native Linux, Docker remote debugger with vsdbg (multi-stage Dockerfile publishing with -c Debug to include .pdb symbol files), WSL2 + VS Code Remote
Selective debugging: run with aspire run, then attach to specific process; explains that only AddProject<T>() resources get debugger attachment
Common issues: breakpoints not hit, debugger detach, port conflicts, Aspire dashboard as fallback diagnostics

`fundamentals/startup-performance.mdx`

NuGet: cache inspection (dotnet nuget locals), pinning away from floating versions, mirror/proxy config
Containers: pre-pull images, pin tags to avoid remote checks, persistent containers to skip per-run init
CI/CD: GitHub Actions NuGet cache pattern, dotnet restore --verbosity detailed for diagnosing slow restores
AppHost: trim resource count during development, aspire doctor

`fundamentals/hot-reload.mdx`

Caution note: .NET hot reload within Aspire has known limitations and open issues; workarounds are more reliable
Supported: per-service dotnet watch run in a separate terminal, Blazor CSS/Razor hot reload
Limitations: AppHost itself cannot hot reload (requires restart on topology changes), container/executable resources excluded, unsupported C# change categories trigger full restart
Workarounds: persistent containers + minimal service set to reduce restart cost

Sidebar

Three entries added to the Fundamentals section in docs.topics.ts.

Original prompt

This section details on the original issue you should resolve

<issue_title>[GitHub Discussions] Developer Experience & Tooling gaps</issue_title>
<issue_description>## Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic Questions

DevEx/Tooling 60 total

Performance/Slow 15+

Debugging 10+

IDE Issues 10+

CLI 15+

Critical Gaps

1. Γ¥î Debugging Guide (CRITICAL)

Discussions:

Allow running and debugging a Linux-only project on aspire dotnet/aspire#12561: Allow running and debugging a Linux-only project on aspire

Localized file check-in by OneLocBuild Task: Build definition ID 1309: Build ID 2816277 dotnet/aspire#12039: .Net Aspire Single Service Nvim Debugging

Is this a bug? dotnet/aspire#9846: Is this a bug?

Customer Questions:

Debugging specific services

Selective debugging (debug some, not others)

Linux-only project debugging

Non-VS debugging (Neovim, etc.)

Action Items:

Debugging guide (all IDEs)

Selective service debugging

Linux debugging patterns

Non-VS IDE debugging

2. Γ¥î Performance/Slow Startup (15+ questions)

Discussions:

Why are Aspire projects taking so long to be restored? It's more than 2 mins every single time. dotnet/aspire#12518: Why are Aspire projects taking so long to be restored? It's more than 2 mins every single time

Optimizing app host start up time dotnet/aspire#13840: Optimizing app host start up time

Customer Questions:

NuGet restore taking too long

App host startup optimization

Container pull slowness

Action Items:

Performance optimization guide

NuGet restore troubleshooting

Startup optimization patterns

3. ΓÜá∩╕Å IDE-Specific Issues

Discussions:

Using GH Copilot in Aspire in Rider and other IDEs dotnet/aspire#10168: Using GH Copilot in Aspire in Rider and other IDEs

Rider, VS Code extension issues mentioned across discussions

Customer Questions:

Rider integration

VS Code extension issues

GitHub Copilot integration

Action Items:

IDE comparison guide

Rider-specific documentation

VS Code troubleshooting

4. ΓÜá∩╕Å Watch Mode / Hot Reload

No dedicated discussions, but Discord shows high demand (42 questions)

Action Items:

Watch mode current status

Hot reload limitations

Workarounds

Data Source

GitHub Discussions: 820 total

DevEx-related: 60 discussions

Date range: Project inception - February 2026
</issue_description>

<agent_instructions>Please address this issue, while using the .github/skills/doc-writer/SKILL.md. Be certain to also take into account, related issues, pull requests, and comments that are directly linked as well as comments.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes [GitHub Discussions] Developer Experience & Tooling gaps #351

💡 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.

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

IEvangelist

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

IEvangelist · 2026-02-21T02:35:01Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+<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>).


Please import the { Kbd } component and use that instead <kbd> throughout this doc.

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>

Copilot · 2026-02-21T02:41:14Z

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

Doc-tester validation complete (823379b). Two issues were found and fixed:

startup-performance.mdx — Removed the "Disable the dashboard for headless scenarios" subsection which referenced aspire run --no-dashboard, a flag that doesn't exist in aspire run (confirmed against the CLI reference docs).
hot-reload.mdx — Removed the misleading WithEnvironment("DOTNET_WATCH", "1") AppHost code example. Setting that env var on a project resource does not invoke dotnet watch or enable hot reload — the correct approach (running dotnet watch run in a separate terminal) is now the sole recommendation in that section.

All internal links, imports, Kbd usage, and other technical claims passed validation.

IEvangelist

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

IEvangelist · 2026-02-24T01:52:13Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+
+<Steps>
+
+1. Open your Aspire solution (`.sln`) in Visual Studio.


Suggested change

1. Open your Aspire solution (`.sln`) in Visual Studio.

1. Open your Aspire solution (`.sln` or `.slnx`) in Visual Studio.

Done in 784b660.

IEvangelist · 2026-02-27T13:50:57Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+
+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**.


Suggested change

1. Press **F5** or select **Debug** > **Start Debugging**.

1. Press <Kbd window='F5' /> or select **Debug** > **Start Debugging**.

Done in 784b660 — using <Kbd windows='F5' /> to match the pattern used elsewhere in the docs.

IEvangelist · 2026-02-27T13:53:26Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+
+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.


Suggested change

1. Press **Shift+F9** or select **Run** > **Debug** to start debugging.

1. Press <Kbd window='Shift+F9' /> or select **Run** > **Debug** to start debugging.

Done in 784b660.

IEvangelist · 2026-02-27T13:53:58Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+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


Suggested change

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS debug

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS debug

Done in 784b660.

IEvangelist · 2026-02-27T13:59:05Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+    WORKDIR /app
+    EXPOSE 4024
+    # Install vsdbg (the .NET debugger)
+    RUN curl -sSL https://aka.ms/getvsdbg | bash /dev/stdin -v latest -l /vsdbg


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

Fixed in 784b660 — updated to apt-get install -y unzip + https://aka.ms/getvsdbgsh.

IEvangelist · 2026-02-27T14:02:43Z

src/frontend/src/content/docs/fundamentals/hot-reload.mdx

+## 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)


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).

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>

Copilot · 2026-02-27T14:09:29Z

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

Doc-tester re-run complete on commit 784b660 — all checks pass:

✅ <Kbd> imports and props correct throughout debug-aspire-apps.mdx
✅ All internal links resolve
✅ No unused imports
✅ vsdbg Dockerfile uses correct aka.ms/getvsdbgsh URL with apt-get install unzip
✅ Previously-flagged issues (--no-dashboard, WithEnvironment("DOTNET_WATCH","1")) confirmed absent
✅ <Aside type="caution"> present in hot-reload.mdx about known .NET hot reload limitations
✅ All code examples syntactically correct and accurate vs CLI reference docs

IEvangelist · 2026-02-27T14:11:35Z

src/frontend/src/content/docs/fundamentals/debug-aspire-apps.mdx

+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"]
+    ```


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

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>

Initial plan

a190f29

Copilot AI assigned Copilot and IEvangelist Feb 20, 2026

Copilot started work on behalf of IEvangelist February 20, 2026 21:49 View session

Add debugging, startup performance, and hot reload documentation

a0dc953

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add debugging guide for developer experience gaps~~ Add Developer Experience docs: debugging, startup performance, and hot reload Feb 20, 2026

Copilot AI requested a review from IEvangelist February 20, 2026 21:58

Copilot finished work on behalf of IEvangelist February 20, 2026 21:58

IEvangelist reviewed Feb 21, 2026

View reviewed changes

Copilot started work on behalf of IEvangelist February 21, 2026 02:36 View session

Copilot AI and others added 2 commits February 21, 2026 02:37

Replace kbd with Kbd component in debug-aspire-apps.mdx

cf34df5

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Fix doc-tester findings: remove invalid --no-dashboard flag and misle…

823379b

…ading DOTNET_WATCH example Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot AI requested a review from IEvangelist February 21, 2026 02:41

Copilot finished work on behalf of IEvangelist February 21, 2026 02:41

IEvangelist reviewed Feb 27, 2026

View reviewed changes

Copilot started work on behalf of IEvangelist February 27, 2026 14:05 View session

Apply review suggestions: Kbd shortcuts, .slnx, vsdbg fix, hot reload…

784b660

… caution note Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot AI requested a review from IEvangelist February 27, 2026 14:10

Copilot finished work on behalf of IEvangelist February 27, 2026 14:10

IEvangelist reviewed Feb 27, 2026

View reviewed changes

Copilot started work on behalf of IEvangelist February 27, 2026 14:12 View session

Expand Linux remote debug Dockerfile with multi-stage build, Debug co…

2e65512

…nfig, and pdb files Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot AI requested a review from IEvangelist February 27, 2026 14:14

Copilot finished work on behalf of IEvangelist February 27, 2026 14:14

Topic	Questions
DevEx/Tooling	60 total
Performance/Slow	15+
Debugging	10+
IDE Issues	10+
CLI	15+


		<Steps>

		1. Open your Aspire solution (`.sln`) in Visual Studio.

	1. Open your Aspire solution (`.sln`) in Visual Studio.
	1. Open your Aspire solution (`.sln` or `.slnx`) in Visual Studio.

	1. Press F5 or select Debug > Start Debugging.
	1. Press <Kbd window='F5' /> or select Debug > Start Debugging.

	1. Press Shift+F9 or select Run > Debug to start debugging.
	1. Press <Kbd window='Shift+F9' /> or select Run > Debug to start debugging.

	FROM mcr.microsoft.com/dotnet/sdk:9.0 AS debug
	FROM mcr.microsoft.com/dotnet/sdk:10.0 AS debug

Conversation

Copilot AI commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New pages

fundamentals/debug-aspire-apps.mdx

fundamentals/startup-performance.mdx

fundamentals/hot-reload.mdx

Sidebar

Critical Gaps

1. Γ¥î Debugging Guide (CRITICAL)

2. Γ¥î Performance/Slow Startup (15+ questions)

3. ΓÜá∩╕Å IDE-Specific Issues

4. ΓÜá∩╕Å Watch Mode / Hot Reload

Data Source

Comments on the Issue (you are @copilot in this section)

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 21, 2026

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 20, 2026 •

edited

Loading

`fundamentals/debug-aspire-apps.mdx`

`fundamentals/startup-performance.mdx`

`fundamentals/hot-reload.mdx`