diff --git a/README.md b/README.md index 59a93bd32a..82cc80b2df 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ This leverages the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) where `PowerShellEditorServices` is the server and `vscode-powershell` is the client. +Also included in this extension is the PowerShell ISE theme for Visual Studio Code. It is +not activated by default, but after installing this extension either click "Set Color +Theme" or use the [theme picker](https://code.visualstudio.com/docs/getstarted/themes) and +select "PowerShell ISE" for a fun and familiar experience. + ## Platform support - **Windows 7 through 10** with Windows PowerShell v3 and higher, and PowerShell Core @@ -25,7 +30,7 @@ where `PowerShellEditorServices` is the server and `vscode-powershell` is the cl Read the [installation instructions](https://docs.microsoft.com/en-us/powershell/scripting/components/vscode/using-vscode) to get more details on how to use the extension on these platforms. -Read the [FAQ](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) for answers to common questions. +Read the [troubleshooting guide](./docs/troubleshooting.md) for answers to common questions. ## Features @@ -38,18 +43,20 @@ Read the [FAQ](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) for ans - Document and workspace symbol discovery - Run selected selection of PowerShell code using F8 - Launch online help for the symbol under the cursor using Ctrl+F1 -- Local script debugging and basic interactive console support! +- Local script debugging +- Integrated console support +- PowerShell ISE color theme ## Installing the Extension You can install the official release of the PowerShell extension by following the steps in the [Visual Studio Code documentation](https://code.visualstudio.com/docs/editor/extension-gallery). -In the Extensions pane, search for "PowerShell" extension and install it there. You will +In the Extensions pane, search for "PowerShell" extension and install it there. You will get notified automatically about any future extension updates! You can also install a VSIX package from our [Releases page](https://github.com/PowerShell/vscode-powershell/releases) by following the [Install from a VSIX](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix) -instructions. The easiest way is through the command line: +instructions. The easiest way is through the command line: ```powershell code --install-extension PowerShell-.vsix diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c6c2f76e1b..96f55f76c3 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -3,23 +3,30 @@ This document contains troubleshooting steps for commonly reported issues when using the [PowerShell Extension] for Visual Studio Code. -## Script Analysis is Reporting False Errors +## How do I debug my PowerShell script? -Script analysis is provided by the [PSScriptAnalyzer] project on GitHub. -Please [open an issue there] if you are getting fault script diagnostics -(red and green squiggly lines under PowerShell in scripts). +This topic is best covered in the "Debugging PowerShell Script in Visual Studio Code" +Scripting Guys blog posts (thanks community!): -## Problems with Syntax Highlighting +* [Part 1](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/) +* [Part 2](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/13/debugging-powershell-script-in-visual-studio-code-part-2/) -PowerShell syntax highlighting is not performed by the [PowerShell Extension]. -Instead syntax highlighting for VSCode, Atom, SublimeText and even GitHub is -provided by the [Editor Syntax] repository on GitHub. Please open any -[syntax highlighting issues there]. +## Script analysis is reporting false errors -However, with the introduction of [Semantic Highlighting] in [v2021.2.2], the -chosen colors may be different because this is applied at a layer above [Editor -Syntax]. To disable semantic highlighting and so restore the colors as they -were, set: +Script analysis is provided by the [PSScriptAnalyzer] project on GitHub. If the warning +message starts with `[PSScriptAnalyzer]` or if you are getting faulty script diagnostics +(red and green squiggly lines under PowerShell in scripts) please [open an issue there]. + +## Problems with syntax highlighting + +PowerShell syntax highlighting is performed in combintation by the [PowerShell Extension] +(semantic highlighting) and [Editor Syntax]. Syntax highlighting for VS Code, Atom, +SublimeText and even GitHub is provided by the [Editor Syntax] repository on GitHub. + +With the introduction of [Semantic Highlighting] in [v2021.2.2], the chosen colors may be +different because this is applied at a layer above [Editor Syntax]. To disable semantic +highlighting and so restore the colors as they were and rely solely on [Editor Syntax], +set: ```json "[powershell]": { @@ -30,7 +37,16 @@ were, set: If you leave it enabled, you can customize the colors used for the various tokens. See [#3221] for more info and to leave suggestions. -## VSCode is not working like the ISE +If you disable it and your issue remains, then please open those [syntax highlighting +issues there]. + +## Windows aren't appearing + +Due to an [issue](https://github.com/Microsoft/vscode/issues/42356) in Electron, windows +spawned by Visual Studio Code (such as those for `Get-Credential`, `Connect-MsolService`, +`Connect-AzAccount`, `Connect-AzureAd`, etc.) do not appear above Visual Studio Code. + +## Visual Studio Code is not working like the ISE The PowerShell extension does not aim to perfectly recreate the experience of the PowerShell ISE. @@ -45,7 +61,7 @@ VSCode itself and can't be changed by the extension. The VSCode maintainers are quite reasonable though, and you can ask for new features [in their repository](https://github.com/Microsoft/vscode). -## Known Issues in the Extension +## Known issues in the extension - If you are running the Preview version "PowerShell Preview" side-by-side with the stable version "PowerShell" you will experience performance and debug issues. @@ -84,7 +100,7 @@ and you can ask for new features [in their repository](https://github.com/Micros may be opportunities to improve our integration with it in the [PowerShell Extension] too. -## Reporting an Issue +## Reporting an issue If you experience a problem with the [PowerShell Extension]: @@ -97,7 +113,7 @@ If you experience a problem with the [PowerShell Extension]: [look there]. 3. If you don't see the issue you're experiencing, please [open a new issue]. -## Opening a New Issue +## Opening a new issue If you experience an issue with the [PowerShell Extension] and can't find an existing issue for it, [open an issue on us on GitHub]. @@ -118,7 +134,7 @@ When opening an issue, keep in mind: [tackling an issue], we always accept contributions and will help you at every step. -## Reproducing the Issue +## Reproducing the issue To fix the issue, we need to be able to reproduce it. To do that, we need: @@ -134,7 +150,7 @@ the GitHub issue template will have sections to guide you through providing all of this information as well as environment information discussed below. -## Providing Information About Your Environment +## Providing information about your environment For solving most issues, the following information is important to provide: @@ -213,7 +229,7 @@ At this point, you may delete the setting if you want. vscode-powershell@microsoft.com. Please still open an issue though so we can track the work — other users may have the same issue. -### Visual Studio Code Version +### Visual Studio Code version [Your VSCode version] can be obtained from the Integrated Console or PowerShell like this: @@ -245,7 +261,7 @@ code: The term 'code' is not recognized as the name of a cmdlet, ... in this case, use the file menu in VSCode and choose `Help`>`About` (or `Code`>`About Visual Studio Code` on macOS) to get version information. -### PowerShell Extension Version +### PowerShell extension version [Your installed PowerShell Extension version] can similarly be found with: @@ -278,7 +294,8 @@ If VSCode isn't on your path use the [Command Palette] (Ctrl+Shift+P) to enter `Extensions: Show Installed Extensions` and list your extensions. -### Editor Services Version +### Editor Services version + To get the [PowerShell Editor Services] version, in the Integrated Console, enter: @@ -289,7 +306,8 @@ Major Minor Build Revision 1 8 4 0 ``` -### PowerShell Version Table +### PowerShell version table + You can get [your PowerShell version table] from the Integrated Console: ```powershell @@ -307,7 +325,7 @@ SerializationVersion 1.1.0.1 WSManStackVersion 3.0 ``` -### Operating System Information +### Operating system information - Windows - all needed information should already be in the `$PSVersionTable` - macOS @@ -316,7 +334,7 @@ WSManStackVersion 3.0 - `uname -a` - Your distro and version (usually `lsb_release -a` is the best here) -### Note on Security +### Note on security If you believe there is a security vulnerability in the [PowerShell Extension] (or in [PowerShell Editor Services]), it **must** be reported directly to @@ -328,7 +346,6 @@ an issue on GitHub is appropriate. [PowerShell Editor Services]: https://github.com/PowerShell/PowerShellEditorServices [PowerShell Extension]: https://github.com/PowerShell/vscode-powershell/ [PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer -[PSReadLine]: https://github.com/lzybkr/PSReadLine [Command Palette]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette [Coordinated Vulnerability Disclosure]: https://technet.microsoft.com/security/dn467923