Rider .NET Debugger Architecture: Minimal Agent Design for Local and Remote Debugging

The problem Rider solves for .NET debugging

Rider must launch or attach to .NET CLR and .NET Core processes, map PDB symbols to source, show threads and async/await call stacks, set breakpoints, evaluate expressions, and support Hot Reload, without requiring Visual Studio to be installed. The useful takeaway is that Rider keeps the IDE UI client-side and delegates process inspection to a small local debug agent that speaks Microsoft's debugger protocols.

Requirements that shape the design

Functional requirements are process control and inspection. Rider needs to start a debuggee under its own launch configuration or attach to a running process, resolve symbols from PDB files and symbol servers, present managed call stacks including async continuations, allow breakpoint placement by source location, and evaluate expressions in the debuggee context. Hot Reload is a secondary requirement that depends on runtime support.

Non-functional requirements are isolation and portability. The debugger must not require Visual Studio installation, must work on Windows, macOS and Linux where the runtime is supported, and must keep source code and user input separate from untrusted process memory.

Smallest suitable design

The minimal design pairs Rider's UI with the .NET Core Debugger protocol and Microsoft's Visual Studio Debugger API. A local debug agent process is spawned per debugging session. The agent loads the Microsoft debugging components, attaches to or launches the target CLR/Core process, and relays inspection data to Rider.

Communication uses named pipes on Windows and TCP sockets on other platforms for local debugging. For remote debugging, the agent runs on the target host and Rider connects over TCP. Symbol resolution and source lookup stay client-side in Rider to avoid shipping source to remote hosts unnecessarily.

An example run configuration for local debugging contains transport type, process ID or launch profile, symbol paths, and source root mappings. A Docker Compose run configuration switches the transport to TCP and adds host mapping for the agent port, while keeping symbol resolution in Rider.

Trust and data boundaries

The debuggee process is untrusted. Data flows are directional and explicit. From Rider to agent: source file paths, environment variables, launch arguments, breakpoint locations, and evaluated expressions entered by the user. From agent to Rider: process memory reads, thread state, stack frames, variable values, and exception notifications.

Attach requires explicit user consent in Rider's Attach to Process dialog. Remote connections require the user to provide host, port and credentials. The agent does not persist source code and does not write back to the debuggee except for Hot Reload edits, which are gated by runtime capability checks.

Operational checks

Rider surfaces health signals in the debug tool window and console.

• Symbol server accessibility: verify that symbol paths are reachable before attach and that PDBs match the loaded assemblies. Mismatches are reported as missing source.
• Process attach permissions: check that the current user can attach to the target process on the host OS. Permission denied is surfaced as an attach failure.
• Source file availability: confirm that source roots mapped in the run configuration resolve to files on disk for the active build configuration.
• Transport health: monitor named pipe or TCP connection liveness between IDE and agent. Disconnects are reported as transport errors.

Practical verification can be done by creating a simple .NET console app in Rider, setting a breakpoint, starting debug and inspecting variable inspection and async stack display. Attaching to a running dotnet process via the Attach to Process dialog shows permission prompts and attach success or failure messages. Comparing a local run configuration with a Docker Compose run configuration shows transport switching and symbol resolution messages in the debug console.

Failure modes

Symbol mismatches cause breakpoints to appear unbound and source to show as unavailable. This occurs when PDBs do not match the running assembly or symbol servers are unreachable.

Process exit during attach leaves the agent without a target and Rider reports a detached session.

Permission denied on remote hosts prevents attach. This is outside Rider and depends on OS access controls, firewall rules and credentials.

Transport disconnects drop the debugging session. Named pipe failures are common when the agent process terminates unexpectedly; TCP failures occur with network interruption.

Conditions that would change the design

The minimal agent design would need to change if requirements expand beyond managed debugging. Kernel debugging, deep cross-platform native interop inspection, or zero-trust network debugging requiring signed debug sessions would require a privileged agent, additional authentication layers, and different data boundaries.

Behavior is version-sensitive across Rider, .NET SDK and runtime. Debugger protocol capabilities and Hot Reload support evolve between releases. Hot Reload and Edit and Continue support varies by language, project type and runtime version, limiting guarantees of the minimal design.

Remote debugging assumes network trust. Credentials, firewall rules and host access controls are outside Rider and must be managed separately.