How to: debug C# companions

Goal: debug your .NET integrations inside the Studio through the pinned netcoredbg adapter — knowing exactly where the floor is. Every degradation on this page is named; none is silent.

Prerequisites

• A .NET 8+ companion (net8.0 or later TFMs) for direct debugging — see the net48 section below for the pattern that covers .NET Framework code.
• Launch/attach configurations in <companion>/.xppstudio/debug.json (versioned, non-secret). Start from the Projects pane’s Debug row.

The supported floor (.NET 8+)

• Launch console apps: breakpoints, step over/into/out, locals (including complex object expansion), call stack.
• Conditional breakpoints — C#-level condition expressions (e.g. line.Sku == "SKU-2"): fully supported, adapter-evaluated.
• Attach to a running process ("request": "attach" configs): the session auto-pauses right after attaching — the adapter cannot inspect a running process (0x80131302), so the Studio pauses for you and the call stack is immediately readable. Author "processId" or enter the PID when prompted. AOS-process attach remains out of scope.

DEBUG · ATTACH AUTO-PAUSEReal UI capture pending (shares capture with cs-debug-panel)cs-debug-attach

The degradations — verbatim

Logpoints are not supported

netcoredbg has no supportsLogPoints capability. A logpoint in a C# session becomes a normal stopping breakpoint, and the Studio names every converted logpoint in a toast at session start — it never silently stops instead of logging.

Hit-count conditions are not supported

No supportsHitConditionalBreakpoints capability; the adapter ignores hitCondition. Same treatment: the breakpoint becomes a plain stop-on-every-hit breakpoint and the conversion is named at session start. Expression conditions are unaffected — fully supported.

.NET Framework (net4x) processes cannot be debugged

netcoredbg is CoreCLR-only. Starting debug on a net48-only companion shows the typed state: “Debugging .NET Framework targets is unavailable — netcoredbg supports .NET (CoreCLR) only on this setup. .NET Framework library code running inside a .NET 8 host remains fully debuggable — breakpoints, stepping into library frames, locals, and conditional breakpoints all work across the assembly boundary. Build + edit remain fully supported.” The net48-interop-library + net8-host architecture is the debugging story for .NET Framework code.

Verify it worked

• A breakpoint in a net8 companion binds and pauses; locals expand.
• Attach auto-pauses; the call stack reads immediately.

If it goes wrong

• Execution stops where you set a logpoint — read the session-start toast: the conversion was named there.
• net48 debug button shows the typed state — expected; use the net8-host pattern.

Next: dotnet test · interop library.