Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Add a User Guide for the extension #743

Closed
wants to merge 4 commits into from
Closed

WIP: Add a User Guide for the extension #743

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
978cf3c
Add a User Guide for the extension
daviwil Jan 6, 2017
31a7bfb
Add more outline and possible content
daviwil May 15, 2017
9513bd2
More User Guide contents
daviwil May 15, 2017
44486e5
Update README.md with User Guide link
daviwil May 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
273 changes: 273 additions & 0 deletions docs/UserGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,273 @@
# 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-editor-and-extension)
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. 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

> 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 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.

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.

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

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 <kbd>F1</kbd> or <kbd>Ctrl+Shift+P</kbd>
(<kbd>Cmd+Shift+P</kbd> 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 <kbd>Enter</kbd>.

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

### Integrated Terminal

### Tasks

### 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

> 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.

### IntelliSense

### Analyzing Your Code

- Syntax analysis
- PSScriptAnalyzer
- Code fixes

### 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

> 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 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 <kbd>Ctrl+N</kbd>
- `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: <kbd>Ctrl+Shift+V</kbd>
- Zen mode: <kbd>Ctrl+K Z</kbd>
- Side by side editing: <kbd>Ctrl+\</kbd>

## 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.


### 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)?

### Why can't I select more than the visible region in the integrated console?

https://github.com/Microsoft/vscode/issues/9958

## Troubleshooting

### Windows

#### 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)

#### 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.
80 changes: 1 addition & 79 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!