PowerShell is a shell and a scripting language in one. You type a command and get a result, and later you can write the same command into a file and let it run automatically. This course takes you from the first command to runbooks that show what they would do before every change. In this first lesson you learn which PowerShell you are actually sitting in, how a command is built, and how to help yourself when you do not know one. The course is general: everything runs on Windows, Linux and macOS unless the text says otherwise.

All examples in this course were run in PowerShell 7.6.9 on Windows 11, and the output shown comes from that run. Where your output differs (date, language of messages, paths), the text says so.

Two programs side by side

On a Windows machine there are two different PowerShells, and both can be installed at once:

  • Windows PowerShell 5.1 is the program powershell.exe. It is part of Windows and is built on the .NET Framework.
  • PowerShell 7 is the program pwsh (on Windows pwsh.exe), is built on modern .NET and also runs on Linux and macOS.

Microsoft Learn describes that PowerShell 7 runs side by side with Windows PowerShell 5.1: its own install folder, its own program name, its own module path, its own profiles. The new name pwsh makes it possible to run both versions next to each other. This course teaches PowerShell 7; Windows PowerShell 5.1 appears only where behavior differs.

Which session you have in front of you is told by the automatic variable $PSVersionTable. First in PowerShell 7:

PowerShell
$PSVersionTable.PSVersion.ToString()
$PSVersionTable.PSEdition
7.6.9
Core

The same two lines from inside powershell.exe:

5.1.26100.9711
Desktop

Core and Desktop are the two editions: Core is PowerShell 7 on modern .NET, Desktop is Windows PowerShell on the .NET Framework. A script that relies on a feature of one edition can check the edition. Usually it is enough to demand in the script that it runs with pwsh, and to say so in the first line:

PowerShell
#Requires -Version 7.0

If the script runs in an older version, PowerShell stops with a message before the first line can do any harm.

New language features arrive in PowerShell 7 (Learn names the ternary form condition ? a : b and ForEach-Object -Parallel as examples). If a module runs only in Windows PowerShell 5.1, PowerShell 7 can load it through a compatibility layer; Learn describes this under “PowerShell 7 module compatibility”. We return to this in module PS.4 when it comes to Azure.

The first command

Start pwsh (in Windows Terminal, in VS Code or in a console). A line that you type and confirm with Enter is called a command. The simplest one:

PowerShell
Get-Date

Get-Date returns the current date and time. The command has two parts, verb and noun, separated by a hyphen: Get and Date. Commands like this are called cmdlets (pronounced “command-lets”). The pattern is the same everywhere, and that is the biggest help when learning: whoever knows Get-Process guesses Get-Service, Get-Item, Get-Content; whoever knows Remove-Item guesses Remove-Service. Verbs with the same meaning exist only once (Get, never Fetch or Read). The list of approved verbs comes from a cmdlet:

PowerShell
Get-Verb | Select-Object -First 3 -Property Verb, Group

The columns Verb and Group show the first verbs (Add, Clear, Close) and their group (Common). If you see the description in your language, it can read differently on your machine than in the course.

That there are not only cmdlets is shown by Get-Command:

PowerShell
(Get-Command Get-ChildItem).CommandType
(Get-Command Get-ChildItem).Source
Cmdlet
Microsoft.PowerShell.Management

Cmdlet is one of several kinds of commands. There are also Function (written in PowerShell itself, lesson PS.2.2), Alias (a short name, see below), Application (a program such as git.exe) and ExternalScript (a .ps1 file). For you as a user the kinds behave alike. Source says which module a cmdlet comes from: a module bundles related commands (Microsoft.PowerShell.Management for files, processes, services).

Finding commands

You do not have to know all cmdlets. You need three ways to find them:

PowerShell
Get-Command -Verb Get -Noun Process*
Get-Process
Get-ProcessMitigation

(the output on Windows; on Linux and macOS there is no Get-ProcessMitigation). -Verb and -Noun filter, * stands for any number of characters. If you only know that the noun has something to do with “Service”, Get-Command *Service* is enough. The second way is Get-Help (next section), the third is the documentation on Learn.

Parameters: name, position, switch

A command gets its input through parameters. A parameter begins with a hyphen, then comes its name and, if it needs a value, the value:

PowerShell
Get-Process -Name pwsh

Parameters have different properties, and you can look them up. This is how Get-Help shows the details of -Name of Get-Process:

PowerShell
Get-Help Get-Process -Parameter Name

The output names the type (<string[]>, so one or more strings), whether the parameter is required (not here), its position (0), whether it takes input from the pipeline (ByPropertyName, more in lesson PS.1.2) and which aliases it has (ProcessName). On the machine of this course the labels are in German (“Erforderlich?” falsch), on an English system “Required? false”.

From the position it follows: a parameter with position 0 may stand without its name. The two lines mean the same:

PowerShell
Get-Process -Name pwsh
Get-Process pwsh

In a script you always write out the name, because otherwise the reader has to guess. On the command line you type the short form.

A third kind are switches (switch parameters): they have no value. They are there or they are not. -Recurse of Get-ChildItem says “also in subfolders”. Important switches meet you again in lesson PS.3.1: -WhatIf and -Confirm are switches.

Which parameters a cmdlet has at all is shown by:

PowerShell
(Get-Command Get-Process).Parameters.Keys | Select-Object -First 6
Name
Id
InputObject
IncludeUserName
Module
FileVersionInfo

The first six of many. In addition every cmdlet gets the common parameters (-Verbose, -ErrorAction, -WhatIf for cmdlets that change something, and more), which we introduce one by one in the next lessons.

Tab completion: type Get-Pro and press Tab: PowerShell completes Get-Process. Type Get-Process -N and Tab: -Name. Tab also shows the permitted values of a parameter when there are only a few. Whoever uses Tab types less and makes fewer typos.

Help

Get-Help shows the help for a command: syntax, description, parameters, examples. The usual forms:

PowerShell
Get-Help Get-ChildItem
Get-Help Get-ChildItem -Examples
Get-Help Get-ChildItem -Full
Get-Help Get-ChildItem -Online

-Examples shows only the examples (the fastest way to understand a cmdlet), -Full everything, -Online opens the page on Learn in the browser. With a pattern instead of a command name Get-Help also searches the topic articles, the about_ help (Get-Help about_Pipelines).

The help files are not built into PowerShell, they are downloaded with Update-Help (this needs network access; for which accounts it applies and which rights it needs is in the help of Update-Help). If the help is missing, Get-Help shows only the syntax. The pages on Learn are the complete version in both cases.

Aliases

An alias is a short name for a command:

PowerShell
Get-Alias ls
Get-Command -Name gci | Select-Object Name, CommandType, Definition | Format-List
Name Definition
---- ----------
ls   Get-ChildItem

Name        : gci
CommandType : Alias
Definition  : Get-ChildItem

Here you see that ls and gci both stand for Get-ChildItem. On the command line aliases are convenient. In scripts they never appear, for three reasons:

  1. They are hard for readers to read (gci, %, ?), and a script is read more often than written.
  2. An alias can be missing on another machine or mean something else, because anyone can create their own (for example in the profile).
  3. The analyzer that checks scripts (lesson PS.4.2) warns about aliases.

The tool of choice is: on the command line tab completion and short names, in the script the full name.

The profile and the editor

At startup pwsh reads a profile: a script that you create yourself and that sets your habits (aliases, colors, functions). The path is named by the variable $PROFILE. Learn describes that every PowerShell version has its own profile, so the profile of Windows PowerShell 5.1 does not apply to pwsh. A profile is only for interactive work: scripts that you give to others or let run automatically must never depend on it. Start pwsh with -NoProfile to skip the profile, and do so in every automatic call (pwsh -NoProfile -File …). The examples in the rest of the course do so.

As an editor, Visual Studio Code with the PowerShell extension is a good choice: it gives you tab completion, help while typing and a debugger. A terminal that displays PowerShell well (Windows Terminal on Windows) saves you trouble with umlauts and colors.

Exercise 1: Explore the session

  1. Start pwsh and read $PSVersionTable.PSVersion and $PSVersionTable.PSEdition. If Windows PowerShell 5.1 is installed, start powershell.exe and compare.
  2. Find all cmdlets whose noun ends in Item (Get-Command -Noun *Item).
  3. How many parameters does Get-Date have? Hint: (Get-Command Get-Date).Parameters.Count.

Solution 1

  1. With PowerShell 7 it says 7.x.y and Core, with Windows PowerShell 5.1.… and Desktop.
  2. Get-Command -Noun *Item lists among others Get-Item, New-Item, Remove-Item, Copy-Item and Move-Item (on the machine of this course also some cmdlets of other modules, such as Get-ControlPanelItem): the same nouns, different verbs, so you learn whole families at once.
  3. The number depends on the version and includes the common parameters (25 here). What matters is the way: .Parameters is a collection, .Count counts it.

Exercise 2: Read help

  1. Call Get-Help Get-ChildItem -Examples. Which example shows how to find only files with a certain extension?
  2. Which position does the parameter -Path of Get-ChildItem have, and from which source does it take pipeline input? (Get-Help Get-ChildItem -Parameter Path)
  3. Why is gci -r -fo a bad way to write a script file, and what is the good way?

Solution 2

  1. The example that shows -Filter or -Include with *.txt (the examples are numbered and described; the numbers change between versions).
  2. -Path has position 0 and takes pipeline input by value and by property name (ByValue, ByPropertyName); that is how the help reads on this machine, where the labels are in German.
  3. gci is an alias, -r and -fo are abbreviated parameters (-Recurse, -Force); both read badly and can become ambiguous when new parameters appear. Good: Get-ChildItem -Recurse -Force.

Exercise 3: Compare two programs

  1. Run Get-Command Get-ChildItem | Select-Object CommandType, Source once in pwsh and once (if present) in powershell.exe.
  2. Write a script version.ps1 with the line #Requires -Version 7.0 and a line $PSVersionTable.PSVersion.ToString(). Start it with pwsh -NoProfile -File .\version.ps1 and with powershell.exe -NoProfile -File .\version.ps1. What happens, and what does the exit code ($LASTEXITCODE) say?

Solution 3

  1. Both return Cmdlet and a module; the source can differ (Microsoft.PowerShell.Management). What matters: the same name, but two different programs behind it.
  2. In pwsh the script prints the version. In Windows PowerShell 5.1 it stops with a message that the #requires statement for version 7.0 does not match the running version 5.1, and $LASTEXITCODE is 1. The check saves you from half a script that runs halfway in the wrong version. (The exact text of the message depends on the system language. Read the exit code without sending the command through Select-Object -First: why is in lesson PS.2.3.)

What you can do now

  • You tell pwsh (PowerShell 7) and powershell.exe (Windows PowerShell 5.1) apart and read the version from $PSVersionTable.
  • You read a command as verb-noun with parameters and know name, position and switch.
  • You find commands with Get-Command and help with Get-Help -Examples.
  • You recognize aliases and write the full names in scripts.
  • You start automations with -NoProfile so that they do not depend on your profile.

The next lesson shows what a command actually returns: not lines of text, but objects. That changes everything.

Further reading