Skip to content

Commit 48df606

Browse files
rjmholtrjmholt
authored
Add first steps to ISE compatibility doc (#1632)
* Add ISE compatibility doc * Add section to troubleshooting on ISE parity
1 parent 61caa7f commit 48df606

File tree

2 files changed

+139
-0
lines changed

2 files changed

+139
-0
lines changed

‎docs/ise_compatibility.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# ISE Compatibility
2+
3+
While the PowerShell extension for VSCode does not seek
4+
complete feature parity with the PowerShell ISE,
5+
there are features in place to make the VSCode experience more natural
6+
for users of the ISE.
7+
8+
This document tries to list settings you can configure in VSCode
9+
to make the user experience a bit more familiar compared to the ISE.
10+
11+
## Key bindings
12+
13+
| Function | ISE Binding | VSCode Binding |
14+
| ---------------- | ----------- | -------------- |
15+
| Interrupt and break debugger | <kbd>Ctrl</kbd>+<kbd>B</kbd> | <kbd>F6</kbd> |
16+
| Execute current line/highlighted text | <kbd>F8</kbd> | <kbd>F8</kbd> |
17+
| List available snippets | <kbd>Ctrl</kbd>+<kbd>J</kbd> | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>J</kbd> |
18+
19+
### Custom Keybindings
20+
21+
You can [configure your own keybindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)
22+
in VSCode as well.
23+
24+
## Tab completion
25+
26+
To enable more ISE-like tab completion, add this setting:
27+
28+
```json
29+
"editor.tabCompletion": "on"
30+
```
31+
32+
This is a setting added directly to VSCode (rather than in the extension),
33+
so its behavior is determined by VSCode directly and cannot be changed by the extension.
34+
35+
## No focus on console when executing
36+
37+
To keep the focus in the editor when you execute with <kbd>F8</kbd>:
38+
39+
```json
40+
"powershell.integratedConsole.focusConsoleOnExecute": false
41+
```
42+
43+
The default is `true` for accessibility purposes.
44+
45+
## Do not start integrated console on startup
46+
47+
To stop the integrated console on startup, set:
48+
49+
```json
50+
"powershell.integratedConsole.showOnStartup": false
51+
```
52+
53+
**Note:** The background PowerShell process will still start,
54+
since that provides intellisense, script analysis, symbol navigation, etc.
55+
But the console will not be shown.
56+
57+
## Assume files are PowerShell by default
58+
59+
To make new/untitled files register as PowerShell by default:
60+
61+
```json
62+
"files.defaultLanguage": "powershell"
63+
```
64+
65+
## Color scheme
66+
67+
There are a number of ISE themes available for VSCode
68+
to make the editor look much more like the ISE.
69+
70+
In the [Command Palette]
71+
type `theme` to get `Preferences: Color Theme` and press <kbd>Enter</kbd>.
72+
In the drop down list, select `PowerShell ISE`.
73+
74+
You can set this in the settings with:
75+
76+
```json
77+
"workbench.colorTheme": "PowerShell ISE"
78+
```
79+
80+
## PowerShell Command Explorer
81+
82+
Thanks to the work of [@corbob](https://github.com/corbob),
83+
the PowerShell extension has the beginnings of its own command explorer.
84+
85+
In the [Command Palette]
86+
enter `PowerShell Command Explorer` and press <kbd>Enter</kbd>.
87+
88+
## Open in the ISE
89+
90+
If you end up wanting to open a file in the ISE anyway,
91+
you can use <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd>.
92+
93+
## Other resources
94+
95+
- 4sysops has [a great article](https://4sysops.com/archives/make-visual-studio-code-look-and-behave-like-powershell-ise/)
96+
on configuring VSCode to be more like the ISE.
97+
- Mike F Robbins has [a really good post](https://mikefrobbins.com/2017/08/24/how-to-install-visual-studio-code-and-configure-it-as-a-replacement-for-the-powershell-ise/) on setting up VSCode.
98+
- Learn PowerShell has [an excellent write up](https://www.learnpwsh.com/setup-vs-code-for-powershell/)
99+
on getting VSCode setup for PowerShell.
100+
101+
## More settings
102+
103+
If you know of more ways to make VSCode feel more familiar
104+
for ISE users, please contribute to this doc.
105+
If there's a compatibility configuration you're looking for,
106+
but you can't find any way to enable it,
107+
please [open an issue](https://github.com/PowerShell/vscode-powershell/issues/new/choose)
108+
and ask away!
109+
110+
We are always happy to accept PRs and contributions as well!
111+
112+
## VSCode Tips
113+
114+
### Command Palette
115+
116+
<kbd>F1</kbd> OR <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>
117+
(<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on macOS)
118+
119+
A handy way of executing commands in VSCode.
120+
See [the VSCode docs](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
121+
for more details.
122+
123+
[Command Palette]: #command-palette

‎docs/troubleshooting.md

+16
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,22 @@ Instead syntax highlighting for VSCode, Atom, SublimeText and even GitHub is
1616
provided by the [Editor Syntax] repository on GitHub. Please open any
1717
[syntax highlighting issues there].
1818

19+
## VSCode is not working like the ISE
20+
21+
The PowerShell extension does not aim to perfectly recreate
22+
the experience of the PowerShell ISE.
23+
However, we do want to support compatibility whenever possible
24+
to do so without breaking existing functionality.
25+
26+
Please see [the ISE compatibility doc](./ise_compatibility.md)
27+
for ways to configure VSCode to be closer to the ISE.
28+
29+
Bear in mind that many of the UI/UX aspects of VSCode are driven by
30+
VSCode itself and can't be changed by the extension.
31+
The VSCode maintainers are quite reasonable though,
32+
and you can ask for new features [in their repository](https://github.com/Microsoft/vscode).
33+
34+
1935
## Known Issues in the Extension
2036

2137
- Highlighting/completions/command history don't work as I expect in the

0 commit comments

Comments
 (0)