Move wiki documentation into the repo

CONTRIBUTING.md

@@ -187,10 +187,10 @@ Extension releases on the marketplace are done from the prerelease and release b
 
 ### Snap main -> prerelease
 The snap is done via the "Branch snap" github action.  To run the snap from main -> prerelease, run the action via "Run workflow" and choose main as the base branch.
-![branch snap action](./docs/main_snap.png)
+![branch snap action](./docs/images/main_snap.png)
 
 This will generate two PRs that must be merged.  One merging the main branch into prerelease, and the other bumps the version in main.
-![generated prs](./docs/generated_prs.png)
+![generated prs](./docs/images/generated_prs.png)
 
 ### Snap prerelease -> release
 To snap from prerelease to release, run the same action but use **prerelease** as the workflow branch.  This will generate a single PR merging from prerelease to release.
@@ -199,6 +199,6 @@ To snap from prerelease to release, run the same action but use **prerelease** a
 The marketplace release is managed by an internal AzDo pipeline.  On the pipeline page, hit run pipeline.  This will bring up the pipeline parameters to fill out:
 1.  The branch will **always** be main, no matter if release a build from prerelease or release.
 2.  Uncheck the "test" option.
-3.  In "Resources", choose "dotnet-vscode-csharp [officialBuildCI]", then check only the build that should be released, and then confirm with "Use selected run".  Based on the selected build, it will automatically determine if it is prerelease or release. ![release pipeline image](./docs/release_pipeline.png)
-4.  The pipeline parameters should then look something like the following image.  Hit "Run". ![release pipeline parameters image](./docs/release_pipeline_params.png)
+3.  In "Resources", choose "dotnet-vscode-csharp [officialBuildCI]", then check only the build that should be released, and then confirm with "Use selected run".  Based on the selected build, it will automatically determine if it is prerelease or release. ![release pipeline image](./docs/images/release_pipeline.png)
+4.  The pipeline parameters should then look something like the following image.  Hit "Run". ![release pipeline parameters image](./docs/images/release_pipeline_params.png)
 5.  After a bit, the pipeline will request approval from an authorized approver before it actually uploads to the marketplace.  Hit approve and it will continue.

SUPPORT.md

@@ -13,7 +13,7 @@ For help and questions about using this project, please see the [README](https:/
 ### How to file an issue
 
 We highly recommend using the C# extension's built-in command, `CSharp: Report an issue` (`csharp.reportIssue`) to create a pre-filled issue template.  This will include helpful details such as local dotnet installations, installed extensions, and other information.
-![csharp.reportIssue command](./docs/report_issue.png)
+![csharp.reportIssue command](./docs/images/report_issue.png)
 
 #### Collecting General Logs
 
@@ -22,8 +22,8 @@ The template has a section to include the `C#` output window logs. These logs ar
 1. **Set the Log Level to Trace**:
    - Open the `C#` output window (`View` -> `Output`).
    - Set the log level to `Trace`.
-     
-     ![c# output window showing trace option](./docs/csharp_trace.png)
+
+     ![c# output window showing trace option](./docs/images/csharp_trace.png)
 
 2. **Reproduce the Issue**:
    - Perform the actions that reproduce the issue.
@@ -57,8 +57,8 @@ For issues with Razor, the Razor Log output window can contain useful informatio
 1. **Set the Log Level to Trace**:
    - Open the `Razor Logs` output window (`View` -> `Output`).
    - Set the log level to `Trace`.
-     
-     ![razor log output window showing trace option](./docs/razor_logs.png)
+
+     ![razor log output window showing trace option](./docs/images/razor_logs.png)
 
 2. **Reproduce the Issue**:
    - Perform the actions that reproduce the issue.
@@ -81,7 +81,7 @@ Missing language features are often caused by a failure to load the project(s) o
    - This information is displayed in the bottom-right corner of the VSCode window in the language status section.
    - You can pin this item using the pin icon to keep it visible at all times.
 
-     ![language status bar showing file active project context](./docs/language_status.png)
+     ![language status bar showing file active project context](./docs/images/language_status.png)
 
 3. **Verify the Solution Explorer (C# Dev Kit)**:
    - If you are using C# Dev Kit, check the Solution Explorer to ensure the project is displayed with the expected references.
@@ -100,12 +100,12 @@ If you encounter issues with document classification (e.g., incorrect syntax hig
      3. Click on the word or section with incorrect colorization to display the token and scope information.
    - Take a screenshot of the output and include it in your issue report.
 
-     ![Inspect Tokens and Scopes Output](./docs/inspect_tokens.png)
+     ![Inspect Tokens and Scopes Output](./docs/images/inspect_tokens.png)
 
 ### Diagnostics problems
 
 For issues with diagnostics, please provide values of the background analysis scope options, `dotnet.backgroundAnalysis.analyzerDiagnosticsScope` and `dotnet.backgroundAnalysis.compilerDiagnosticsScope`
-![background analysis settings](./docs/background_analysis.png)
+![background analysis settings](./docs/images/background_analysis.png)
 
 #### Language server crashing
 
@@ -124,12 +124,12 @@ When investigating performance issues, we may request a performance trace of the
 The C# extension has a built in command, `csharp.recordLanguageServerTrace` to help with trace collection.  This command will install `dotnet-trace` as a global tool and invoke it against the language server.
 
 1.  Invoke the record language server trace command
-![alt text](docs/recordTraceCommand.png)
+![alt text](docs/images/recordTraceCommand.png)
 2.  Select the folder to save the trace.
 3.  Accept the default trace arguments, or change them if requested
-![alt text](docs/recordTraceArgs.png)
+![alt text](docs/images/recordTraceArgs.png)
 4.  A new terminal window will open to run the trace collection.  While the trace is running, reproduce the peformance issue.  When done, hit <Enter> or <Ctrl+C> in the trace window to stop the trace
-![alt text](docs/recordTraceTerminal.png)
+![alt text](docs/images/recordTraceTerminal.png)
 5.  Share the trace.  Note that the trace may contain PII, so generally we will provide an email or other confidential way to share the trace with us.
 
 ## Microsoft Support Policy

debugger.md

@@ -65,7 +65,7 @@ Your project is now all set. Set a breakpoint or two where you want to stop, cli
 If your code was built on a different computer from where you would like to run in there are a few things to keep in mind --
 
 * **Source Maps**: Unless your local source code is at exactly the same path as where the code was originally built you will need to add a [sourceFileMap](https://github.com/dotnet/vscode-csharp/blob/main/debugger-launchjson.md#source-file-map) to launch.json.
-* **Portable PDBs**: If the code was built on Windows, it might have been built using Windows PDBs instead of portable PDBs, but the C# extension only supports portable PDBs. See the [portable PDB documentation](https://github.com/dotnet/vscode-csharp/wiki/Portable-PDBs#how-to-generate-portable-pdbs) for more information.
+* **Portable PDBs**: If the code was built on Windows, it might have been built using Windows PDBs instead of portable PDBs, but the C# extension only supports portable PDBs. See the [portable PDB documentation](./docs/debugger/Portable-PDBs.md#how-to-generate-portable-pdbs) for more information.
 * **Debug vs. Release**: It is much easier to debug code which has been compiled in the `Debug` configuration. So unless the issue you are looking at only reproduces with optimizations, it is much better to use Debug bits. If you do need to debug optimized code, you will need to disable [justMyCode](https://github.com/dotnet/vscode-csharp/blob/main/debugger-launchjson.md#just-my-code) in launch.json.
 
 #### [Configurating launch.json for C# Debugging](debugger-launchjson.md)
@@ -76,7 +76,7 @@ See the [official documentation](https://code.visualstudio.com/docs/csharp/debug
 
 #### Remote Debugging
 
-The debugger supports remotely launching or attaching to processes. See [Attaching to remote processes](https://github.com/dotnet/vscode-csharp/wiki/Attaching-to-remote-processes) in the wiki for more information.
+The debugger supports remotely launching or attaching to processes. See [Attaching to remote processes](./docs/debugger/Attaching-to-remote-processes.md) in the wiki for more information.
 
 #### Exception Settings
 

docs/How-to-run-and-debug-unit-tests.md

@@ -0,0 +1,23 @@
+The C# extension currently supports running and debugging a unit test via CodeLens annotations on test methods. Just click the 'run test' or 'debug test' links:
+
+![CodeLens](./images/unit-test-codelens.png)
+
+### Notes
+
+* Because `dotnet test` will run the test code in a child process, it isn't possible to configure a "unit test debugging" configuration in launch.json
+* There currently isn't a VS Code command to run the current test, though there is an [issue for this in the backlog](https://github.com/dotnet/vscode-csharp/issues/421).
+* You can tweak [debugging options](../debugger-launchjson.md) for unit tests by opening your VS Code settings file (ex: File->Preferences->Settings on Windows), and configuring the `"csharp.unitTestDebuggingOptions"` setting. See example below.
+* If your unit tests are targeting .NET Framework instead of .NET Core, see [Desktop .NET Framework](./debugger/Desktop-.NET-Framework.md) for more information.
+
+Example User Settings file with unit test debugging options:
+
+```json
+{
+    "window.zoomLevel": 0,
+    "csharp.unitTestDebuggingOptions": {
+        "sourceFileMap": {
+            "c:\\example\\folder\\where\\library\\was\\built": "/folder/where/my/library/is/now"
+        }
+    }
+}
+```

docs/Installing-without-Internet-connectivity.md

@@ -0,0 +1,10 @@
+Some environments may not have access to the Internet and thus the marketplace to download extensions or dependencies dynamically.  To install the C# language extension and dependencies without Internet access, the following is required:
+
+> NOTE: It is important that if extensions offer platform-specific versions, that you ensure you are downloading/installing the matching platform pieces. Failure to do so could put your VS Code environment in a non-functional state.
+
+* Download and install the required ASP.NET Core 9.0.8 runtime from https://dot.net/downloads
+* Download the following VS Code extensions **for your specific platform**:
+  * [.NET Install Tool](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime)
+  * [C# language extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp)
+  * Optional extensions such as the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit), [MAUI](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui), or [IntelliCode for C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscodeintellicode-csharp)
+* Follow the documentation to [**Install from VSIX**](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix) in VS Code with the downloaded extension files

docs/Reporting-Issues.md

@@ -0,0 +1,15 @@
+The extension supports the command that populates the necessary information from the user's system into a new github issue and opens the preview in the user's default browser to preview and submit.
+
+#### Report issue on GitHub
+* In VSCode, navigate to the View --> Command Palette menu or press Ctrl+Shift+P.
+* Select the option : `CSharp: Report an issue`. This will open the github repository issues page with a new issue with all the necessary system information.
+* Fill in all the fields like "Expected Behavior", "Actual Behavior", "Steps to Reproduce".
+* Paste the "C#" log (if any) and hit "Submit"
+
+    ##### OmniSharp and C# log
+    * In VSCode, navigate to View-->Output or press Ctrl+Shift+U
+    * In the output pane on the right, you should see an "OmniSharp log" in the drop-down
+    * Paste the output from here to the "OmniSharp log" section
+
+    ![OmniSharp log](./images/omnisharp_log.png)
+    * The C# log can also be found in the same window.

docs/Troubleshooting-'The-.NET-Core-SDK-cannot-be-located.'-errors.md

@@ -0,0 +1,85 @@
+## Introduction
+
+This page contains more information about the error:
+
+> The .NET Core SDK cannot be located. .NET Core debugging will not be enabled. Make sure the .NET Core SDK is installed and is on the path.
+
+What this error means is that this extension ran the command `dotnet` and `dotnet` was **NOT** found on the `PATH` within the extension's process.
+
+If you don't have the .NET Core SDK installed, fixing this error is usually simple enough: visit https://dot.net/core-sdk-vscode to download and install the .NET Core SDK.
+
+If you do have the .NET Core SDK installed, then this means that the directory containing `dotnet` (Linux and macOS) or `dotnet.exe` (Windows) is not on your `PATH`, at least in this extension's process. The rest of this page will provide advice on understanding why.
+
+## Known issues
+
+Before we get to a list of troubleshooting steps, lets first enumerate a few known reasons why this error happens:
+
+1. If you very recently installed the .NET SDK --
+   * If you had Visual Studio Code open at the time you installed the .NET SDK, and you haven't restarted it, you should do so.
+   * On Windows, on some machines, environment variable changes don't immediately take effect. Restart your computer to see if that resolves this problem.
+2. If the .NET SDK was installed through Linux Snap - see [Linux Snap instructions](#linux-snap-instructions)
+
+## General troubleshooting steps on Linux/Mac
+
+The first step in troubleshooting this problem is to see if this problem also happens is a terminal/shell. After you have launched a terminal or shell, type in `which dotnet`.
+
+If `which dotnet` produces a PATH, then the .NET SDK was able to successfully modify the PATH, but VS Code isn't picking it up. VS Code attempts to scrape the environment by launching the default shell under the covers. But this process can be fragile. You can attempt to work around this by starting VS Code from your Terminal. Alternatively, you can attempt to debug VS Code to understand what is going wrong -- at this time at least, the function to debug is [`getUnixShellEnvironment`](https://github.com/microsoft/vscode/blob/ab10e26096a5494b68bc709a405a0dddeb227e0b/src/vs/code/node/shellEnv.ts#L13). Lastly, you could manually add a symbolic link from within a directory which is on the PATH in all processes to wherever `dotnet` is installed (see below for instructions).
+
+If `which dotnet` produces no output, then this means the .NET SDK wasn't able to modify the `PATH` or add a symbolic link, or the .NET SDK for your platform doesn't do so. You can fix this by either adding a symbolic link yourself (example: `sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet` where `/usr/share/dotnet/dotnet` should be replaced with wherever the .NET SDK installer for your platform was installed to), or by modifying your `PATH` manually (example: modify ~/.bashrc add add something like `export PATH=$PATH:/new/directory/here`).
+
+## General troubleshooting steps on Windows
+
+First, as mentioned above, if you installed the .NET SDK since you last rebooted Windows, you might start by just rebooting to see if that fixes things.
+
+Otherwise, you can start troubleshooting this problem is to see if this problem also happens is a command prompt:
+
+* Start a command prompt:
+    * Hit `WinKey+R` to bring up the Windows run dialog
+    * Type in `cmd.exe`
+* When the command prompt starts, type in `where.exe dotnet`.
+
+If the result of running `where.exe` is that a path to dotnet.exe is printed (example: `C:\Program Files\dotnet\dotnet.exe`) then the .NET SDK has successfully added itself to the Windows Path. There are no known reasons why PATH wouldn't be propagated to the VS Code process. You could try starting VS Code from the command prompt to see if that helps.
+
+If the result of running `where.exe` is a message like `INFO: Could not find files for the given pattern(s).` then the .NET SDK wasn't able to add itself to the PATH. You could try uninstalling and reinstalling the .NET SDK. You could also try examining the default path with the following steps:
+
+* Bring up System Properties:
+    * Windows 10 - On the Start Menu, search for 'This PC' and bring up properties
+    * Before - On the Start Menu, search for 'My Computer' and bring up properties
+* Go to the Advanced settings
+* Click the button for 'Environment Variables'
+* Find 'Path' in either the user or system list
+* See if the dotnet.exe directory (example: `C:\Program Files\dotnet`) is in the list. If not you could add it.
+* If it is in the list, you could see if maybe another directory has added it self incorrectly (example: added an opening quote without a trailing quote), or if the set of environment variables has grown very large -- there is a limit of 32,767 total characters.
+
+### Note about 64-bit installs of the .NET SDK
+
+In 64-bit environments the .NET SDK will fail to be discovered if the 32-bit dotnet path comes before the 64-bit dotnet path in the Environment PATH variable. Try removing the 32-bit path entirely from your PATH variable and relaunch VS Code to see if your issue is resolved.
+
+## Special instructions
+
+#### Linux Snap instructions
+
+The Linux Snap packages for the .NET Core SDK, by default, will not create the `dotnet` link. To do so, run `sudo snap alias dotnet-sdk.dotnet dotnet`. More information about this can be found in [the .NET Core SDK release notes](https://github.com/dotnet/core/blob/master/release-notes/3.1/3.1.0/3.1.0-install-instructions.md#install-using-snap).
+
+Note that, as of the time of this writing, there are also other incompatibilities between this extension and the .NET Core SDK Snap package beyond the `dotnet` PATH issue. This incompatibility may result in:
+
+> Some projects have trouble loading. Please review the output for more details.
+> It was not possible to find any installed .NET Core SDKs
+> Did you mean to run .NET Core SDK commands? Install a .NET Core SDK from:
+> 	https://aka.ms/dotnet-download
+
+More information about this problem can be found in [dotnet/cli#12110](https://github.com/dotnet/cli/issues/12110).
+
+Another possible workaround is to add the following to `~/.omnisharp/omnisharp.json`.
+
+```json
+{
+    "MSBuild": {
+        "UseLegacySdkResolver": true
+    }
+}
+```
+
+Instead, you also may create a symbolic link to your dotnet install like so:
+
+`ln -s /snap/dotnet-sdk/current/dotnet /usr/local/bin/dotnet`