Adding Debug support cross platform (#375)

Author: Ellerbach

.vscodeignore

@@ -29,3 +29,6 @@ nanoFirmwareFlasher/**
 !node_modules/extract-zip
 !node_modules/semver
 !node_modules/typed-rest-client
+
+# Include debug bridge binaries
+!bin/nanoDebugBridge/**

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- **Full Debugging Support** - The extension now supports source-level debugging of nanoFramework applications
+  - Set and hit breakpoints in your C# code
+  - Step through code (Step Into, Step Over, Step Out)
+  - Inspect local variables, arguments, and object properties
+  - View call stacks with source file locations
+  - Evaluate expressions in the Debug Console
+  - Watch expressions panel support
+  - Debug.WriteLine output in Debug Console
+  - Exception handling with break on exception options
+  - Automatic device detection and selection
+  - Support for both Launch (deploy and debug) and Attach (debug running code) modes
+
+### Documentation
+
+- Added comprehensive debugging documentation in [docs/debugging.md](docs/debugging.md)
+- Updated README with debugging section, launch.json configuration, and troubleshooting guide
+
+---
+
 ## [v1.0.132](https://github.com/nanoframework/nf-VSCodeExtension/tree/v1.0.132) (2022-09-08)
 
 [Full Changelog](https://github.com/nanoframework/nf-VSCodeExtension/compare/v1.0.130...v1.0.132)

README.md

@@ -74,15 +74,106 @@ Then select the type of project you want to add.
 
 ![type of project](docs/create-solution-step4.png)
 
-### Check Prerequisites
+## Debugging
+
+The extension provides full debugging support for .NET nanoFramework applications running on connected devices.
+
+### Quick Start
+
+1. **Connect your device** - Ensure your nanoFramework device is connected via USB/Serial
+2. **Build your project** - Use `nanoFramework: Build Project` command
+3. **Start debugging** - Press `F5` or use `Run > Start Debugging`
+
+### Debug Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **Breakpoints** | Set breakpoints by clicking in the gutter or pressing `F9` |
+| **Step Through Code** | Step Over (`F10`) currently like Continue, Step Into (`F11`), Step Out (`Shift+F11`) |
+| **Variable Inspection** | View local variables, arguments, and object properties |
+| **Watch Expressions** | Add expressions to the Watch panel |
+| **Call Stack** | View the current call stack with source locations |
+| **Debug Console** | See `Debug.WriteLine` output and evaluate expressions |
+| **Exception Handling** | Break on exceptions (configurable) |
+
+### launch.json Configuration
+
+Create a `.vscode/launch.json` file in your workspace with the following configurations:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "nanoFramework: Launch and Debug",
+            "type": "nanoframework",
+            "request": "launch",
+            "program": "${workspaceFolder}/${workspaceFolderBasename}/bin/Debug",
+            "device": "",
+            "stopOnEntry": true,
+            "deployAssemblies": true,
+            "verbosity": "none"
+        },
+        {
+            "name": "nanoFramework: Attach to Device",
+            "type": "nanoframework",
+            "request": "attach",
+            "device": "",
+            "program": "${workspaceFolder}/${workspaceFolderBasename}/bin/Debug"
+        }
+    ]
+}
+```
+
+#### Configuration Options
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `type` | string | Must be `"nanoframework"` |
+| `request` | string | `"launch"` to deploy and debug, `"attach"` to debug running code |
+| `program` | string | Path to the `.pe` file or directory containing assemblies |
+| `device` | string | COM port (e.g., `"COM3"`) or IP address. Leave empty for auto-detect |
+| `stopOnEntry` | boolean | Pause at program entry point (default: `true`) |
+| `deployAssemblies` | boolean | Deploy assemblies before debugging (launch only) |
+| `verbosity` | string | Logging verbosity: `"none"`, `"information"` (default), or `"debug"` |
+
+### Device Selection
+
+- If `device` is empty, the extension will:
+  - Use the last selected device if available
+  - Auto-select if only one device is connected
+  - Show a device picker if multiple devices are found
+
+- Use the `nanoFramework: Select Debug Device` command to manually choose a device
+
+### Troubleshooting
+
+**Device not detected:**
+
+- Ensure the device is properly connected and running nanoFramework firmware
+- Check that the correct drivers are installed for your device
+- Try unplugging and reconnecting the device
 
-Select `nanoFramework: Check Prerequisites` to verify that all required tools are installed and properly configured on your system. This is especially helpful for macOS and Linux users to diagnose setup issues.
+**Breakpoints not hitting:**
+
+- Ensure you have build the project first!
+- Ensure the deployed code matches your source files
+- Adjust the path for `"program": "${workspaceFolder}/${workspaceFolderBasename}/bin/Debug"` if needed
+- Rebuild the project before debugging
+- Check that symbol files (.pdbx, .pdb) are present in the output directory
+
+**Debug session won't start:**
+
+- Verify .NET 10.0 runtime is installed
+- Check the Debug Console for error messages
+- Ensure no other application is using the COM port
+- Change the log level to see more errors
 
 ## Requirements
 
 You will need to make sure you'll have the following elements installed:
 
-- [.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or later
+- [.NET 10.0](https://dotnet.microsoft.com/download/dotnet/10.0) or later
 - [nanoff](https://github.com/nanoframework/nanoFirmwareFlasher) - Install via: `dotnet tool install -g nanoff`
 - **Windows only:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with ".NET desktop build tools" workload
 - **Linux/macOS only:** [mono-complete](https://www.mono-project.com/docs/getting-started/install/) with msbuild, and [nuget CLI](https://www.nuget.org/downloads)
@@ -103,9 +194,7 @@ Log out and back in for this to take effect.
 > Instead install the `mono-complete` package provided by the Mono Project.  
 > The [preview](https://www.mono-project.com/download/preview/) version is recommended.
 
-## Known Issues
-
-This extension will **not** allow you to debug the device. Debug is only available on Windows with [Visual Studio](https://visualstudio.microsoft.com/downloads/) (any edition) and the [.NET nanoFramework Extension](https://marketplace.visualstudio.com/items?itemName=nanoframework.nanoFramework-VS2022-Extension) installed.
+**Debugging is now supported!** See the [Debugging](#debugging) section below.
 
 This extension works on:
 
@@ -115,6 +204,10 @@ This extension works on:
 
 32-bit operating systems are not supported.
 
+## Known Issues
+
+Step over in debug mode is like continue so far. We're activey working on improving this. You can setup as many break points as you want, so, if you need an equivalent of setp over, you can do this!
+
 ## Developing for the VS Code extension
 
 Documentation about development for the extension can be found [here](installation.md).

azure-pipelines.yml

@@ -65,6 +65,10 @@ steps:
     displayName: npm ci
     condition: succeeded()
 
+  - script: npx gulp build-debug-bridge
+    displayName: Build debug bridge
+    condition: succeeded()
+
   # we don't have unit tests
   # - script: npm run test
   #   displayName: Run unit tests