PowerShell/docs/FAQ.md

179 lines
9.9 KiB
Markdown
Raw Normal View History

2023-08-23 08:03:57 +02:00
![](powershell_black_icon_64x64.png) PowerShell FAQ
===================================================
2021-02-11 07:20:18 +01:00
2023-05-10 13:01:44 +02:00
<details><summary>What is PowerShell?</summary>
2023-05-11 11:08:01 +02:00
2024-05-29 17:22:32 +02:00
**PowerShell is a cross-platform task automation solution made up of a command-line shell, a scripting language, and a configuration management framework. PowerShell runs on Linux, Mac OS, and Windows.**
2023-05-10 12:58:03 +02:00
</details>
2021-02-11 07:20:18 +01:00
2023-05-10 13:01:44 +02:00
<details><summary>Why use PowerShell?</summary>
2023-05-10 13:00:28 +02:00
2024-05-29 17:24:44 +02:00
* **It's powerful** - fully control your computer.
* **It's easy to learn** - see the tutorial at: https://www.guru99.com/powershell-tutorial.html.
* **It's cross-platform** - available for Linux, Mac OS and Windows.
* **It's open-source and free** - see the Github repository at: https://github.com/PowerShell/PowerShell.
* **It's fully documented** - see the official documentation at: https://docs.microsoft.com/en-us/powershell.
2023-05-10 12:59:02 +02:00
</details>
2021-12-22 15:54:05 +01:00
2024-05-31 12:30:12 +02:00
<details><summary>How to learn PowerShell?</summary>
* **Please find tutorials at:** https://www.guru99.com/powershell-tutorial.html
* **See a cheat sheet at:** [PowerShell/Docs/cheat-sheet.md](cheat-sheet.md)
2024-05-31 12:31:36 +02:00
* **Visit the official PowerShell documentation at:** https://docs.microsoft.com/en-us/powershell/
2024-05-31 12:30:12 +02:00
</details>
2023-08-09 16:11:18 +02:00
<details><summary>How to install PowerShell on Linux?</summary>
2024-05-31 12:24:36 +02:00
1. **Execute on Linux with Snap support:**
2023-08-09 16:11:18 +02:00
```
$ snap install PowerShell
$ ln -s /snap/bin/pwsh /usr/bin/pwsh
```
2024-05-31 12:25:33 +02:00
2. **Otherwise, visit:** https://github.com/PowerShell/PowerShell **and scroll down to: *Get PowerShell*.**
2024-05-31 12:45:25 +02:00
3. **Want to configure PowerShell as your default shell?**
* Check that the file **/etc/shells** contains the **/usr/bin/pwsh** line, otherwise add it.
* Now execute: **`chsh -s /usr/bin/pwsh <USERNAME>`** (replace <USERNAME> by your user name).
2023-08-09 16:11:18 +02:00
</details>
<details><summary>How to install PowerShell on MacOS?</summary>
2023-05-10 13:00:28 +02:00
2023-08-23 08:35:22 +02:00
**Please visit:** https://github.com/PowerShell/PowerShell **and scroll down to: 'Get PowerShell'.**
2023-08-09 16:11:18 +02:00
</details>
<details><summary>How to install PowerShell on Windows?</summary>
2024-05-31 12:33:31 +02:00
**It's already preinstalled, but** the script execution policy is *restricted* (forbidden) by default! **Open the *Windows PowerShell (Admin)* console and enter:**
2022-12-29 20:47:33 +01:00
```
2023-10-18 07:51:09 +02:00
> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
2022-12-29 20:47:33 +01:00
```
2023-08-23 08:35:22 +02:00
**NOTE:** the group policy object (GPO) settings of your organization might disallow changes. In that case contact your system administrator for help.
2023-05-10 13:00:28 +02:00
</details>
2021-02-11 07:39:51 +01:00
2023-09-15 15:45:26 +02:00
<details><summary>How to get the Mega collection of PowerShell scripts?</summary>
2023-05-10 13:01:44 +02:00
2024-05-29 16:21:08 +02:00
1. **When using Git, execute in a terminal window:** `git clone https://github.com/fleschutz/PowerShell`
2023-08-23 08:35:22 +02:00
2. **Otherwise, download and unzip it from:** https://github.com/fleschutz/PowerShell/archive/master.zip
2023-05-10 13:00:28 +02:00
</details>
2021-06-30 19:43:40 +02:00
2023-08-09 16:20:35 +02:00
<details><summary>How to execute PowerShell scripts on Windows?</summary>
2023-05-10 14:08:50 +02:00
2023-09-12 14:25:14 +02:00
1. **In the Windows desktop:** right-click the script and select: *Execute with PowerShell*
2024-05-31 12:35:35 +02:00
2. **On the command-line:** launch a terminal application (e.g. *Windows Terminal*), then type: `cd <PATH>`, then: `./<SCRIPT>.ps1`.
2023-09-15 15:52:55 +02:00
3. **By remote login:** use *SSH* to login to the Windows machine, then type: `cd <PATH>`, then: `./<SCRIPT>.ps1`.
4. **By context menu:** see below.
5. **By voice control:** see repo [talk2windows](https://github.com/fleschutz/talk2windows) for more information.
6. **By automation software:** see [Jenkins.io](https://www.jenkins.io) or [AutoHotKey.com](https://www.autohotkey.com/) for more information.
7. **Automatically on login:** see below.
2023-05-10 14:08:50 +02:00
</details>
2023-05-10 14:21:58 +02:00
2023-05-10 14:24:16 +02:00
<details><summary>How to execute PowerShell scripts in Windows context menus?</summary>
2023-08-09 16:30:15 +02:00
* To enable "right-click > New > Windows PowerShell Script" execute `Add_ps1_to_New_context_menu.reg` in subfolder [Data/](../Data)
* To disable this execute `Remove_ps1_from_New_context_menu.reg` in subfolder [Data/](../Data)
2023-05-10 14:24:16 +02:00
</details>
2023-08-09 16:30:15 +02:00
<details><summary>How to execute PowerShell scripts automatically on login in Windows?</summary>
2023-08-23 08:35:22 +02:00
1. **Open the *File Explorer* with your Autostart folder** (usually at: `C:\Users\YOUR_USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup`).
2. **Copy the script (or a link to it) into this folder.**
2023-08-09 16:30:15 +02:00
</details>
2023-05-10 14:24:16 +02:00
2023-05-11 11:12:22 +02:00
<details><summary>How to execute PowerShell scripts in Jenkins?</summary>
2023-08-23 08:35:22 +02:00
1. **Install the Jenkins plugin:** `PowerShell plugin` (it uses PowerShell.exe on Windows and pwsh on Linux).
2. **Add or reference your PowerShell scripts in the Jenkins jobs or in your Jenkinsfiles.**
2023-05-11 11:12:22 +02:00
</details>
2022-09-16 09:12:31 +02:00
2024-05-29 16:17:34 +02:00
<details><summary>What about PowerShell security?</summary>
2022-09-16 09:12:31 +02:00
2024-05-29 16:33:55 +02:00
1. **Do NOT execute scripts from untrusted sources!**
2. **Check the script content for strange things (that's impossible for executables).**
3. **Prefer SSH Remoting instead of PowerShell Remoting**
4. **More recommendations by NSA and cyber security centers in the U.S. (CISA), New Zealand (NZ NCSC), and the U.K. (NCSC-UK) can be found here:** https://media.defense.gov/2022/Jun/22/2003021689/-1/-1/1/CSI_KEEPING_POWERSHELL_SECURITY_MEASURES_TO_USE_AND_EMBRACE_20220622.PDF
2023-05-10 14:08:50 +02:00
</details>
2022-08-30 09:24:51 +02:00
2024-05-29 16:07:10 +02:00
<details><summary>How to get the best PowerShell experience?</summary>
2024-05-29 16:33:55 +02:00
1. **Install *PowerShell* on all your Linux/Mac OS/Windows machines and configure it as default shell.**
2024-05-31 12:21:44 +02:00
2. **For remote control install *SSH client & server* on all your Linux/Mac OS/Windows machines.**
3. **Install the free *Windows Terminal* on Windows with 50% transparency, font 'Fira Code' and no PowerShell banner message.**
4. **To edit PowerShell scripts install the free *Visual Studio Code* with plugin 'PowerShell'.**
5. **Install the *Mega Collection of PowerShell scripts* and set the PATH environment variable to it.**
6. **Use an own PowerShell profile, e.g. execute: './update-powershell-profile.ps1'**
2024-05-29 16:07:10 +02:00
</details>
2023-05-11 11:12:22 +02:00
<details><summary>Why do some scripts show gibberish characters?</summary>
2023-05-10 14:14:57 +02:00
2023-09-15 15:56:46 +02:00
**Your current terminal application doesn't support Unicode characters used by those PowerShell scripts.**
**Use a modern one such as *Windows Terminal*, please.**
2023-05-11 11:12:22 +02:00
</details>
2021-03-29 11:33:47 +02:00
2024-05-15 14:13:40 +02:00
<details><summary>How to set a custom PowerShell profile?</summary>
2023-05-10 14:14:57 +02:00
2024-05-15 14:13:40 +02:00
**Execute: `./update-powershell-profile.ps1` in the *Scripts* subfolder, this will install **my-profile.ps1** as your PowerShell profile. It's a nice looking basic profile and can easily be adapted to your needs.**
2023-05-11 11:12:22 +02:00
</details>
2023-04-21 20:18:23 +02:00
2023-05-10 14:14:57 +02:00
<details><summary>How to add the scripts to the search path?</summary>
2023-05-10 14:12:49 +02:00
2021-02-11 07:20:18 +01:00
Want to use the PowerShell scripts everywhere on the command-line? Then you need to add the Scripts/ subfolder to the search path:
2024-05-15 14:16:18 +02:00
* **On Linux using Bash:** edit .profile in your home directory and add the line: PATH="$PATH:/path/to/PowerShell/scripts (replace '/path/to/)."
2022-08-29 12:42:59 +02:00
* **On Windows:** open Settings > System > About > Advanced system settings > Environment Variables, edit the user's variable "Path", and add the full path to the Scripts/ directory.
2023-05-10 14:12:49 +02:00
</details>
2021-02-11 07:20:18 +01:00
2023-05-11 11:02:05 +02:00
<details><summary>Which editor to use for PowerShell scripts?</summary>
2023-05-10 14:12:49 +02:00
2023-05-11 11:06:42 +02:00
* **Visual Studio Code** - it supports syntax highlighting, on-the-fly problem checking and an integrated PowerShell Console (available for free on Linux, Mac OS and Windows, now recommended by Microsoft).
* **PowerShell ISE** (Integrated Scripting Environment) - the former official PowerShell development environment included with Microsoft Windows.
* **PowerShell Studio** - a powerful PowerShell IDE with module, help, and user interface development tools, high DPI support and regular updates.
* **PowerShell Plus** - an all in one IDE.
* **Atom package** - an add-on with PowerShell language support for Atom.
* **SublimeText package** - an add-on with PowerShell language support for Sublime Text.
2023-09-12 14:31:58 +02:00
* or simply your **favorite text editor** as an alternative.
2023-05-11 11:02:05 +02:00
</details>
2021-04-16 16:43:41 +02:00
2024-05-15 13:48:58 +02:00
<details><summary>How to remove the banner message in PowerShell?</summary>
2024-05-15 13:54:09 +02:00
* **In general:** start powershell.exe with option '-nologo'.
* **For Windows Terminal:** open Settings > Profiles > Windows PowerShell > Command line and add " -nologo".
2024-05-15 13:48:58 +02:00
</details>
2023-05-11 11:02:05 +02:00
<details><summary>How to write good PowerShell scripts?</summary>
2023-05-11 11:16:33 +02:00
**Good PowerShell scripts are both user-friendly and platform-independent. As a starting point I recommend the following:**
2023-05-11 11:02:05 +02:00
2023-09-12 14:17:08 +02:00
* Use the `<verb>-<noun>.ps1` scheme for filenames (e.g. *new-symlink.ps1*). Official approved verbs can be found here: [https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands)
2023-08-23 08:17:21 +02:00
* Use **UTF-8 BOM** encoding to support Unicode characters in the script.
* Add a **comment-based help** at the beginning with: `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`, `.LINK`, and `.NOTES`.
* Check the **requirements** for the script, e.g. `#Requires -RunAsAdministrator`, or `#Requires -Version 3`
* Prefer **command-line options**, else ask the user for help
* Recommended is **Set-StrictMode -Version Latest** to enable additional error checking.
* For readibility use **lowerCamelCase** to name variables, functions, etc.
* Set execute file permissions for Linux: **chmod a+rx <filename>**
* On success exit with error code 0 (**exit 0**), otherwise print the error with keyword **ERROR:** (to support log parsers) and exit the error code (mostly 1)
2023-05-11 11:02:05 +02:00
</details>
2021-02-11 07:20:18 +01:00
2023-08-23 08:27:15 +02:00
<details><summary>Where's the Star History of this repository?</summary>
2023-05-10 14:14:57 +02:00
2023-04-18 15:41:40 +02:00
[![Star History Chart](https://api.star-history.com/svg?repos=fleschutz/PowerShell&type=Date)](https://star-history.com/#fleschutz/PowerShell&Date)
2023-05-11 11:02:05 +02:00
</details>
2023-04-18 15:41:40 +02:00
2023-05-11 11:02:05 +02:00
<details><summary>How to contribute or how to report a bug?</summary>
2023-04-18 15:41:40 +02:00
2023-09-12 14:08:11 +02:00
**If you find something bad (like a bug, error, or any issue), please report it here by opening an Issue.**
**Or even better: Fork the repository, add or fix the script and submit a pull request, so others can participate too.**
2023-05-11 11:02:05 +02:00
</details>
2021-08-30 09:19:10 +02:00
2023-08-04 12:22:37 +02:00
<details><summary>How to donate to this project?</summary>
2023-08-04 12:21:42 +02:00
2023-08-23 08:25:47 +02:00
**Thanks a lot! Just follow this link:** [https://www.paypal.com/paypalme/Fleschutz](https://www.paypal.com/paypalme/Fleschutz)
2023-08-04 12:22:37 +02:00
</details>
2023-08-04 12:21:42 +02:00
2023-05-11 11:10:24 +02:00
<details><summary>What if my question is not answered here?</summary>
2023-08-23 08:23:44 +02:00
**Just send your question by e-mail to:** `markus.fleschutz [at] gmail.com`
2023-05-11 11:10:24 +02:00
</details>