[docs] Debugging Libraries tests on Mono using VS Code (#73393)

* [docs] Debugging Libraries tests on Mono using VS Code

* markdown lint fixes

* A note about windows

docs/workflow/debugging/libraries/debugging-vscode.md

@@ -18,4 +18,40 @@
       - ex. running `dotnet build /t:Test` in `runtime/src/libraries/System.Net.Sockets/tests/FunctionalTests` has terminal output including `"exec --runtimeconfig System.Net.Sockets.Tests.runtimeconfig.json ... -notrait category=failing"`, which can be reformatted into `["exec","--runtimeconfig","System.Net.Sockets.Tests.runtimeconfigjson", ... ,"-notrait","category=failing"]`
       - similarly, running `dotnet build /t:Test /p:xUnitMethodName=System.Net.Sockets.Tests.{ClassName}.{TestMethodName}` will get you the args needed to debug a specific test
 - Set a breakpoint and launch the debugger (running ".NET Core Launch (console)"), inspecting variables and call stacks will now work.
-- Optionally, save the launch settings in a [workspace](https://code.visualstudio.com/docs/editor/workspaces) file. The advantage is that it doesn't necessarily need to reside in `.vscode` in the currently open directory, so it's much easier to preserve during `git clean -dfx`.
+- Optionally, save the launch settings in a [workspace](https://code.visualstudio.com/docs/editor/workspaces) file. The advantage is that it doesn't necessarily need to reside in `.vscode` in the currently open directory, so it's much easier to preserve during `git clean -dfx`.
+
+## Debugging Libraries with Visual Studio Code running on Mono
+
+To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below.
+See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md)
+
+- Install the VS Code [Mono Debugger (`ms-vscode.mono-debug`)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) extension
+- Create a `launch.json` file configuration with type `mono`
+
+   ```json
+   {
+       "version": "0.2.0",
+       "configurations": [
+           {
+               "name": "Attach to Mono",
+               "type": "mono",
+               "request": "attach",
+               "address": "localhost",
+               "port": 1235
+           }
+        ]
+   }
+   ```
+
+- start a test from the command line, setting the `MONO_ENV_OPTIONS` environment variable to configure the debugger:
+
+  ```sh
+  DOTNET_REMOTEEXECUTOR_SUPPORTED=0 MONO_ENV_OPTIONS="--debug --debugger-agent=transport=dt_socket,address=127.0.0.1:1235,server=y,suspend=y" ./dotnet.sh build /t:Test /p:RuntimeFlavor=Mono src/libraries/System.Buffers/tests
+  ```
+
+  Note that you also have to set `DOTNET_REMOTEEXECUTOR_SUPPORTED=0` otherwise multiple instances of the runtime will attempt to listen on the same port.
+
+  On Windows, do not pass `--debug` in `MONO_ENV_OPTIONS`.
+
+- Set a breakpoint in a test in VS Code and start debugging in the "Attach to Mono" configuration.
+- Note that Mono does not stop on first chance exceptions and xunit catches all exceptions, so if a test is throwing, the debugger won't break on an uncaught exception.

docs/workflow/testing/mono/testing.md

@@ -90,6 +90,11 @@ For example, the following command is for running System.Runtime tests:
 ```
 make run-tests-corefx-System.Runtime
 ```
+
+### Debugging libraries tests on Desktop Mono
+
+See [debugging with VS Code](../../debugging/libraries/debugging-vscode.md#Debugging-Libraries-with-Visual-Studio-Code-running-on-Mono)
+
 ### Mobile targets and WebAssembly
 Build and run library tests against WebAssembly, Android or iOS. See instructions located in [Library testing document folder](../libraries/)