Windows PowerShell is the successor of the MS-Windows cmd language, which itself has its roots in the ms-dos Bat language. All recent versions of Windows offer PowerShell (PS). PS may be seen as Microsoft's answer to the shells common in Unix/Linux (such as Csh, Bash, etc.). Its name implies that Microsoft sees the shell as powerful, which it arguably is.
In these notes some important PS commands are listed and PowerShell's most notable feature, the object pipeline, is discussed. From the outset it is important to note that, in contrast to Linux/Unix, Windows PowerShell is completely case-insensitive.
Most monospace text snippets below are valid PS and may be copied, pasted, and executed in a PowerShell- or a PowerShell_ISE-session. This is why the notes form a "Cheatsheet". As is common for cheatsheets, there is hardly any explanation, the examples speak for themselves. It must be stressed here that many of the basic PS commands are not at all orthogonal, so that many variant pipelines can lead to the same effect. The examples just give one out of the several possibilities to accomplish a certain task.
The last two sections are about search in and traversal of the Windows Registry by means of PowerShell.
Unrelated to PS
A few lesser known windows features and tricks, not directly related to PowerShell:
- In the Windows (File) Explorer address bar enter
cmd, powershell.exe, or powershell_ise and a corresponding window opens at the current directory. This is most likely the shortest route to opening a cmd, ps, or ps_ise session from a given directory.
- Typing
Control Panel (nl: Configuratiescherm), Regedit, powershell, ... after hitting the start or search button in the Windows taskbar opens a screen with the name of the program. Click on it once and the program opens.
- In PS:
Get-WmiObject win32_useraccount gives the SID's (security identifiers) of accounts on present computer.
- Adaptation of user environment variables:
Control Panel/User Accounts/User Accounts/. Then left panel: change my environment variables.
- Adaptation of system environment variables:
Control Panel/System and Security/System/Advanced System Settings. Button: Environment Variables. Set in panel system variable not in administrator account. Change is persistent, a change (see below) within PowerShell is volatile.
- In a cmd session:
setx sets persistent user environment variable. To unset: go to HKCU/environment (in the Registry) or to Control Panel/User Accounts.
- In a cmd session:
doskey np = notepad++ $* sets alias for notepad++.exe fn.ft (provided notepad++ is in path)
About ISE
ISE stands for Integrated Scripting Environment. ISE—a standard part of Windows 10—is an editing and execution environment for PowerShell.
An important advantage of the use of ISE over pure PowerShell, is that ISE offers pop-up help: when the user is typing a command line, ISE often pops up a relevant list of methods and properties. By double clicking on an entry in the pop-up list, the entry is appended to the command line.
A few noticeable points:
- Upon the start of ISE, the script
Microsoft.PowerShellISE_profile.ps1 is executed.
- To protect ordinary users against malignant PS scripts, the execution of PowerShell scripts (including the ISE profile) must be allowed explicitly. This is done once and for all by issuing the command
Set-ExecutionPolicy RemoteSigned
-Scope CurrentUser
- Allow execution of a script downloaded from the internet by:
unblock-file .\script.ps1
where script is the name of the downloaded script (which is in the current directory).
- Execution of a script requires that the scriptname is prefixed by its path. If the script is in the present folder use
.\script.ps1, where script is the name of the script.
- Set width and height of the output pane by:
$Host.UI.RawUI.BufferSize = New-Object
$Host.UI.RawUI.BufferSize.GetType().Fullname (150, 40)
(The pure PS console does not allow shrinking of width).
- Set ISE console fontsize by:
$Host.PrivateData.FontSize = 13
(pure PS has a different $Host.PrivateData object).
- Start PowerShell as administrator:
Start-Process PowerShell -Verb runAs
- An important ISE tool for PowerShell learners is CTRL-J. This pops up a selection of code snippets. These are templates that give illustrative examples of PS syntax and can be used in scripts as a start points for further editing.
Notepad++
Provided the correct path is set, notepad++.exe start the Notepad++ editor from a PS session. Or set an alias by: set-alias -name np -value "C:\Program Files (x86)\notepad++\notepad++.exe" and then np opens Notepad++.
Cmdlets
The internal commands of PowerShell are called "cmdlets". A cmdlet name is of the form "verb-noun", where "verb" is one out of a fixed set of verbs. All cmdlets return an object. For instance,
Get-ChildItem .\
returns an array object of which the elements are objects belonging to the children of the current folder (.\). If the whole object is to be inspected, pipe it to Get-Member (see below). Any cmdlet flag (= parameter) can be truncated to the extent that it is still unique. A few examples of cmdlets and their flags:
Get-Help # Gets help about a cmdlet,
# example: get-help get-help
Get-PSdrive # List PSdrives, such
# as c:, env:, hklm:, hkcu:, alias:, etc.
Get-ChildItem # In Registry: children are subkeys
# and value entries in current key.
Get-ChildItem # In File System: children are
# subdirectories and filenames in current directory.
Get-ChildItem -recurse # Lists all children, grandchildren, ...
# of current PSdrive, directory, or Registry key.
Get-ChildItem -rec -force # Include hidden directories
# (flag -hidden searches hidden directories only)
(Get-ChildItem .\).name # List names ('name' is an object property)
# of files and directories in current directory.
Get-ChildItem -name # Equivalent to
# (Get-ChildItem .\).name
(Get-ChildItem .\).count # Number of entries in the array object returned by Get-ChildItem
# (count is a property of an array).
GoTo a PSdrive
To switch a PS session to another PSdrive or directory and get the children of the new location, proceed as follows:To env:
Set-Location env: # Prompt character
# becomes PS Env:\> (environment variables)
Get-Childitem # Get all environment
# variables
Get-Childitem userprofile # Get environment variable
# userprofile=C:\Users\user_name
To alias:
Set-Location alias: # To PS-Drive alias
Get-Childitem # All aliases
Switch to c:\users and get a named child from another PSDrive:
Set-Location c:\users # Back to filesystem c: (
# directory users)
$env:userprofile # Get environment variable
# (note the $ in $env:) userprofile=C:\Users\user_name
$alias:ls # Get what alias 'ls' stands for
# --> Get-ChildItem (Note the $ in $alias:)
Pipelines
Important: Cmdlets pass objects through pipelines, not a character stream as in Unix.
The pipeline character is |, it must be followed by a cmdlet. The passed pipeline object is referred to by the automatic variable $_ and its member member_name is accordingly referred to by $_.member_name.The treatment of the passed object $_ depends on the cmdlet it is passed to. To illustrate this, it is noted that a PowerShell string is an object with many methods, one of them being .contains("substr"). The method returns true if the string contains "substr" and false if not. In the following example the stuff between curly brackets is a script block which is a sequence of executable statements. Now pass the very same string object to two different cmdlets:
"a string" | Foreach-Object {$_.contains("ri")} # -> True
"a string" | Where-Object {$_.contains("ri")} # -> "a string"
In both commands it is tested whether "ri" is a substring of "a string" (which it is). The first cmdlet passes on the resulting boolean value which drops off the end of the pipeline and is then sent to the console. The second cmdlet uses the boolean result to decide what to do: if true the string is passed on in the pipeline (and as it is at the end it is sent the console). If false where-object stops the pipeline and no console output is generated.The cmdlet Get-ChildItem not only gets children of a directory (files and subdirectories), but also an array of children of any PSdrive:
Get-ChildItem alias: # All children of alias: all defined aliases
In the next three pipelined statements it is assumed that all elements (also objects) of the array passed through the pipeline have a member called name. The name name must be known by the cmdlet that handles the pipelined input.
Get-ChildItem alias: |Where-Object {$_.name -eq 'ls'}# Gives: "Alias ls -> Get-ChildItem"
Get-ChildItem alias: |Where-Object name -eq 'ls' # Gives: "Alias ls -> Get-ChildItem"
Get-ChildItem alias: |Where-Object name -match 'ls' # Gives three matching aliases (ls, sls, and cls).
The second and third commands do not use a script block but the short-hand name. Shorter, use Get-Alias (no pipeline):
Get-Alias ls # Gives: "Alias ls -> Get-ChildItem"
gal ls # Gives same.
The names of members (methods and properties) of an object are obtained by piping the object to Get-Member. Example:
Get-Process PowerShell_ise |Get-Member # Short: ps PowerShell_ise |gm
This gives:
Name MemberType Definition
---- ---------- ----------
Handles AliasProperty Handles = Handlecount
Name AliasProperty Name = ProcessName
...
GetType Method type GetType()
InitializeLifetimeService Method System.Object InitializeLifetimeService()
Kill Method void Kill()
...
Id Property int Id {get;}
MachineName Property string MachineName {get;}
...
ProcessName Property string ProcessName {get;}
StartTime Property datetime StartTime {get;}
...
Knowing property names we can pass them to Select-Object to get their values,
Get-Process PowerShell_ise |Select-Object name, id, processname, starttime # names separated by comma's
This gives:
Name Id ProcessName StartTime
---- -- ----------- ---------
PowerShell_ise 6732 PowerShell_ise 12/14/2017 11:05:47 AM
The cmdlet Where-Object acts as a filter, it transfers objects through the pipeline that satisfy a boolean condition. The cmdlet Get-Process gets objects for all running processes.
Get-Process |Where-Object name -match PowerShell_ise
|Select-Object name, id, processname, starttime
This gives again:
Name Id ProcessName StartTime
---- -- ----------- ---------
PowerShell_ise 6732 PowerShell_ise 12/14/2017 11:05:47 AM
Many of the property names and their values are obtained by piping an object to Format-List *. Methods are not listed.
Get-Process PowerShell_ise | Format-List *
This gives:
Name : PowerShell_ise
Id : 6732
...
StartTime : 12/14/2017 11:05:47 AM
...
UserProcessorTime : 00:00:46.3750000
...
Container :
Useful aliases
Many cmdlets have one or more aliases. Often an alias is DOS- or Unix-like.
ac = Add-Content # Example: ac -value 'The End' -path 'flop.txt'
# (appends value to file)
cat = gc = type = Get-Content # Get the content of a file;
# returns an array with one line per element
cd = sl = Set-Location # Change folder, Registry key, or PSdrive.
# Example: cd env:, cd HKLM:
cls = clear = Clear-Host # Clears console
#
dir = gci = ls = Get-Childitem # List children in current
# PSdrive/folder/Registry key
echo = write = Write-Output # String to output array. Array is sent to console, into
# pipeline, or redirected/appended to file
foreach = % = Foreach-Object # Only in pipeline: for each object crossing the pipeline
# Do not confuse with language construct of the same name
ft = Format-Table # Only in pipeline.
# Example: ls *.jpg |ft directory, length, name -AutoSize -Wrap
fl = Format-List # Only in pipeline. Example: ls env:\Path |fl
# (gives wrapped output of environment variable "Path")
gal = Get-Alias # "Get-Alias -definition cmdlet", gives aliases of cmdlet
# "Get-Alias [-name] alias", gives name of cmdlet called by alias
gcm = Get-Command # Get all commands (cmdlets, functions, and aliases).
# gcm -CommandType Alias -> all aliases
gm = Get-Member # Example: ls flop.txt | gm
# (all members of object flop.txt)
gp = Get-ItemProperty # In file system: gp * gives same output as ls *
# In Registry: value entries (names and values)
gpv = Get-ItemPropertyValue # In filesystem: get prop's of files. Ex: gpv *.txt -name basename (names of .txt files)
# In Registry: get value of value entry. Example: gpv -name cursorsize (returns number)
gv = Get-Variable # Get names and values of
# all session variables
ps = gps = Get-Process # List running processes
#
pwd = gl = Get-Location # Current directory (folder)
# or Registry key
ren = rni = Rename-Item # Examples: ren report.doc report.txt
# and: ls report.doc | ren -newname report.txt
rv = Remove-Variable # Remove variable (name without $ prefix, while
# note that variable names must begin with $)
select = Select-Object # Select specified properties of piped object
# Example: ps |select Processname | select -first 10
sleep = Start-Sleep # Sleep -sec 1
# (sleep 1 second)
sls = Select-String # Example: sls foo.txt -patt '^\S' (a regular expression
# giving all lines that do not start with blank, tab, or EOL)
where = ? = Where-Object # Only in pipeline.
# Example: ls -recurse |? name -like '*Pict*'
Example of a pipelined command
The following pipelined command may be issued from C:\Program Files, for example. It outputs the names of .dll files of size less than 10000 bytes in the directory and all its subdirectories:
Get-ChildItem -recurse -path *.dll | Where-Object {$_.length -lt 10000} |
Sort-Object -property Length | Format-Table -property name, length, directory -wrap
The flag -path, being default, can be omitted. The command can be shortened further by introducing aliases and abbreviated flags. For clarity, the statement is split by assigning an array object to the variable $a. (Recall here that variable names are text strings that begin with a dollar sign). Note that the cmdlet Where-Object = ? can recognize names of object properties without use of a script block. That is, {$_.length -lt 10000} is equivalent to length -lt 10000. Thus,
$a = ls -r *.dll |? length -lt 10000 # Store in $a all .dll files from current directory downward
# with file sizes < 10000 bytes
The array object $a is piped to the alias sort of the cmdlet Sort-Object and the sorted object goes to Format-Table:
$a | sort length | ft name, length, directory -w # Sort entries of array $a on file size (length) and tabulate
# formatted name, length, and directory
Finally, in one statement:
ls -r *.dll |? length -lt 10000 |sort length |ft name, length, directory -w
More examples of pipelines
An alias is not the same object as the corresponding cmdlet. This is proved by the inspection of the output of the following:
gcm ls | fl * # All properties of the alias 'ls' are listed
gcm Get-Childitem | fl * # All properties of the cmdlet 'Get-Childitem' are listed
List properties (names and values) of the file object PSnotes.txt:
ls PSnotes.txt |fl * # Lists all properties: Directory, LastAccessTime, Basename, etc.
ls PSnotes.txt |fl LastAccessTime, Basename # Lists two properties: date/time of last access and file name.
If you want to tabulate names and values of one or more properties then pipe to ft. Example:
ls PSnotes.txt |ft LastAccessTime, Basename # Tabulates date and time of last access and file name
List the content of the lines in foo.out that begin with four or more spaces together with their sequence numbers:
sls foo.out -patt '^[ ]{4,}'|ft linenumber, line
(Note that an empty line may not contain spaces and is then not shown by this command).The difference between tabulating (ft) and listing (fl) properties is minor.An example of ?=Where-Object: select the basenames (file names without extension) of files in current directory that end with the letter r (use of operator -match with a regexp):
ls |? basename -match 'r$'
This lists the matching basenames plus additional information (mode, write time, length, full file name). If only the basename must be listed, use:
ls |? basename -match 'r$' |ft basename
Other examples of ?. Use of comparison operators -in, -notmatch, -and, -notlike. The first example limits the list of 'svchost' and 'firefox' processes to the first 10. The second example uses a script block, which is the code snippet between curly brackets:
ps |? ProcessName -in "svchost", "firefox" | select -f 10 |ft processname, PagedMemorySize
ls |? {$_.name -notmatch 'e$' -and $_.name -notlike 'c*'}
# (Names not ending on "e" (regexp) or beginning with "c")
How long did Notepad++ run? The cmdlet Format-Table recognizes as parameter a hash table (@{..;..}) with entries L(abel) and E(xpression) defining the header and entries of the table sent to the PS console:
ps Notepad++ | ft ProcessName, @{L="WallClock time"; E={(Get-Date) - $_.StartTime}}
This gives something like:
ProcessName WallClock time
----------- --------------
notepad++ 07:44:35.0765408
The number under the heading 'WallClock time' is the result of the expression (an elapsed time).
As a last example, the string 'was' is found in all .txt files in the present directory by application of Select-String = sls:
sls *.txt -pattern 'was' |ft -wrap filename, linenumber, line
Find all directories called winx from the present directory downward (-rec). Inspect also hidden directories (-force) and suppress error messages (-ea 0):
ls winx -dir -rec -force -ea 0 |ft
Examples foreach
Remember that % is an alias for ForEach-Object, as is foreach.
Get-Alias |% {if ($_.name -match '^s') {Write-Host $_.name, $_.definition}}
Get-Alias sends 158 objects (aliases) through the pipeline. All objects have a property name, which is matched against a regexp. The regexp checks if the first letter is 's' or 'S'. If so, the properties name and definition of the current object are written to screen. The body of the Foreach-Object must be enclosed by curly brackets (the outer ones), and so must the body of the true branch.Note that a list of aliases starting with 's' or 'S' can be obtained from shorter Where-Object statements:
Get-Alias |? name -match '^s' # regexp
Get-alias |? name -like 's*' # string + wildcard
And still shorter:
gal s*
Count number of lines of each member of a list of .txt files (every filename followed by single space and number of lines):
ls *.txt |% {Write-host ($_.name, " ") -NoNewline; (cat $_).count }
Remember that cat returns an array object that has the property count.The present file, called PS_cheat_sheet.html, contains several terms in bold font, surrounded by and . The following PS pipeline extracts (almost) all bold text strings from it that occur first on a line. (The command does not work correctly when bold text extends over different lines):
sls -path PS_cheat_sheet.html -pattern '' |% {$_.line -match '(.*?).*' |out-null; $matches[1]}
The sls (select-string) command returns all lines containing .*?. The question mark indicates "non-greediness", at most one match is found on on each line. The output (true or false) of the match expression is sent to /dev/null, in powershell: out-null. The capture is caught in $matches[1], the second element of the automatic array $matches.An example of foreach as a language construct: $letterArray = "a","b","c","d"
foreach($letter in $letterArray){
Write-Host -ForeGroundColor green $letter
}
Yet another example as language construct:
$ff = ps firefox # Usually there is more than one firefox process active
foreach($p in $ff) {$p.starttime}
This gives something like (in Dutch):
zaterdag 8 juni 2019 07:47:44
zaterdag 8 juni 2019 13:53:41
zaterdag 8 juni 2019 07:47:30
zaterdag 8 juni 2019 07:47:28
zaterdag 8 juni 2019 15:21:39
zaterdag 8 juni 2019 13:42:46
zaterdag 8 juni 2019 11:52:45
Incidentally, the very same output is obtained by:
ps firefox |select-object -expandproperty starttime
The flag -expandproperty of select-object (alias: select) expands the date in property starttime to a long notation.
Bracketed subexpressions of a regular expression are captured in the automatic array $matches and foreach can loop over this array. To get a sorted list of the unique verbs of all aliases, issue:
gal|? displayname -match '->(.*)-.*' |% {write $matches[1]} |select -Unique |sort
Datatypes and strings
Type cast operators are among others: [int], [long], [string], [char], [bool], [byte], [double], [decimal], [single], [array], [xml], [hashtable], [PSCustomObject].Once a variable is declared explicitly, an implicit type change is forbidden. Examples:
[string]$s = 'Peanuts' # Explicit declaration
$s = 4 # Assign new string '4'
$s * 3 # Gives 444 (triplicates the string)
[int]$s = 4 # Explicit change of type (to int32)
$s * 3 # Gives 12
$s = 'bear' # Error --> Cannot convert value "bear" to type "System.Int32"
[string]$s = 'bear' # Explicit recasting is OK
$s = [char]0x07 # Recasting is OK on RHS (hex-char 0x07 sounds "Bell", warning sound)
Another type casting example:
'a', 'b', 'c', 'd' > letters.txt # Each letter on a line in file letters.txt. Output in UTF-16 (!)
[string]$letter = cat letters.txt # Get-Content, assign to string
$letter # --> a b c d (a single string)
$letter = [string](cat letters.txt) # The same. Brackets are necessary to cast the output of the cmdlet
Use set to assign a constant:
set pi 3.14 -opt const # Assign constant; (No $ in set pi !)
$pi # Gives 3.14 (Use $ in reference to the constant just set without $!)
$pi = 2 # -> Error: Cannot overwrite variable pi because it is read-only or constant.
set pie $([math]::pi) -opt const
$pie # -> 3.14159265358979
Arrays
$a = @('a', 'b') # Array (round brackets, colons as separators)
$a += 'c' # Push 'c'
$a += 'd' # Push 'd'
$a # --> a\n b\n c\n d (vertical stack)
$a.GetType() # --> True True Object[] System.Array
$arry = 1,2,3,4,5 # Array, $arry[0] is 1, $arry[$arry.length-1] is 5.
$arry.GetType() # --> True True Object[] System.Array
Associative arrays (hash tables)
$assoc = @{one=1 ; two=2} # Associative array (curly brackets, semicolons as separators)
$assoc.one # -> 1
$assoc['two'] # -> 2
$assoc['three'] = 3 # Adds a member
$assoc.four = 4 # Adds a member
$assoc.GetType() # --> True True Hashtable System.Object
$assoc #
The last statement ($assoc) gives:
Name Value
---- -----
four 4
one 1
three 3
two 2
Type cast a hash table as a custom object:
$obj = [PSCustomObject]@{1 = 'one'; 2 = 'two'}
$obj.1 # --> one (accesses member of object with dot)
$obj | fl *
Last statement gives:
1 : one
2 : two
Strings are as in PHP. 'Singly' quoted strings: no expansion of variables or escape character (backtick). "Doubly" quoted: expansion of variables. Furthermore, expressions under $ are evaluated. For example, "$(3*5)" gives 15, while "3*5" gives 3*5. Backtick escapes under double quotes "`$(3*5)" gives $(3*5). Backticks are unchanged under single quotes: '`$(3*5)' gives '`$(3*5)'. Note: "`n" gives the newline character. The string "John Doe" can be appended to file simply by "John Doe" >> out.txt. Note, however, that the file will be in UTF-16. The cmdlet add-content (alias ac) writes to file by default in ANSI (Windows-1252), and allows specification of other encodings.
Here-strings: \n@'\n ... \n'@\n (no expansion) and \n@"\n ... \n"@\n (with expansion). The newline symbol \n is not entered by the user, but indicates that @' and @" must start in column 1 and be on a single line. The same holds for '@ and "@.
Example, assume $a -eq "Big Brother":
@'
$a
$(3*5)
'@
gives
$a
$(3*5)
while
@"
$a
$(3*5)
"@
gives
Big Brother
15
Comparison
Comparison operators are among others: -eq, -ne, -gt, -ge, -lt, -le, -like, -notlike, -match, -notmatch, and -cmatch. Although the operator -replace does not perform a comparison, it is usually included in this group.Examples:
'peanutbutter' -like 'nut' # false
'peanutbutter' -like '*nut*' # true (* is wildcard)
'peanutbutter' -notlike '*nut*' # false
'peanutbutter' -notlike 'nut' # true
'peanutbutter' -match '[a-z]+' # true (regexp: all letters)
'peanutbutter' -match 'r$' # true (regexp: last letter is r)
'peanutbutter' -match '[A-Z]+' # true (PS is case insensitive)
'peanutbutter' -cmatch '[A-Z]+' # false (cmatch matches cases)
'peanutbutter' -replace 'u', 'U' # 'peanUtbUtter'
Rename
The cmdlet rename-item (aliases: ren and rni) renames files, directories, and registry keys. In contrast to the cmd command rename, it does not allow wildcard in the name of the files. Although
ren report.txt report.doc
is correct in cmd-mode as well as in PowerShell, the command that includes the wildcard *
ren *.txt *.doc # Error in PS!
only works in cmd-mode. PowerShell returns an error.
To explain how to rename more than one file in PS by a single command, we first observe that the cmdlet rename-item can take piped input for the original (old) name and takes as the new name the name defined by the flag -newname, for example,
ls report.txt | ren -newname report.doc
gives the required change of the file extension.
To change multiple names the -replace operator may be used. Its syntax is:
string -replace regexp, new_name
In string every substring that matches the regular expression regexp is replaced by new_name. For example,
'report.txt' -replace '\.txt$', '.doc' # -> 'report.doc'
The regular expression '\.txt$' is anchored at the end of the string by "$" and the dot is escaped so that its meaning is not the regexp arbitrary character but the ordinary punctuation mark. Thus,
ls *.txt | ren -new { $_.name -replace '\.txt$','.doc' }
replaces in the current directory all file extensions txt to doc. The value of the script block is a string: the new file name.
Switch
The following switch statement is case sensitive because of the flag -casesensitive:
function f ($str) {
Switch -casesensitive ($str) {
'aap' { write-host 'AAP' }
'noot' { write-host 'NOOT' }
'mies' { write-host 'MIES' }
'wim' { write-host 'WIM' }
Default { "Unable to determine value of $str" }
}
"Statement after switch"
}
f('noot') # --> NOOT \n Statement after switch
f('Noot') # Unable to determine value of Noot \n Statement after switch
Builtin classes
PowerShell has built-in classes, one is [console] with methods (among others) beep and write: see the msdn (microsoft developer network) site.
[console]::beep(800, 1000) # beep at 800 Hz for 1000 msec
[console]::write([char]0x07) # Write hex 07, that is, ring the bell (does not work under ISE)
[console]::readkey() # Return name of key + modifier(not under ISE)
Another built-in class is [math]. See msdn.Examples:
[math]::pi # 3.14159265358979
[math]::cos([math]::pi) # -1
[math]::max(-1, -4) # -1
[math]::pow(10,3) # 1000
Random numbers
Get-Random -min 0.0 -max 1.0 # Random nr between 0.0 and 1.0, see help Get-Random for bounds
Alternatively, use the System.Random object:
$rand = New-Object Random
$rand | gm # Gives methods of $rand, among which NextBytes
The creation of a byte array by type casting is equivalent to the creation of a System.Byte object (a byte array of length 4 plus methods):
[byte[]]$out = @(0,0,0,0) <--> $out = New-Object Byte[] 4
Fill the array by a method of instance $rand:
$rand.NextBytes($out) # Fill array $out with 4 integer random numbers n: 0 -le n -le 255
$out # To console
Errors
Almost all cmdlets recognize the flag -ErrorAction, abbreviated: -ea. The parameters of this flag (Continue, etc) may be replaced by numbers, as follows:
# -ErrorAction Continue | Ignore | Inquire | SilentlyContinue | Stop
# -ea 2 | 4 | 3 | 0 | 1
For instance, suppress error message about inaccessible subdirectories as follows:
ls -rec -ea 0 *.jpg # all .jpg files in present and all subdirectories
As in many languages errors may be trapped. Enter
Get-Help about_trap to see how. The very same info as web page is here:
About trap.
Example of trapping:
Trap [System.Exception] {
"Command error trapped.`n$_" # Automatic variable '$_' contains system error msg; `n gives newline.
continue # Suppress traceback, continue after erroneous statement
}
nonsenseString # Erroneous statement: unknown cmdlet, function or script.
'Execution continues'
PS also has a Try ... Catch construct:
try {
An error # Illegal statement
}
catch {
"An error occurred"
}
The global object $error is a stack containing the consecutive non-trapped errors. To list the latest and the first error, respectively:
$error[0] | fl # The latest
$error[$error.count-1] | fl # The first
The formatting of strings
The PS formatting of strings is derived from the composite formatting of C#. The format operator is -f. Schematically it is used like:
"String containing format-items" -f elements to be formatted
Examples:
"{0, 0:f4} is rounded to 4 decimals" -f 12.34567 # -> 12.3457 is rounded to 4 decimals
"12345 converted to hex is: {0 :x}" -f 12345 # -> 12345 converted to hex is: 3039
"Prices are {0, 0:c} and {1, 4:c0}" -f 12.3998, 1.99 # -> Prices are $ 12.40 and $ 2
On the left-hand-side of the operator -f there is a string containing format-items:
{index[,alignment]:[formatString]}
[Square brackets surround optional values]. The index is 0-based and refers to the position in the array on the right-hand-side of -f. The number of digits before the decimal point is adapted by the system so as not to lose information. The number of decimals (digits after the decimal point) is by default 2.A composite-formatted string can be written by Write-Host:
$str = "One decimal:{1,5:n1}; two decimals:{0, 7:n2}; three decimals:{2, 10:n3}"
Write-Host($str -f 2.141, 1.141, 3.141)
Note the order: second argument first, then the first, and finally the third. Also look at the spacings dictated by the alignment parameter:
One decimal: 1.1; two decimals: 2.14; three decimals: 3.141
||||| ||||||| ||||||||||
The following is an (incomplete) list of format strings, optionally they may be appended by an integer giving the number of decimals:
- :c
- Currency (symbol depends on the region set in Windows Control Panel:
$, €, ...)
- :d
- Decimal. Only for integers (no decimals)
- :e
- Scientific (exp) notation
- :f
- Fixed point,
n:fd gives n gives field of length n and d digits after the decimal point. If n is too small the system adapts.
- :g
- Most compact generic format, fixed or scientific
- :n
- Number, includes decimal point and thousands separators (actual symbols depend on the region set in Windows Control Panel))
- :p
- Percentage
- :x
- Hexadecimal format (only integers)
To get the sizes of all PS-scripts in the current directory (gp = Get-ItemProperty):
gp *.ps1 |% length <--> gp *.ps1 |% {$_.length}
The second form allows for computation (1kb is a literal constant of value 1024):
gp *.ps1 |% {$_.length/1kb} # Sizes in kilobyte
Prettify the format (round brackets are needed to give priority to the division):
gp *.ps1 |% {"{0,10:f2}" -f ($_.length/1kb)}
Functions
A PS function is written in the PowerShell script language and is not compiled but interpreted. Often functions are written by end-users. In contrast, a cmdlet is written in a .net programming language such as C# ("C sharp") and is an intrinsic part of PS. A function name, just like a cmdlet name, is preferably of the form "verb-noun" where "verb" is any of the existing verbs.To get the unique verbs of all (including user) functions sorted in alphabetical order:
gcm -commandtype function |select verb -unique |sort verb|ft
Example of a user function:
function Write-ToScreen($path, $name) {
Write-Host $path, $name
}
Alternatively, the parameters can be defined by the param statement:
function Write-ToScreen {
param($path, $name)
Write-Host $path, $name
}
Both forms can be called as (parameters can be abbreviated to unique strings):
Write-ToScreen -path roaming -name debug.txt # --> roaming \n debug.txt
Or more briefly:
Write-ToScreen roaming debug.txt # Quotes are not required
Or more classically:
Write-ToScreen('roaming', 'debug.txt') # Quotes are required
With regard to return values: (most) console output generated in the body of the function is collected into an array which is returned. After completion of the function call, the return array may be written to the console (the default), or it may be assigned to a variable, or redirected to a file, or piped to a cmdlet. Indeed, the following three kinds of console output are collected in a return array:
Write-Output.- A simple string reference.
- The end of a pipeline (including a pipeline of one segment)..
Example:
function list-no{
write-output "first"
"second"
"third" |fl
}
$a = list-no # Nothing to the console; output collected in return array $a
$a # --> first \nsecond \nthird (vertically stacked)
Not all console output is collected: the cmdlets Write-Host and Out-Host -i write only to the console (do not generate return values):
function list-yes{
Write-Host "first"
Out-Host -i "second"
}
$a = list-yes # --> first \nsecond (vertically stacked) to console
$a # No output
Because the return array may be redirected to a file and not all console output generated during function execution ends up in this array, the return values require close inspection. Example:
function Write-Vars {
$a = 'A'; $b = 'B'; $c = 'C'; $d = 'D'; $e = 'E';
Write-Output $a # To return array (including EOL chars)
$e | fl # To return array
Write-Host $b # To console
$c # To return array
Out-Host -i $d # To console
}
$f = Write-Vars # 'B', 'D' to console; 'A', 'E', 'C' to $f
$f # 'A', 'E', 'C' to console
Write-Vars # 'A', 'E', 'B', 'C', 'D' to console (in order of assignment).
Write-Vars > foo.out # 'B', 'D' to console; 'A', 'E', 'C' to foo.out
One could expect that the statement Write-Vars would write first the immediate values of $b and $d followed by the values of the return array, but this is not the case.More examples:
function list-txt{ls *.txt}
$a = list-txt # No console output, output of ls returned.
$a # Info of .txt files to console
list-txt | ft name # Only file names to console
function list-txt{ls *.txt|write-host}
$a = list-txt # Long file names of .txt files to console, nothing to $a.
$a # No output, no returned parameters.
Function parameters can have a default value:
function f {
param($c = "Pete")
$c
}
f # -> Pete
f John # -> John
Positional parameters are passed in the automatic array $args:
function Get-Pos {
foreach ($p in $args) {
Write-Host $p
}
}
Get-Pos 1, 2, 'pink elephant', icecream # --> 1 2 pink elephant icecream
Functions may handle piped input (property names must be known—as always in pipelines). The named members of an object or hash table piped into the function are handled in a Process block:
Function Test-PipedValue {
Process {
Write-Host "name: " $_.name,
"color: " $_.color
}
}
Example, create hash table and pipe into function:
$hash = @{name = 'Jean'; color = 'White'}
$hash | Test-PipedValue # --> name: Jean color: White
The process command loops over elements of the piped object:
function Test-Loop{
process {
Write $_ # alias of write-output, appends EOL char
}
}
1, 2, 3, 4 | Test-Loop # --> 1\n 2\n 3\n \4
See help about_functions for more info.
Scripts
A script is a collection of PowerShell commands contained in a file with extension .ps1. The script is invoked from a PS session by entering its file name (= script name) prefixed by its path. If the script has parameters (defined in a param statement) their values follow the script name, optionally prefixed by the parameter names, just as is the case in a function invocation.
The output of scripts is comparable to that of functions. That is, the command Write-Host writes immediately (and only) to the console, while Write-Output writes to a return array. After termination of the script it is decided what happens to the return array: redirected to a file or to the console. Create the script Measure-Text.ps1 containing the following 8 lines:
# Begin Measure-Text.ps1
Param ([string]$filename) # Script with one parameter, a string.
Write-Output "`nStatistics of $filename `:" # To return array
cat $filename | measure -line -word -character|ft # To return array, counts of lines, words, and chars
Write-Host "You will hear a beep after 2 sec:" # To console
sleep -sec 2
Write-Host 'Beep'; [console]::beep(800,1000); # To console
# End Measure-Text.ps1
Compare what is written on the console when the output is redirected (the script measures its own length):
.\Measure-Txt.ps1 -filename .\Measure-Txt.ps1 > foo.out
cat foo.out
to when the script is called directly (parameter name -filename is optional and omitted):
.\Measure-Txt.ps1 .\Measure-Txt.ps1
Variables and functions have a default scope which may be modified. For example, inside a script the following function has only the script as scope. The scope of the variable $a is modified to global and hence $a is known to the invoking PS session:
function Display-Hello {
"Hello, World"
$global:a = 13
}
Display-Hello
$a
Traversing the Windows Registry
PowerShell is eminently suitable for traversing the Windows Registry. The Registry stores information needed by the programs installed in a Windows environment. It contains the following "hives";
- hkey_classes_root (hkcr)
- hkey_current_user (hkcu)
- hkey_local_machine (hklm)
- hkey_users (hku)
- hkey_current_config (hkcc)
Each hive is a tree consisting of keys and subkeys that define traversable paths. Unless a subkey is the end of a path, it contains one or more subkeys that point further down their paths. A subkey may also contain value entries, which are name-value pairs that offer the desired information to installed programs. The value entries are the very reason for the existence of the Registry. In fact, the tree structure is only a means to help locate the value entries.The only Registry hives predefined as PSDrives are HKCU and HKLM. The hives HKCR, HKU, and HKCC are not directly accessible by cd. One must issue cd registry::hkcr to access HKCR:, etc. The latter change of directory leads to the very long prompt:
PS Microsoft.PowerShell.Core\Registry::HKCR>
Alternatively, one can define a new PSdrive by a command like:
New-PSDrive -PSProvider registry -Root HKEY_CLASSES_ROOT -Name HKCR
followed by cd HKCR:. The advantage is the much shorter prompt string: PS HKCR:\>.A Registry key that does not contain value entries is called empty. An empty key always contains one or more subkeys. An end node of a path is never empty, it always contains value entries, but by definition no subkeys. Clearly, value entries are not part of a path.For use in the following examples, we set once and for all:
set ps 'PSChildName' -opt constant
so that from hereon $ps -eq 'PSChildName'. In the examples below the current PSdrive is HKCU\software. One gets there in a PowerShell session by issuing
cd hkcu:\software
Recall that -ea 4 stands for -ErrorAction Ignore. This flag suppresses errors about non-accessible keys of which there are many in the Registry. The alias gp stands for Get-ItemProperty. The alias gi stands for Get-Item. The functionality of gi overlaps to a large extent with ls and gp.
Now follows a list of examples that may be useful in inspecting/traversing the Registry:
ls -rec -depth 1 -name # Tabulate names of subkeys (children) and subsubkeys (grandchildren).
gp * # Lists all value entries (name and value) in all subkeys plus a few PS variables that define
# three generations of the current path. Skips empty subkeys.
ls 7-zip | gp # Value entries (names and values) of the subkeys of 7-zip (plus a few PS variables).
gp . # Lists value entries in present key. No output if present key is empty.
gp * |ft $ps # $ps='PSChildname' is a PS variable, returned by gp, that contains the name of subkey (child).
# Hence this tabulates names of all non-empty subkeys.
gp microsoft # No output because no value entry present in subkey 'microsoft' (is empty).
gp RegisteredApplications # Value entries (names and values) of hkcu:\software\RegisteredApplications + PS info
gi * # Same as ls *; lists names of subkeys (also empty ones) and their value entries;
# no output when present key is endnode.
gi . # Value entries of present key. Almost same info as 'gp .', but somewhat different format.
gi .\Microsoft\Notepad # Value entries of subkey
gi .\microsoft\Notepad |fl * # A subkey is an object, list its property names and values. One member is array 'Property'
gi .\microsoft\Notepad |select -exp property # The content of array 'Property' in expanded form,
# the array elements contain the names of value entries of the present key.
Note on ls * −rec −depth 1
Consider the following two commands issued from
HKCU:\software:
ls * -rec -depth 1 -ea 4 | measure -line # gives 35329 lines
ls -rec -depth 1 -ea 4 | measure -line # gives 804 lines
while both commands—issued from
c:\—give the very same number of lines (542). It is difficult to see this dependence on context as anything but a bug. It is, therefore, advisable to never use
ls * together with the flags
-rec -depth.
ls -rec -depth 1 |select name, property
Here property contains the names of all value entries, but only the first few elements are listed. To expand this array, together with the names of the subkeys separated by an empty line, use the following:
ls -rec -depth 1 |select name, property |% {$_.name; $_.property; "" }
Explanation: ls returns an array of subkey objects that all have the properties name and property. The cmdlet select picks from each subkey object these two properties and adds them to an object that is referred to by $_ in the next stage of the pipeline. These objects are collected in an array that is passed to % = Foreach-Object. Then % loops over the array elements. The script block in the body of the loop simply issues the two member names as commands. Issuing of a variable name gives the writing of the content of the variable. If the content is an array, the array is written element for element, every element on a new line.
Registry lookup
If a value entry or a subkey must be located, it is necessary to descend down hive trees. The cmdlet Set-Location (alias cd) enables this. The -recurse parameter of ls does not imply any cd in a script block. An explicit cd is necessary if some processing must be performed lower down the path. For example, recalling that ls -name -rec -de 1 returns an array containing names of subkeys and subsubkeys, we see that the following statement gives the names of all subkeys and subsubkeys by execution of pwd (which returns the name of the present key), including those without value entries (the empty ones):
ls -name -rec -depth 1 |% {$p=pwd; cd $_ -ea 4; pwd; cd $p; rv p}
Here -ea 4 suppresses the listing of an error when a cd to a non-accessible subkey is attempted. The newly created variable $p is removed to avoid possible later side effects. Compare this statement to the following command that lists names (contained in PSPath) of only non-empty subkeys and subsubkeys, but does not require a cd:
ls -name -rec -depth 1 |gp |select pspath
Once one has descended to a certain key, the names of its value entries (if any) are obtained by:
gi . |select -exp property # This returns line by line the names of the value entries.
The command gpv -name entry_name returns the value coupled to entry_name. For instance, the subkey 7-zip of HKCU\software contains the value entry pair (lang: nl), i.e., it has entry name lang and entry value nl. The commands issued from HKCU\software:
$p=pwd; cd 7-zip; gpv -name lang; cd $p; rv p;
effectively leave us in HKCU\software and outputs the entry value nl named lang.To list the value entries (if present) of the present key, use
gi . |select -exp property |% {$v=gpv -name $_; write-host $_":", $v; rv v;}
The next command lists names ($p) of non-empty subkeys, subsubkeys, and subsubsubkeys, name of value entry ($name) and corresponding value ($v). It does not list the value entries of the current key. Note the nesting of |% and the line continuation:
ls -rec -name -de 2 |% {$cd=pwd; $p=$_; cd $p -ea 4; gi . |select -exp property|`
% {$name=$_; $v=gpv -name $name; write-host $p": ", $name" = "$v; rv name, v }; cd $cd; rv cd, p}
The final command finds entry values containing a given string in keys below the current key. It is important to note that the search time increases exponentially with the value of the parameter -depth:
$string = "aul"
ls -rec -name -depth 2 |% {$cd=pwd; $p=$_; cd $p -ea 4; gi . |select -exp property|`
% {$name=$_; $v=gpv -name $name; if ($v -match $string) {write-host $p": ", $name" = "$v;}; rv name, v }; cd $cd; rv cd, p}
rv string
´
