Update debugger documentation for 1.23.12 (#4500)

Author: gregg-miskelly

CHANGELOG.md

@@ -11,8 +11,15 @@
 * Renaming symbol fails within a file that had recently been renamed without saving changes.
   * As a workaround, make an edit within the file before using Rename Symbol.
 
+## 1.23.12 (Not yet released)
+* Debugger changes:
+  * Added support for osx-arm64 debugging ([#4390](https://github.com/OmniSharp/omnisharp-vscode/issues/4390))
+  * Added support for exception conditions. See [documentation](https://aka.ms/VSCode-CS-ExceptionSettings) for more information ([#4356](https://github.com/OmniSharp/omnisharp-vscode/issues/4356)).
+  * Fixed an issue with character encoding for multi-byte characters written to the debug console ([#4398](https://github.com/OmniSharp/omnisharp-vscode/issues/4398))
+
 ## 1.23.11 (April 9, 2021)
 * Move the global Mono check to the correct place ([#4489](https://github.com/OmniSharp/omnisharp-vscode/issues/4489), PR: [#4492](https://github.com/OmniSharp/omnisharp-vscode/pull/4492))
+
 ## 1.23.10 (April 9, 2021)
 * Support solution filters (*.slnf) (PR: [#4481](https://github.com/OmniSharp/omnisharp-vscode/pull/4481))
 * Prompt user to install Blazor WASM companion extension if needed (PR: [#4392](https://github.com/OmniSharp/omnisharp-vscode/pull/4392))

debugger.md

@@ -82,3 +82,27 @@ Select the '.NET Core Attach' configuration. Clicking the play button (or pressi
 #### Remote Debugging
 
 The debugger supports remotely launching or attaching to processes. See [Attaching to remote processes](https://github.com/OmniSharp/omnisharp-vscode/wiki/Attaching-to-remote-processes) in the wiki for more information.
+
+#### Exception Settings
+
+The VS Code .NET debugger supports configuration options for if the debugger stops when exceptions are thrown or caught. This is done through two different entries in the BREAKPOINTS section of the Run view:
+
+![Exceptions settings in BREAKPOINTS Run View](https://raw.githubusercontent.com/wiki/OmniSharp/omnisharp-vscode/images/Exception-Settings.png)
+
+Note that the BREAKPOINTS section will be missing these entries until the first time that the folder has been debugged with the .NET debugger.
+
+Checking 'All Exceptions' will configure the debugger to stop when an exception is thrown. If Just My Code is enabled (which it is by default) the debugger will not break if an exception is internally thrown and caught in library code. Though if the exception is thrown in library code and returned to user code the debugger will break then.
+
+Checking 'User-Unhandled Exceptions' will configure the debugger to stop when an exception is caught in non-user code after having been thrown in user code or traveled through user code. Exceptions that become user-unhandled aren't always a problem, it could be that user code is implementing an API and is expected to raise an exception in this scenario, but it is often a problem. So, by default, the debugger will stop when an exception becomes user-unhandled.
+
+##### Exception Conditions
+Both checkboxes support conditions to break on only selected exception types. To edit the condition, click on the pencil icon (see image above) or right click on the entry and invoke 'Edit Condition'. The condition is a comma-separated list of exception types to break on, or if the list starts with '!', a list of exception types to ignore.
+
+Examples conditions:
+
+| Example condition value | Result |
+|-------------------------|--------|
+| System.NullReferenceException | This will break on just null reference exceptions. |
+| System.NullReferenceException, System.InvalidOperationException | This will break on both null reference exceptions and invalid operation exceptions. |
+| !System.Threading.Tasks.TaskCanceledException | This will break on all exceptions except for task canceled. |
+