From 978cf3c769f2f3e691db307dc3d9cd99eaac1895 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Fri, 6 Jan 2017 07:18:34 -0800 Subject: [PATCH 1/4] Add a User Guide for the extension --- docs/UserGuide.md | 173 ++++++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 80 +------------------ 2 files changed, 174 insertions(+), 79 deletions(-) create mode 100644 docs/UserGuide.md diff --git a/docs/UserGuide.md b/docs/UserGuide.md new file mode 100644 index 0000000000..fcdf85a22a --- /dev/null +++ b/docs/UserGuide.md @@ -0,0 +1,173 @@ +# PowerShell for Visual Studio Code - User Guide + +![PowerShell extension logo](../images/PowerShell_icon.png) + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Editor Concepts](#editor-concepts) +3. [Writing PowerShell](#writing-powershell) +4. [Debugging PowerShell](#debugging-powershell) +5. [Configuring the Extension](#configuring-the-extension) +6. [Frequently Asked Questions](#frequently-asked-questions) +7. [Troubleshooting](#troubleshooting) + +## Getting Started + +The PowerShell extension works with both the [Stable](https://code.visualstudio.com/) and +[Insiders](https://code.visualstudio.com/insiders) releases of Visual Studio Code. To +install the extension, follow the instructions in our README.md. + +## Editor Concepts + +> NOTE: This section is currently under development. Please feel free to +> [file issues](https://github.com/PowerShell/vscode-powershell) for any +> additional content you wish to see in this section. + +The Visual Studio Code documentation site provides a [great overview](https://code.visualstudio.com/docs/editor/codebasics) +of the editor and its features. + +### Files and Folders + +Visual Studio Code is focused around managing projects using folders instead +of project files. + +You can only have one top-level workspace folder open at a time. + +Unlike larger integrated development environments (IDEs) like [Visual Studio](https://www.visualstudio.com/), +Visual Studio Code + +### Command Palette + +The Command Palette is a searchable index of all the things you can do in Visual +Studio Code. It filters down every command in the editor as you type so that you +can find what you're looking for with ease. For example, typing `PowerShell` will +show you all of the commands with the word "PowerShell" in the name including those +that come with the PowerShell extension. + +You can open the command palette by pressing F1 or Ctrl+Shift+P +(Cmd+Shift+P on macOS). You'll be presented with this UI: + +**TODO: Image** + +Once you've typed enough to see the command you're looking for, you can use the arrow +keys to navigate the filtered command list. When you've got the desired command selected +you can execute it by pressing Enter. + +Some commands in Visual Studio Code will use the Command Palette UI to prompt you for +other things like string input or a list of selections to choose from. + +### Activity Bar + +### Integrated Terminal + +### Editor Settings + +Just about everything in Visual Studio Code is configurable using plain-text files in the +[JSON](https://en.wikipedia.org/wiki/JSON) format. + +## Writing PowerShell + +> NOTE: This section is currently under development. Please feel free to +> [file issues](https://github.com/PowerShell/vscode-powershell) for any +> additional content you wish to see in this section. + +## Debugging PowerShell + +> NOTE: This section is currently under development. Please feel free to +> [file issues](https://github.com/PowerShell/vscode-powershell) for any +> additional content you wish to see in this section. + +## Configuring the Extension + +> NOTE: This section is currently under development. Please feel free to +> [file issues](https://github.com/PowerShell/vscode-powershell) for any +> additional content you wish to see in this section. + +### Recommended Settings + +## Frequently Asked Questions + +> NOTE: This section is currently under development. Please feel free to +> [file issues](https://github.com/PowerShell/vscode-powershell) for any +> additional content you wish to see in this section. + + +## Troubleshooting + +### Windows + +#### 1. IntelliSense is extremely slow on PowerShell 5.0 + +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: + +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. + +This issue has been resolved in PowerShell 5.1. + +### macOS (OS X) + +#### 1. PowerShell IntelliSense does not work, can't debug scripts + +The most common problem when the PowerShell extension doesn't work on macOS is that +OpenSSL is not installed. You can check for the installation of OpenSSL by looking for +the following files: + +If installed using Homebrew: + +``` +/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib +/usr/local/opt/openssl/lib/libssl.1.0.0.dylib +``` + +If installed by some other means: + +``` +/usr/local/lib/libcrypto.1.0.0.dylib +/usr/local/lib/libssl.1.0.0.dylib +``` + +The extension should check for these files and direct you to this documentation if you +do not have OpenSSL installed. + +##### Installing OpenSSL via Homebrew + +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. + +If you don't already have Homebrew installed, you can do so by downloading and installing Homebrew via this ruby script: + +```` +ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +```` + +Once Homebrew is installed, run the following command: + +``` +brew install openssl +``` + +Restart VS Code after completing the installation and verify that the extension is working correctly. + +##### Installing OpenSSL via MacPorts + +If you prefer to use [MacPorts](https://www.macports.org/), you can run the following command to install OpenSSL: + +``` +sudo port install openssl +``` + +You will need to take an additional step once installation completes: + +``` +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 +``` + +Thanks to [@MarlonRodriguez](https://github.com/MarlonRodriguez) for the tip! + +Restart VS Code after completing the installation and verify that the extension is working correctly. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a8ffbf1fda..f50a2c3fa8 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,81 +1,3 @@ # Troubleshooting PowerShell Extension Issues -This document contains troubleshooting steps for commonly reported issues when using the -PowerShell extension for Visual Studio Code. - -## Windows - -### 1. IntelliSense is extremely slow on PowerShell 5.0 - -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: - -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. - -This issue has been resolved in PowerShell 5.1. - -## macOS (OS X) - -### 1. PowerShell IntelliSense does not work, can't debug scripts - -The most common problem when the PowerShell extension doesn't work on macOS is that -OpenSSL is not installed. You can check for the installation of OpenSSL by looking for -the following files: - -If installed using Homebrew: - -``` -/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib -/usr/local/opt/openssl/lib/libssl.1.0.0.dylib -``` - -If installed by some other means: - -``` -/usr/local/lib/libcrypto.1.0.0.dylib -/usr/local/lib/libssl.1.0.0.dylib -``` - -The extension should check for these files and direct you to this documentation if you -do not have OpenSSL installed. - -#### Installing OpenSSL via Homebrew - -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. - -If you don't already have Homebrew installed, you can do so by downloading and installing Homebrew via this ruby script: - -```` -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -```` - -Once Homebrew is installed, run the following command: - -``` -brew install openssl -``` - -Restart VS Code after completing the installation and verify that the extension is working correctly. - -#### Installing OpenSSL via MacPorts - -If you prefer to use [MacPorts](https://www.macports.org/), you can run the following command to install OpenSSL: - -``` -sudo port install openssl -``` - -You will need to take an additional step once installation completes: - -``` -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 -``` - -Thanks to [@MarlonRodriguez](https://github.com/MarlonRodriguez) for the tip! - -Restart VS Code after completing the installation and verify that the extension is working correctly. +Please see the new [User Guide]() for troubleshooting instructions! \ No newline at end of file From 31a7bfb94cb996a64d0092065ccebbb7c3e6325f Mon Sep 17 00:00:00 2001 From: David Wilson Date: Mon, 15 May 2017 10:54:30 -0700 Subject: [PATCH 2/4] Add more outline and possible content --- docs/UserGuide.md | 77 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 70 insertions(+), 7 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index fcdf85a22a..49be18a544 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -8,7 +8,7 @@ 2. [Editor Concepts](#editor-concepts) 3. [Writing PowerShell](#writing-powershell) 4. [Debugging PowerShell](#debugging-powershell) -5. [Configuring the Extension](#configuring-the-extension) +5. [Configuring the Extension](#configuring-the-editor-and-extension) 6. [Frequently Asked Questions](#frequently-asked-questions) 7. [Troubleshooting](#troubleshooting) @@ -59,12 +59,22 @@ other things like string input or a list of selections to choose from. ### Activity Bar +### Source Control + ### Integrated Terminal -### Editor Settings +### Tasks -Just about everything in Visual Studio Code is configurable using plain-text files in the -[JSON](https://en.wikipedia.org/wiki/JSON) format. +### Extensions + +#### Recommended Extensions + +- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) +- [Vim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) +- [Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync) + +Check out other [popular extensions](https://marketplace.visualstudio.com/vscode) on +the Visual Studio Marketplace. ## Writing PowerShell @@ -72,20 +82,67 @@ Just about everything in Visual Studio Code is configurable using plain-text fil > [file issues](https://github.com/PowerShell/vscode-powershell) for any > additional content you wish to see in this section. +### IntelliSense + +### Analyzing Your Code + +- Syntax analysis +- PSScriptAnalyzer +- Code fixes + +### Navigating Around the Code + +### Formatting Your Code + +### Expanding Aliases + ## Debugging PowerShell > NOTE: This section is currently under development. Please feel free to > [file issues](https://github.com/PowerShell/vscode-powershell) for any > additional content you wish to see in this section. -## Configuring the Extension +## Configuring the Editor and Extension > NOTE: This section is currently under development. Please feel free to > [file issues](https://github.com/PowerShell/vscode-powershell) for any > additional content you wish to see in this section. +Just about everything in Visual Studio Code is configurable using plain-text files in the +[JSON](https://en.wikipedia.org/wiki/JSON) format. + +### User and Workspace Settings + +### Editor Settings + +- `editor.insertSpaces` - Spaces, not tabs! +- `editor.formatOnSave` - Format your code just before it's saved +- `editor.formatOnType` - Format your code as you type! + +- `editor.fontSize` +- `editor.fontFamily` + +- `terminal.integrated.fontSize` - Override `editor.fontSize in the integrated terminal +- `terminal.integrated.fontFamily` - Override `editor.fontFamily` in the integrated terminal + +### PowerShell Extension Settings + ### Recommended Settings +TODO: Write full descriptions + +- `files.defaultLanguage`: Set the default language for files created with Ctrl+N +- `files.autoSave`: Save your files automatically as you edit them, very configurable + +## Tips and Tricks + +**Please feel free to send pull requests to add more tips and tricks to this section!** + +- "Hot Exit": retains unsaved files on exit, restores on next session +- Markdown preview: Ctrl+Shift+V +- Zen mode: Ctrl+K Z +- Side by side editing: Ctrl+\ + ## Frequently Asked Questions > NOTE: This section is currently under development. Please feel free to @@ -93,11 +150,17 @@ Just about everything in Visual Studio Code is configurable using plain-text fil > additional content you wish to see in this section. +### Why doesn't the debugger hit a breakpoint I added? + +### Why can't I remove breakpoints from a file while I'm not debugging a script? + +### Why does the integrated console steal focus when I run the current selection (F8)? + ## Troubleshooting ### Windows -#### 1. IntelliSense is extremely slow on PowerShell 5.0 +#### IntelliSense is extremely slow on PowerShell 5.0 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: @@ -109,7 +172,7 @@ This issue has been resolved in PowerShell 5.1. ### macOS (OS X) -#### 1. PowerShell IntelliSense does not work, can't debug scripts +#### PowerShell IntelliSense does not work, can't debug scripts The most common problem when the PowerShell extension doesn't work on macOS is that OpenSSL is not installed. You can check for the installation of OpenSSL by looking for From 9513bd24bc156489a13534d886214dbec139bddc Mon Sep 17 00:00:00 2001 From: David Wilson Date: Mon, 15 May 2017 12:05:51 -0700 Subject: [PATCH 3/4] More User Guide contents --- docs/UserGuide.md | 55 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 49be18a544..faf8a8ea1d 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -9,14 +9,27 @@ 3. [Writing PowerShell](#writing-powershell) 4. [Debugging PowerShell](#debugging-powershell) 5. [Configuring the Extension](#configuring-the-editor-and-extension) -6. [Frequently Asked Questions](#frequently-asked-questions) -7. [Troubleshooting](#troubleshooting) +6. [Tips and Tricks](#tips-and-tricks) +7. [Frequently Asked Questions](#frequently-asked-questions) +8. [Troubleshooting](#troubleshooting) ## Getting Started +Welcome to the PowerShell extension for Visual Studio Code! This extension aims to +provide a complete, high-quality development experience for PowerShell scripts, modules, +and DSC resources. We are developing this extension as an open-source project on GitHub +so please feel free to [file an issue](https://github.com/PowerShell/vscode-powershell/issues) +if you encounter an issue or if you have any questions or feature requests. + The PowerShell extension works with both the [Stable](https://code.visualstudio.com/) and -[Insiders](https://code.visualstudio.com/insiders) releases of Visual Studio Code. To -install the extension, follow the instructions in our README.md. +[Insiders](https://code.visualstudio.com/insiders) releases of Visual Studio Code. You can +learn how to install either of these releases in Visual Studio Code's [setup instructions](https://code.visualstudio.com/docs/setup/setup-overview). +Once you've installed Visual Studio Code you can install the PowerShell extension by +[following the instructions](https://github.com/PowerShell/vscode-powershell#installing-the-extension) +in our README. + +If you'd like a quick and easy way to install both Visual Studio Code and the PowerShell +extension, try our [quick install script](https://github.com/PowerShell/vscode-powershell#quick-installation)! ## Editor Concepts @@ -29,13 +42,20 @@ of the editor and its features. ### Files and Folders -Visual Studio Code is focused around managing projects using folders instead -of project files. +Visual Studio Code is designed around managing projects using file system folders +instead of project files. This enables individual language extensions to use their +own tooling to manage the experience for a "project" in the editor instead of having +an editor-specific project file. -You can only have one top-level workspace folder open at a time. +Visual Studio Code looks for a special folder in your workspace called `.vscode`. This +folder contains workspace-specific settings for the editor, tasks to execute for your +project (like build scripts or Pester tests) and launch configurations for debugging +your PowerShell scripts. For best results, this folder should be checked into your +source control repository along with your project's source code. -Unlike larger integrated development environments (IDEs) like [Visual Studio](https://www.visualstudio.com/), -Visual Studio Code +As this time, you can only have one top-level workspace folder open in a VS Code window. +This is likely to change in the near future as the VS Code team is working on support +for [multi-folder workspaces](https://github.com/Microsoft/vscode/issues/396). ### Command Palette @@ -57,6 +77,10 @@ you can execute it by pressing Enter. Some commands in Visual Studio Code will use the Command Palette UI to prompt you for other things like string input or a list of selections to choose from. +**TODO: Image** + +TODO: File navigation + ### Activity Bar ### Source Control @@ -92,8 +116,17 @@ the Visual Studio Marketplace. ### Navigating Around the Code +- Document symbols +- Workspace symbols +- Go to definition +- Find References + ### Formatting Your Code +- Formatting the file +- Formatting the selection +- Formatting on save, type, paste + ### Expanding Aliases ## Debugging PowerShell @@ -156,6 +189,10 @@ TODO: Write full descriptions ### Why does the integrated console steal focus when I run the current selection (F8)? +### Why can't I select more than the visible region in the integrated console? + +https://github.com/Microsoft/vscode/issues/9958 + ## Troubleshooting ### Windows From 44486e53343822fad27aa61ab4c8ad105c56751a Mon Sep 17 00:00:00 2001 From: David Wilson Date: Mon, 15 May 2017 12:06:03 -0700 Subject: [PATCH 4/4] Update README.md with User Guide link --- README.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2d0dbc64b9..d96bcafdc9 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,19 @@ to get more details on how to use the extension on these platforms. ## Features -- Syntax highlighting -- Code snippets -- IntelliSense for cmdlets and more -- Rule-based analysis provided by [PowerShell Script Analyzer](http://github.com/PowerShell/PSScriptAnalyzer) -- 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` -- Local script debugging and basic interactive console support! +- PowerShell ISE-like interactive development experience with the PowerShell Integrated Console +- Rich debugging experience including variables view, call stack, watch window, and various breakpoint types +- Integrated script analysis and code fixes provided by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) +- Code navigations that allow you to find definitions and references of functions across your script files +- Highly configurable code formatter based on community best practices +- New file and project creation using [Plaster](https://github.com/PowerShell/Plaster) templates +- Editor scripting API through the [$psEditor object model](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) + +## User Guide + +We have written a complete [User Guide](./docs/UserGuide.md) to help you learn how to use the features +of this extension. If you have any comments or feedback on the User Guide, please feel free to [file an issue](https://github.com/PowerShell/vscode-powershell/issues/new) +or [edit the file](https://github.com/PowerShell/vscode-powershell/edit/master/docs/UserGuide.md) and submit a pull request! ## Quick Installation