Insert new debugger with support for Symbol Server and Source Link (#…

…2070)

* launch.json schema changes and documentation

This has the new launch.json schema to support XPlat symbols

* Update debugger packages

* Update CHANGELOG.md with debugger change

CHANGELOG.md

@@ -3,6 +3,15 @@
 * There currently is no completion support for package references in csproj files. ([#1156](https://github.com/OmniSharp/omnisharp-vscode/issues/1156))
   * As an alternative, consider installing the [MSBuild Project Tools](https://marketplace.visualstudio.com/items?itemName=tintoy.msbuild-project-tools) extension by @tintoy.
 
+## 1.15.0 _(Not Yet Released)_
+
+#### Debugger
+
+* Adds support for [Source Link](https://github.com/dotnet/core/blob/master/Documentation/diagnostics/source_link.md), Symbol Servers and other more advanced symbol options ([#373](https://github.com/OmniSharp/omnisharp-vscode/issues/373))
+* Adds launch.json option to suppress Just-In-Time compiler optimizations.
+* Due to the previous two items and work from the .NET Team, it is now possible to easily debug into ASP.NET itself in projects running against .NET Core 2.1 preview 1. Support for debugging into all the managed code in .NET Core will come in future .NET Core 2.1 builds. Instructions are in the [wiki](https://github.com/OmniSharp/omnisharp-vscode/wiki/Debugging-into-the-.NET-Framework-itself).
+
+
 ## 1.14.0 (February 14, 2018)
 
 #### C# Language Support

debugger-launchjson.md

@@ -66,11 +66,6 @@ You can optionally configure a file by file mapping by providing map following t
         "C:\\foo":"/home/me/foo"
     }
 
-## Symbol Path
-You can optionally provide paths to symbols following this schema:
-
-    "symbolPath": [ "/Volumes/symbols" ]
-
 ## Just My Code
 You can optionally disable `justMyCode` by setting it to "false". You should disable Just My Code when you are trying to debug into a library that you pulled down which doesn't have symbols or is optimized.
 
@@ -110,7 +105,103 @@ More information about pipe transport can be found [here](https://github.com/Omn
 
 You can find information on configuring pipe transport for [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) (WSL) [here](https://github.com/OmniSharp/omnisharp-vscode/wiki/Windows-Subsystem-for-Linux).
 
-## Operating System Specific Configurations
+### Operating System Specific Configurations
 If there specific commands that need to be changed per operating system, you can use the fields: 'windows', 'osx', or 'linux'. 
 You can replace any of the fields mentioned above for the specific operating system.
 
+## Suppress JIT Optimizations
+
+The .NET Debugger supports the following option. If true, when an optimized module (.dll compiled in the Release configuration) loads in the target process, the debugger will ask the Just-In-Time compiler to generate code with optimizations disabled. The option defaults to false.
+
+```
+    "suppressJITOptimizations": true
+```
+
+**How optimizations work in .NET:** If you are trying to debug code, it is easier when that code is **NOT** optimized. This is because when code is optimized, the compiler and runtime will make changes to the emitted CPU code so that it runs faster, but has a less direct mapping to original source code. This means that debuggers are frequently unable to tell you the value of local variables, and code stepping and breakpoints might not work as you expect.
+
+Normally the Release build configuration creates optimized code and the Debug build configuration does not. The `Optimize` MSBuild property controls whether the compiler is told to optimize code.
+
+In the .NET ecosystem, code is turned from source to CPU instructions in a two-step process: first, the C# compiler converts the text you type in to an intermediate binary form called MSIL and writes this out to .dll files. Later, the .NET Runtime converts this MSIL to CPU instructions. Both steps can optimize to some degree, but the second step performed by the .NET Runtime performs the more significant optimizations.
+
+**What does the option do:** This option controls what happens when a DLL that was compiled with optimizations enabled loads inside of the target process. If this option is false (the default value), then when the .NET Runtime compiles the MSIL code into CPU code, it leaves the optimizations enabled. If the option is true, then the debugger requests that optimizations be disabled.
+
+**When should you use this option:** This option should be used when you have downloaded dlls from another source, such as a nuget package, and you want to debug the code in this DLL. In order for this to work you must also find the symbol (.pdb) file for this DLL.
+
+If you are only interested in debugging code you are building locally, it is best to leave this option false, as, in some cases, enabling this option will significantly slow down debugging. There are two reason for this slow down --
+
+* Optimized code runs faster. If you are turning off optimizations for lots of code the time can add up.
+* If you have Just My Code enabled, the debugger will not even try and load symbols for dlls which are optimized. Finding symbols can take a long time.
+
+**Limitations of this option:** There are two situations where this option will **NOT** work:
+
+1: In situations where you are attaching the debugger to an already running process, this option will have no effect on modules that were already loaded at the time the debugger was attached.
+
+2: This option has no effect on dlls that have been pre-compiled (a.k.a ngen'ed) to native code. However, you can disable usage of pre-compiled code by starting the process with the environment variable 'COMPlus_ZapDisable' set to '1'. If you are launching under the debugger, this code be done by adding this to launch.json --
+
+```json
+    "env": {
+        "COMPlus_ZapDisable": "1"
+    }
+```
+
+## Symbol Options
+
+The `symbolOptions` element allows customization of how the debugger searches for symbols. Example:
+
+```json
+    "symbolOptions": {
+        "searchPaths": [
+            "~/src/MyOtherProject/bin/debug",
+            "https://my-companies-symbols-server"
+        ],
+        "searchMicrosoftSymbolServer": true,
+        "cachePath": "/symcache",
+        "moduleFilter": {
+            "mode": "loadAllButExcluded",
+            "excludedModules": [ "DoNotLookForThisOne*.dll" ]
+        }
+    }
+```
+
+### Properties:
+
+**searchPaths**: Array of symbol server URLs (example: https://msdl.microsoft.com/download/symbols) or directories (example: /build/symbols) to search for .pdb files. These directories will be searched in addition to the default locations -- next to the module and the path where the pdb was originally dropped to.
+
+**searchMicrosoftSymbolServer**: If `true` the Microsoft Symbol server (https://msdl.microsoft.com/download/symbols) is added to the symbols search path. If unspecified, this option defaults to `false`.
+
+**cachePath**": Directory where symbols downloaded from symbol servers should be cached. If unspecified, on Windows the debugger will default to %TEMP%\\SymbolCache, and on Linux and macOS the debugger will default to ~/.vsdbg/SymbolCache.
+
+**moduleFilter.mode**: This value is either `"loadAllButExcluded"` or `"loadOnlyIncluded"`. In `"loadAllButExcluded"` mode, the debugger loads symbols for all modules unless the module is in the 'excludedModules' array. In `"loadOnlyIncluded"` mode, the debugger will not attempt to load symbols for ANY module unless it is in the 'includedModules' array, or it is included through the 'includeSymbolsNextToModules' setting.
+
+#### Properties for `"loadAllButExcluded"` mode: 
+**moduleFilter.excludedModules**: Array of modules that the debugger should NOT load symbols for. Wildcards (example: MyCompany.*.dll) are supported.
+
+#### Properties for `"loadOnlyIncluded"` mode: 
+**moduleFilter.includedModules**: Array of modules that the debugger should load symbols for. Wildcards (example: MyCompany.*.dll) are supported.
+
+**moduleFilter.includeSymbolsNextToModules**: If true, for any module NOT in the 'includedModules' array, the debugger will still check next to the module itself and the launching executable, but it will not check paths on the symbol search list. This option defaults to 'true'.
+
+## Source Link options
+
+Source Link is a feature that makes it so that when you are debugging code that was built on another computer, such as code coming from a nuget package, the debugger can automatically bring up matching source code by downloading it from the web. To make this work, the .pdb files for the code you are debugging contains data that maps the source files in the DLL to a URL that the debugger can download from. More information about Source Link can be found at [https://github.com/dotnet/core/blob/master/Documentation/diagnostics/source_link.md](https://github.com/dotnet/core/blob/master/Documentation/diagnostics/source_link.md).
+
+The `sourceLinkOptions` element in launch.json allows customization of Source Link behavior by URL. It is a map from URL to Source Link options for that URL. Wildcards are supported in the URL name. Currently the only customization is if Source Link is enabled for that URL, but more options may be added in the future.
+
+Example:
+
+```json
+    "sourceLinkOptions": {
+        "https://raw.githubusercontent.com/*": { "enabled": true },
+        "*": { "enabled": false }
+    }
+```
+
+This example will enable Source Link for GitHub URLs, and disable Source Link for all other URLs.
+
+The default value of this option is to enable Source Link for all URLs. Similarly, Source Link will be enabled for any URL that doesn't have a rule in the `sourceLinkOptions` map.
+
+To disable Source Link for all URLs, use `"sourceLinkOptions": { "*": { "enabled": false } }`.
+
+If multiple entries cover the same URL, the more specific entry (the entry with the longer string length) will be used.
+
+Currently Source Link only works for source files that can be accessed without authentication. So, for example, the debugger can download source files from open source projects on GitHub, but it cannot download from private GitHub repos, or from Visual Studio Team Services.