diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 1523d3554d..59e1b21008 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -6,11 +6,8 @@ about: Report errors or unexpected behavior 🤔 ### System Details -- Operating system name and version: -- VS Code version: -- PowerShell extension version: -- Output from `$PSVersionTable`: + + + +System Details Output ``` -Copy / paste the following commands into the PowerShell Integrated Console, and paste the output here: -code -v -$pseditor.EditorServicesVersion -code --list-extensions --show-versions -$PSVersionTable ``` ### Issue Description I am experiencing a problem with... +#### Expected Behaviour + +-- Description of what *should* be happening -- + +#### Actual Behaviour + +-- Description of what actually happens -- + ### Attached Logs Follow the instructions in the [README](https://github.com/PowerShell/vscode-powershell#reporting-problems) diff --git a/README.md b/README.md index e4e273c129..58523fb922 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ that Visual Studio Code provides. ## Platform support -- **Windows 7 through 10** with PowerShell v3 and higher -- **Linux** with PowerShell v6 (all PowerShell-supported distributions) -- **macOS and OS X** with PowerShell v6 +- **Windows 7 through 10** with Windows PowerShell v3 and higher, and PowerShell Core +- **Linux** with PowerShell Core (all PowerShell-supported distributions) +- **macOS and OS X** with PowerShell Core Read the [installation instructions](https://github.com/PowerShell/PowerShell/blob/master/docs/learning-powershell/using-vscode.md) to get more details on how to use the extension on these platforms. @@ -26,11 +26,28 @@ Read the [FAQ](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) for ans - Go to Definition of cmdlets and variables - Find References of cmdlets and variables - 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` +- 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! -## Quick Installation +## 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 +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/extensions/install-extension#_install-from-a-vsix) +instructions. The easiest way is through the command line: + +``` +code --install-extension PowerShell-.vsix +``` + +> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`. + +## Script-based Installation If you're on Windows 7 or greater with the [PowerShellGet](https://msdn.microsoft.com/powershell/gallery/readme) module installed, you can easily install both Visual Studio Code and the PowerShell @@ -52,22 +69,14 @@ first before running it in this way! iex (iwr https://git.io/vbxjj) ``` -## 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 -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/extensions/install-extension#_install-from-a-vsix) -instructions. The easiest way is through the command line: +## Reporting Problems -``` -code --install-extension PowerShell-.vsix -``` +If you experience any problems with the PowerShell Extension, see +[the troubleshooting docs](./docs/troubleshooting.md) for information +on diagnosing and reporting issues. -> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`. +#### Security Note +For any security issues, please see [here](./docs/troubleshooting.md#note-on-security). ## Example Scripts @@ -88,48 +97,6 @@ To open/view the extension's examples in Visual Studio Code, run the following f code (Get-ChildItem $Home\.vscode\extensions\ms-vscode.PowerShell-*\examples)[-1] ``` -## Reporting Problems - -If you're having trouble with the PowerShell extension, please follow these instructions -to file an issue on our GitHub repository: - -### 1. File an issue on our [Issues Page](https://github.com/PowerShell/vscode-powershell/issues) - -Make sure to fill in the information that is requested in the issue template as it -will help us investigate the problem more quickly. - -To automatically create a bug report from within the extension, open the Command pallet (Ctrl/Cmd+Shift+P) and run the *"Report a problem on GitHub"* command. Some basic information about your instance and powershell versions will be collected and inserted into a new GitHub issue. - -NOTE: If you believe that there is a security vulnerability in the PowerShell extension for VSCode, -it **must** be reported to [secure@microsoft.com](https://technet.microsoft.com/security/ff852094.aspx) to allow for [Coordinated Vulnerability Disclosure](https://technet.microsoft.com/security/dn467923). -**Only** file an issue, if secure@microsoft.com has confirmed filing an issue is appropriate. - -### 2. Capture verbose logs and send them to us - -If you're having an issue with crashing or other erratic behavior, add the following -line to your User Settings in Visual Studio Code: - -```json - "powershell.developer.editorServicesLogLevel": "Verbose" -``` - -Restart Visual Studio Code and try to reproduce the problem. Once you are done with -that, zip up the logs in the corresponding folder for your operating system: - -- **Windows**: `$HOME\.vscode\extensions\ms-vscode.PowerShell-\logs` -- **Linux and macOS**: `~/.vscode/extensions/ms-vscode.PowerShell-/logs` - -Alternatively, you can open the log folder using the Command pallet (Ctrl/Cmd+Shift+P) and running the *"Open powerShell Extension Logs Folder"* command. - -You have two options for sending us the logs: - - 1. If you are editing scripts that contain sensitive information (intellectual property, - deployment or administrative information, etc), e-mail the logs directly to - *vscode-powershell@microsoft.com*. - - 2. If you are editing scripts that don't contain sensitive information, you can drag and - drop your logs ZIP file into the GitHub issue that you are creating. - ## Contributing to the Code Check out the [development documentation](docs/development.md) for more details @@ -139,7 +106,7 @@ on how to contribute to this extension! - [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill) - [Tyler Leonhardt](https://github.com/tylerl0706) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt) -- [David Wilson](https://github.com/daviwil) - [@daviwil](http://twitter.com/daviwil) +- [Rob Holt](https://github.com/rjmholt) ## License diff --git a/docs/development.md b/docs/development.md index 37f374dbf3..8a9c32b142 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,25 +5,28 @@ You'll need to clone two repositories and set up your development environment to before you can proceed. -### 1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell) +1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell) -### 2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices) +2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices) -### 3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services +3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services. **You will need to complete this step before proceeding**. -### 4. Install [Visual Studio Code Insiders Release](https://code.visualstudio.com/insiders) +4. Install the latest [Visual Studio Code Insiders release](https://code.visualstudio.com/insiders) + - You can also use the [standard Visual Studio Code release](https://code.visualstudio.com/). Both will work, but using VSCode + Insiders means the extension can be developed ready for new features + and changes in the next VSCode release. -### 5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher. +5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher. ## Building the Code #### From Visual Studio Code: -Press Ctrl+P and type `task build` +Press Ctrl+P and type `task build` This will compile the TypeScript files in the project to JavaScript files. -#### From a command prompt: +#### From a PowerShell prompt: ``` Invoke-Build Build @@ -34,7 +37,7 @@ Invoke-Build Build #### From Visual Studio Code: To debug the extension, press F5. To run the extension without debugging, -press Ctrl+F5 or Cmd+F5 on macOS. +press Ctrl+F5 or Cmd+F5 on macOS. #### From a command prompt: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b7fb7e8dd8..7256d43592 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,84 +1,294 @@ # Troubleshooting PowerShell Extension Issues This document contains troubleshooting steps for commonly reported issues when using the -PowerShell extension for Visual Studio Code. +[PowerShell Extension] for Visual Studio Code. -## Windows +## Script Analysis is Reporting False Errors -### 1. IntelliSense is extremely slow on PowerShell 5.0 +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). -There is a known issue with PowerShell 5.0 which, for a small number of users, causes IntelliSense -(code completions) to return after 5-15 seconds. The following steps *might* resolve the issue for you: +## Problems with Syntax Highlighting -1. In a PowerShell console, run the following command: `Remove-Item -Force -Recurse $env:LOCALAPPDATA\Microsoft\Windows\PowerShell\CommandAnalysis` -2. Restart Visual Studio Code and try getting IntelliSense again. +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]. -This issue has been resolved in PowerShell 5.1. +## Known Issues in the Extension -## macOS (OS X) +- Highlighting/completions/command history don't work as I expect in the + Integrated Console - [#535] + - The Integrated Console implements a [custom host] + to work with VSCode, making it incompatible with + [PSReadLine] (the module providing these features in regular PowerShell). + Resolving this incompatibility is being actively worked on. +- Command history is not preserved when debugging in the Integrated Console - + [#550] + - This feature is also provided by [PSReadLine]. +- Intellisense is slow - [#647] + - This is a known issue that we've been chipping away at. There doesn't seem + to be any one performance drain, but we've been trying to incrementally + improve performance bit-by-bit everywhere. +- Variable renaming doesn't work properly - [#261] + - PowerShell's usage of [dynamic scope] rather than [lexical scope] + makes it [formally undecidable] to statically rename variables correctly + (the only way to know for sure which `$x`s refer to the same variable is to + run the PowerShell script). + However, like with many features, we attempt a best effort. +- "Go to Definition" doesn't work through module imports - [#499] + - Again this is a best-effort task. +- Completions don't cycle when Tab is pressed like in the ISE - [#25] + - VSCode itself provides the user experience for completions, and they + currently don't allow us to customize this. +- My command that opens a dialog does nothing - [#410 (comment)] + - Check that the dialog hasn't opened behind VSCode. This is a known + [VSCode issue]. +- PowerShell classes don't have proper reference/symbol support - [#3] + - To maintain compatibility with PowerShell v3/v4 we use an older + PowerShell parsing API that does not support classes. A future version + of the [PowerShell Extension] [will break this compatibility] to support + classes, among other things. +- Document formatting takes a long time - [#984] + - Document formatting is provided by [PSScriptAnalyzer], but there + may be opportunities to improve our integration with it in the + [PowerShell Extension] too. +- `Write-Progress` doesn't output to the console - [#140] -### 1. PowerShell IntelliSense does not work, can't debug scripts +## Reporting an Issue -The most common problem when the PowerShell extension doesn't work on macOS is that you have -an alpha version of PowerShell installed. To upgrade to the latest beta, please follow the -[Install Instructions](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#macos-1012). +If you experience a problem with the [PowerShell Extension]: -If you'd prefer to use an alpha version of PowerShell, then OpenSSL must be installed. -You can check for the installation of OpenSSL by looking for the following files: +1. Search through [existing issues] on GitHub. + In some circumstances, an issue may already be closed due to + a fix being merged but not yet released - so be sure to quickly + check closed issues as well. +2. Most features are provided by the client-agnostic [PowerShell Editor Services] + backend project that the extension leverages, so it's also worth a + [look there]. +3. If you don't see the issue you're experiencing, please [open a new issue]. -If installed using Homebrew: +## Opening a New Issue -``` -/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib -/usr/local/opt/openssl/lib/libssl.1.0.0.dylib -``` +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]. -If installed by some other means: +You can also open an issue directly from VSCode by entering the +[Command Palette] with Ctrl+Shift+P +(Cmd+Shift+P on macOS) and running the +`PowerShell: Upload Bug Report to GitHub` command. -``` -/usr/local/lib/libcrypto.1.0.0.dylib -/usr/local/lib/libssl.1.0.0.dylib -``` +When opening an issue, keep in mind: + +- The fastest way to fixing a bug is reproducing it, and reproducing it + is easier with [more information]. +- The issue templates are designed to help you provide all the information + needed to solve your issue +- As Free and Open Source Software, the [PowerShell Extension] thrives on + the contributions of community members — if you're interested in + [tackling an issue], we always accept contributions and will help you + at every step. + +## Providing Information About Your Environment + +For solving most issues, the following information is important to provide: + +### Logs + +Logs provide context for what was happening when the issue occurred + +- Before sending through logs, try and reproduce the issue with + **log level set to Verbose** or **Diagnostic**. You can set this + in the [VSCode Settings] (Ctrl+,) with: -The extension should check for these files and direct you to this documentation if you -do not have OpenSSL installed. + ```json + "powershell.developer.editorServicesLogLevel": "Verbose" + ``` -#### Installing OpenSSL via Homebrew + or for diagnostic logging: -We **highly recommend** that you use [Homebrew](http://brew.sh) to install OpenSSL. The PowerShell distribution for macOS -has built-in support for Homebrew's OpenSSL library paths. If you install with Homebrew, you will avoid -[security concerns](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#openssl) -around creating symbolic links in your `/usr/local/lib` path which are needed when using other means of installation. + ```json + "powershell.developer.editorServicesLogLevel": "Diagnostic" + ``` -If you don't already have Homebrew installed, you can do so by downloading and installing Homebrew via this ruby script: + After you have captured the issue with the log level turned up, + you may want to return it (since verbose logging can use disk space): -```` -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -```` + ```json + "powershell.developer.editorServicesLogLevel": "Normal" + ``` -Once Homebrew is installed, run the following command: + Logs are located at + ```powershell + $HOME/.vscode[-insiders]/extensions/ms-vscode.powershell-/logs/ + ``` + + For example: + + ```powershell + $HOME/vscode/extensions/ms-vscode.powershell-1.8.4/logs + ``` + +- In VSCode you can open and read the logs directly from the [Command Palette] + (Ctrl+Shift+P) + with `PowerShell: Open PowerShell Extension Logs Folder`. + +- You can attach your logs to an issue by zipping them and drag/dropping + them onto your open issue description in the browser. + +- If you prefer to share your logs privately, you can send them to + 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 + +[Your VSCode version] can be obtained from the Integrated Console +or PowerShell like this: + +```shell +code -v ``` -brew install openssl + +If you are using VSCode Insiders, use this command: + +```shell +code-insiders -v ``` -Restart VS Code after completing the installation and verify that the extension is working correctly. +You should get an output like: -#### Installing OpenSSL via MacPorts +```text +1.27.0 +493869ee8e8a846b0855873886fc79d480d342de +x64 +``` -If you prefer to use [MacPorts](https://www.macports.org/), you can run the following command to install OpenSSL: +If VSCode is not on your path, you will get a message like +```text +code: The term 'code' is not recognized as the name of a cmdlet, ... ``` -sudo port install openssl + +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 + +[Your installed PowerShell Extension version] can similarly be found with: + +```shell +code --list-extensions --show-versions ``` -You will need to take an additional step once installation completes: +With VSCode Insiders: +```shell +code-insiders --list-extensions --show-versions ``` -sudo ln -s /opt/local/lib/libcrypto.1.0.0.dylib /usr/local/lib/libcrypto.1.0.0.dylib -sudo ln -s /opt/local/lib/libssl.1.0.0.dylib /usr/local/lib/libssl.1.0.0.dylib + +You should get an output like: + +```text +DavidAnson.vscode-markdownlint@0.20.0 +eamodio.gitlens@8.5.6 +EditorConfig.EditorConfig@0.12.4 +jchannon.csharpextensions@1.3.0 +k--kato.docomment@0.1.2 +ms-vscode.cpptools@0.18.1 +ms-vscode.csharp@1.16.1 +ms-vscode.PowerShell@2.0.0 +twxs.cmake@0.0.17 +vscodevim.vim@0.16.5 ``` -Thanks to [@MarlonRodriguez](https://github.com/MarlonRodriguez) for the tip! +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 +To get the [PowerShell Editor Services] version, in the Integrated +Console, enter: + +```powershell +> $psEditor.EditorServicesVersion +Major Minor Build Revision +----- ----- ----- -------- +1 8 4 0 +``` + +### PowerShell Version Table +You can get [your PowerShell version table] from the Integrated Console: + +```powershell +> $PSVersionTable +Name Value +---- ----- +PSVersion 6.1.0 +PSEdition Core +GitCommitId 6.1.0 +OS Microsoft Windows 10.0.18242 +Platform Win32NT +PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} +PSRemotingProtocolVersion 2.3 +SerializationVersion 1.1.0.1 +WSManStackVersion 3.0 +``` + +### Operating System Information + +- Windows - all needed information should already be in the `$PSVersionTable` +- macOS + - Your macOS version (e.g. High Sierra 10.13.6) +- Linux + - `uname -a` + - Your distro and version (usually `lsb_release -a` is the best here) + +### 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 +secure@microsoft.com to allow for [Coordinated Vulnerability Disclosure]. +**Only** open an issue if secure@microsoft.com has confirmed that filing +an issue on GitHub is appropriate. + +[Editor Syntax]: https://github.com/PowerShell/EditorSyntax +[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 +[custom host]: https://docs.microsoft.com/en-us/powershell/developer/hosting/custom-host-samples +[dynamic scope]: http://ig2600.blogspot.com/2010/01/powershell-is-dynamically-scoped-and.html +[existing issues]: https://github.com/PowerShell/vscode-powershell/issues +[formally undecidable]: https://en.wikipedia.org/wiki/Undecidable_problem +[lexical scope]: https://stackoverflow.com/questions/1047454/what-is-lexical-scope +[look there]: https://github.com/PowerShell/PowerShellEditorServices/issues +[more information]: #providing-information-about-your-environment +[open an issue]: https://github.com/PowerShell/vscode-powershell/issues/new/choose +[open a new issue]: #opening-a-new-issue +[open an issue there]: https://github.com/PowerShell/PSScriptAnalyzer/issues/new/choose +[open an issue on us on GitHub]: https://github.com/PowerShell/vscode-powershell/issues/new/choose +[Reporting Problems]: ../README.md#reporting-problems +[syntax highlighting issues there]: https://github.com/PowerShell/EditorSyntax/issues/new +[tackling an issue]:./development.md +[VSCode issue]: https://github.com/Microsoft/vscode/issues/42356 +[VSCode Settings]: https://code.visualstudio.com/docs/getstarted/settings +[will break this compatibility]: https://github.com/PowerShell/vscode-powershell/issues/1310 +[Your installed PowerShell Extension version]: https://code.visualstudio.com/docs/editor/extension-gallery#_list-installed-extensions +[your PowerShell version table]: http://www.powertheshell.com/topic/learnpowershell/firststeps/psversion/ +[Your VSCode version]: https://code.visualstudio.com/docs/supporting/FAQ#_how-do-i-find-the-vs-code-version -Restart VS Code after completing the installation and verify that the extension is working correctly. +[#3]: https://github.com/PowerShell/vscode-powershell/issues/3 +[#25]: https://github.com/PowerShell/vscode-powershell/issues/25 +[#140]: https://github.com/PowerShell/vscode-powershell/issues/140 +[#261]: https://github.com/PowerShell/vscode-powershell/issues/261 +[#410 (comment)]: https://github.com/PowerShell/vscode-powershell/issues/410#issuecomment-397531817 +[#499]: https://github.com/PowerShell/vscode-powershell/issues/499 +[#535]: https://github.com/PowerShell/vscode-powershell/issues/535 +[#550]: https://github.com/PowerShell/vscode-powershell/issues/550 +[#647]: https://github.com/PowerShell/vscode-powershell/issues/647 +[#984]: https://github.com/PowerShell/vscode-powershell/issues/984