====== Visual Studio Code .NET Remote Debug Configurator ======

===== Download =====

{{ https://downloads.comfiletech.com/dotnet/vscode-remote-debug-configurator/releases/dotnet-remote-debug-config-1.0.0.vsix | Download dotnet-remote-debug-config-1.0.0.vsix }}

===== Overview =====

Visual Studio Code, with existing C# extensions, already has the ability to deploy to, launch, and debug an application on a remote target device.  However, setting it up requires laboriously editing the //.vscode/tasks.json// and //.vscode/launch.json// files.  

The .NET Remote Debug Configurator is a Visual Studio Code extension that simplifies the process of configuring remote .NET debugging sessions. Instead of manually editing JSON configuration files, developers only need to fill out a form.

{{ :cfnet:cfheader:vscode_remote_debug_configurator:form.png?nolink |}}

Visual Studio Code also has the ability [[https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack|remotely develop and debug applications on a remote target]], but on resource constrained devices, performance is slow, consumes too many resources on the target target, and it interferes with the normal operation of the application on the remote target.

Development should be done on a resource abundant development PC.  The development PC will quickly build the application, deploy it to the remote target, launch it on the remote target, and attach the debugger with a single //F5// keystroke.  This extension makes setting that up a matter of simply filling out of small form.


===== Prerequisites =====

==== Setup Passwordless SSH Login ====

This extension requires [[https://wiki.debian.org/Setup%20SSH%20Passwordless%20Login|Setup passwordless SSH login]] to avoid having to store a password insecurely in the target's configuration.

  - On your development PC, generate a key pair <code>ssh-keygen -t rsa</code>  The key pair will likely be stored in your user profile's home directory (i.e. ''$HOME/.ssh'' or on Windows ''C:\Users\{Username}\.ssh'').
  - Copy the public key to the remote target. Don't miss the trailing colon. <code>scp $HOME/.ssh/id_rsa.pub admin@{remote_target_ip_address}:</code>
  - Register the public key as an authorized key on the remote target.  On the remote target, run <code>mkdir .ssh && cat id_rsa.pub >> .ssh/authorized_keys</code>
  - The next time you start an SSH session from your remote device, you should not be asked to authenticate with a password.

{{ https://downloads.comfiletech.com/jPC/videos/jpc_passwordless_setup.mp4?872x856 }}


==== Install vsdbg on Remote Target ====

This extension requires Microsoft's vsdbg to be installed on the remote target.  It is usually installed by default on COMFILE Technology's products.  But if it's not, run the following command on the remote target to install it.  

<code bash>
curl -sSL https://aka.ms/getvsdbgsh | sudo bash /dev/stdin -v latest -l /opt/Microsoft/vsdbg/
</code>

You can install it to a different location by changing the ''-l'' parameter. If you install it to a different location, then be sure to specify the location when configuring your remote target.

===== How to Use =====

==== Installation ====

=== Download the Extension ===

{{ https://downloads.comfiletech.com/dotnet/vscode-remote-debug-configurator/releases/dotnet-remote-debug-config-1.0.0.vsix | Download dotnet-remote-debug-config-1.0.0.vsix }}

=== Install the Extension ===

  - From the Extensions side panel in Visual Studio Code, select //Install from VSIX//.{{ :cfnet:cfheader:vscode_remote_debug_configurator:install_vsix.png?nolink |}}
  - Browse to the downloaded .vsix file and press the "Install" button.


==== Create A Remote Debug Target ====

  - Open your .NET project in Visual Studio Code
  - Press ''Ctrl+Shift+P'' to open the command palette
  - Type ''.NET Remote Debug Configurator'' and/or select //.NET Remote Debug Configurator// from the dropdown menu
  - Fill out the configuration form with your remote debugging details


==== Manage Existing Configurations ====

When you open the configurator and have existing remote debug targets:

  - Use the //Remote Target// dropdown to select which configuration to edit
  - Modify any fields and click //Save Configuration// or press //Enter// to update
  - Click //Delete// to remove a configuration and all its associated tasks

==== Start a Remote Debug Session ====

  - Go to the //Run and Debug// panel (''Ctrl+Shift+D'')
  - Select your remote debug configuration from the dropdown at the top
  - Press //F5// or click the green //Start Debugging// button

The extension will automatically:
  - Deploy your application to the remote machine via SSH
  - Start the application on the remote machine
  - Attach the VS Code debugger through the SSH tunnel
  - Connect you to the remote debugging session


==== Configuration Marking System ====

The extension uses a special comment marker (<html><code>// Managed by dotnet-remote-debug-config</code></html>) to identify configurations and tasks it creates. This allows it to:

  * Distinguish between extension-managed and user-created configurations
  * Safely update or delete only its own configurations
  * Automatically clean up associated tasks when deleting a debug profile

Please don't remote those comments from the .json files unless you no longer want this extension to manage those configurations.