Parithon.Aspire.Hosting.RemoteDebugging 0.0.7

Parithon.Aspire.Hosting.RemoteDebugging

A .NET Aspire hosting extension that lets you deploy, run, and remote-debug .NET projects on a remote Windows or Linux host — all from your local Aspire AppHost. Logs, traces, and metrics flow back to the Aspire dashboard via an SSH-tunnelled OpenTelemetry pipeline.

Features

• Deploy & run — builds and copies your .NET project binaries to the remote host over SSH, then launches them via a lightweight sidecar agent
• Remote debugging — installs vsdbg on the remote host automatically; attach from VS Code or Visual Studio
• OpenTelemetry tunnel — OTEL data (logs, traces, metrics) is reverse-tunnelled back to the local Aspire dashboard over the same SSH connection — no firewall rules needed
• Windows Service support — deploy and manage your project as a Windows Service via AsWindowsService()
• Log streaming — tail a Serilog log file on the remote host and stream each line to the Aspire console in real time via WithLoggingSupport()
• Parameterised credentials — SSH username and password can be stored as Aspire parameters (user secrets, environment variables)

Installation

The package is published to GitHub Packages. Add the source once:

dotnet nuget add source https://nuget.pkg.github.com/parithon/index.json \
  --name github-parithon \
  --username YOUR_GITHUB_USERNAME \
  --password $(gh auth token) \
  --store-password-in-clear-text

Then add the package to your AppHost project:

dotnet add package Parithon.Aspire.Hosting.RemoteDebugging

Quick Start

1. Configure the remote host

// AppHost/AppHost.cs
using System.Runtime.InteropServices;
using Parithon.Aspire.Hosting.RemoteDebugging.RemoteHost.Transport;

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("remote-password", secret: true);

var remoteHost = builder.AddRemoteHost("my-server", OSPlatform.Windows,
        new RemoteHostCredential("myuser", password))
    .WithEndpoint("192.168.1.100", TransportType.SSH, 22);

Store the secret locally:

dotnet user-secrets set "Parameters:remote-password" "your-password"

2. Add a remote project

builder.AddRemoteProject<MyApp>("my-app", remoteHost);

builder.Build().Run();

3. Run and attach the debugger

Press F5 in VS Code (with the C# Dev Kit extension) — the AppHost deploys the project, starts it on the remote host, and exposes the debugger port.

Windows Service

Deploy and run your project as a Windows Service:

builder.AddRemoteProject<MyWorker>("my-worker", remoteHost)
    .AsWindowsService("myworker", "My Worker Service")
    .WithLoggingSupport(
        @"C:\Windows\Logs\my-worker\app.log",
        "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")
    .WithEnvironment("service-mode", "windows");

WithLoggingSupport tails the Serilog log file on the remote host and streams each line to the Aspire console. Error and Fatal lines appear in red in the dashboard.

Your app must use Serilog with a file sink and RollingInterval.Infinite so the log file path remains stable.

API Reference

AddRemoteHost

Fluent modifiers:

AddRemoteProject<TProject>

Architecture

graph TB
    subgraph local["Local Machine"]
        apphost["Aspire AppHost\n(RemoteHostConnector)"]
        dashboard["Aspire Dashboard"]
    end

    subgraph remote["Remote Host (Windows or Linux)"]
        sidecar["aspire-sidecar\ngRPC :5055"]
        app["Your .NET Project\n(or Windows Service)"]
        tailer["PowerShell log tailer\n(Get-Content -Wait)"]
        logfile["Serilog log file"]
    end

    apphost -- "deploy binaries\n(SCP over SSH)" --> remote
    apphost -- "gRPC RPCs\n(SSH port-forward)" --> sidecar
    sidecar -- "StartProcess / StopProcess\nStreamLogs" --> app
    sidecar -- "StartProcess / StreamLogs" --> tailer
    app -- "writes" --> logfile
    tailer -- "tails" --> logfile
    app -- "OTEL\n(SSH reverse tunnel)" --> dashboard

Requirements

Local machine

• .NET 10 SDK
• .NET Aspire 13+
• Network access to the remote host on the SSH port (default: 22)

Remote host

Additional requirements for AsWindowsService

License

MIT

Security

See docs/threat-model.md for the full threat model. This tool is intended for development use only on trusted networks.

SSH Host Key Verification

Host keys are validated against your ~/.ssh/known_hosts file automatically — the same behaviour as the ssh command. Add the remote host before first use:

ssh-keyscan -H <remote-host> >> ~/.ssh/known_hosts

On mismatch the connection is rejected with an error log warning of a possible MITM attack. On first connect (host not in known_hosts) the connection succeeds with a warning suggesting you run ssh-keyscan.

For CI/CD environments where known_hosts is not available, use an explicit fingerprint pin:

builder.AddRemoteHost("my-server", OSPlatform.Windows, credential)
    .WithEndpoint("192.168.1.100", TransportType.SSH, 22)
    .WithHostKeyFingerprint("abc123...your-sha256-fingerprint");

Obtain the fingerprint with:

ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -