Skip to content

Document VS Code resource debugger attach and editor-assistance language model tools (Aspire 17.0) #2187

Open

Description

Summary

Aspire 17.0 (VS Code extension 1.24.0+/1.25.0+) adds two VS Code features. aspire.dev lists their tool names (via #2150 on release/17.0) but doesn't document how to use them:

  • Add VS Code resource debugging for .NET and Go aspire#18602 adds Attach debugger for running .NET and Go resources, in the Aspire view and through the aspire_resource_debug (#aspireDebugResource) language model tool. Shipped in extension v1.25.0.
  • Add Aspire editor assistance language model tools aspire#19414 adds six editor-assistance language model tools and hardens aspire_apphost_start and aspire_apphost_stop. The six new tools are aspire_debug_session_status, aspire_explain_launch_failure, aspire_open_dashboard, aspire_open_output, aspire_list_debug_sessions, and aspire_hot_reload_status. Shipped in extension v1.24.0.

What exists today

  • release/17.0, get-started/aspire-vscode-extension.mdx, section "Let coding agents use Aspire language model tools": a 9-tool table, the start tool's inputs, the confirmation list, and a one-line privacy statement.
  • main (live site): only aspire_apphost_start and aspire_apphost_stop.
  • whats-new/aspire-17.mdx: no LM-tool coverage. Open Fill gaps in What's new in Aspire 17.0 #2177 adds one bullet about attach.

Gaps

  1. Attach debugger tree action. The Aspire view's right-click list doesn't mention Attach debugger for running .NET project and Go resources. Its progress, cancellation, and "a debugger is already attached" behavior aren't documented either.
  2. Prerequisites and retry.
    • .NET needs the C# extension (ms-dotnettools.csharp).
    • Go needs the Go extension (golang.go) and Delve.
    • When the debugger extension is missing, a notification opens Extensions. After installing or enabling it, retry. The AppHost doesn't need to restart.
  3. Works without a debug session. Attach works for resources started with Run Without Debugging or aspire start. It targets the app process, not the dotnet run, dotnet watch, or go run launcher. It doesn't restart the resource, and the tool never starts or restarts one.
  4. Limitations.
  5. Linux permissions. Under Ubuntu's default kernel.yama.ptrace_scope=1, Delve can't attach to a DCP-launched Go resource. Document the requirement and the trade-off. The product's CI sets ptrace_scope=0. For macOS: in validation on macOS 27 (arm64), Delve attach to a DCP-launched Go resource succeeded with DevToolsSecurity disabled for an account in the _developer group; accounts outside that group may get a Developer Tools Access authorization prompt. Consider a short note.
  6. Go integration. integrations/frameworks/go/go-host.mdx → "Debug Go apps" describes only F5 debugging. Add attach-later guidance:
    • Run Without Debugging uses DCP-managed go run.
    • Symbols and DWARF are retained by default, including under aspire start.
    • Custom ldFlags must keep -s=false -w=false.
    • Use gcFlags: "all=-N -l" for predictable stepping.
    • Attach is mutually exclusive with WithDelveServer.
      Source: src/Aspire.Hosting.Go/README.md, "Debugging".
  7. Tool details.
    • Inputs:
      • aspire_resource_debug takes appHostPath, resourceName, and strategy (auto or attach).
      • status takes appHostPath and an optional resourceName.
      • Hot Reload takes an optional resourceName and appHostPath, with its disambiguation rules.
    • Common outcomes:
      • started, alreadyDebugging, resourceNotRunning, debuggerExtensionMissing, unsupportedResource, unknownAppHost.
      • Hot Reload applicable, notApplicable, noEditorControlledResource.
      • Explain failureFound, noRecordedFailure.
  8. Hot Reload status semantics.
    • Enabled doesn't mean applicable.
    • Only .NET project resources debugged by this editor qualify. A resource started without the debugger reports notApplicable.
    • Externally controlled AppHosts fail closed.
    • The fallback order is restart the resource first, then rebuild and restart the AppHost.
    • Cross-link from app-host/hot-reload-and-watch.mdx → "IDE hot reload and debugging".
  9. Launch-failure explanation. Only the latest sanitized failure per AppHost is kept, for 30 minutes. The result is a stage, a category, and fixed recommended actions. Raw compiler errors aren't returned; point users to the Output panel and CLI logs.
  10. Dashboard and Output tools.
    • Dashboard works only for editor-controlled running AppHosts, uses the configured presentation (external browser by default), and never returns the URL. It needs no confirmation.
    • Output confirms, then selects the "Aspire Extension" channel without reading it.
  11. Versions. State the minimum extension version for each feature: v1.24.0 for the editor-assistance tools, v1.25.0 for resource attach. Also state that Go attach-later requires 17.0 hosting.
  12. aspire describe (optional). Resource JSON now includes project.launchCommand (run, watch, ide, direct, or null), project.configuration, and project.targetFramework. Source: docs/specs/cli-output-formats.md in microsoft/aspire.
  13. What's new 17.0. Add a "VS Code extension" entry covering resource attach and the editor-assistance tools, or extend Fill gaps in What's new in Aspire 17.0 #2177.

Suggested locations and outline

  • get-started/aspire-vscode-extension.mdx
    • New subsection "Attach a debugger to a running resource", under "The Aspire view" or "Run, debug, and deploy". Cover gaps 1–5.
    • Extend the "Language coverage" table with an "Attach to running resource" column: .NET ✔, Go ✔.
    • Under the LM tools section, add per-tool input/outcome details, Hot Reload semantics, failure retention, and dashboard/output behavior (gaps 7–11). A collapsible reference is enough.
  • integrations/frameworks/go/go-host.mdx → "Debug Go apps" → new "Attach to a running Go resource (VS Code)" subsection (gap 6).
  • app-host/hot-reload-and-watch.mdx → "IDE hot reload and debugging" → short paragraph and link (gap 8).
  • reference/cli/commands/aspire-describe.mdx → resource property notes (gap 12, optional).
  • whats-new/aspire-17.mdx (gap 13).

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions