PowerShell cmdlets

Names

The name of a cmdlet is expected to be verb-subject, where the subject is singular (for example get-process).

This rule is not enforced, however. A list of encouraged verbs can be queried with get-verb.

In order to distinguish between cmdlets with the same name from different cmdlets, the import-module cmdlet has a -prefix parameter that allows to specify a prefix which will then be added before a cmdlet's noun.

A list of verbs and nouns can be found with the get-command and group-object cmdlets:

get-command | group-object verb | sort-object count
get-command | group-object noun | sort-object count

cmdlets can be searched by noun or verb name with the get-command cmdlet:

get-command -verb import
get-command -noun csv

It is also possible to search for cmdlets with wildcards. The following command finds cmdlets like get-help, set-hvciOptions, format-hex, out-host etc:

get-command *t-h*

Parameters and aliases

The parameters and their aliases can be shown via the get-command cmdlet:

(get-command get-command).parameters.values | select-object name,aliases

Getting a quick overview of optional and mandatory parameter variations

With the -syntax switch of get-command, its possible to get a quick summary of the possibilities how a cmdLet can be invoked:

PS Users\Rene> get-command get-process -syntax

Get-Process [[-Name] <string[]>] [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]

Get-Process [[-Name] <string[]>] -IncludeUserName [<CommonParameters>]

Get-Process -Id <int[]> -IncludeUserName [<CommonParameters>]

Get-Process -Id <int[]> [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]

Get-Process -InputObject <Process[]> -IncludeUserName [<CommonParameters>]

Get-Process -InputObject <Process[]> [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]

Common parameters

A few parameters, so-called common parameters, are available for any cmdlet:

	Abbr.	Comment
`-debug`	db
`-errorAction`	ea	Sets the value of the preference variable `$errorActionPreference` in the scope of the cmdlet.
`-errorVariable`	ev	Causes an error message to be stored in the specified variable.
`-informationAction`	infa
`-informationVariable`	iv
`-outVariable`	ov	Objects returned by a command are not only sent down the pipeline but also stored in the specified variable.
`-outBuffer`	ob	Specifies the number of objects that are accumulated before they're sent down the pipeline.
`-pipelineVariable`	pv
`-verbose`	vb	Sets the value of the preference variable `$verbosePreference` to `Continue` which in turn affects the cmdLet `write-verbose`
`-warningAction`	wa
`-warningVariable`	wv

The so-called risk mitigation parameters are:

-whatIf
-confirm

Sometimes, there is also -passThru. This causes a cmdlet to pass on the object it acted on. Usually, this parameter is used on cmdlets with the verbs new, stop, set etc.

The list of common parameters can be displayed in the shell like so:

PS C:\> [System.Management.Automation.Cmdlet]::CommonParameters
…
PS C:\> [System.Management.Automation.Cmdlet]::OptionalCommonParameters
…

In order to turn a function into a cmdlet (or possibly more accurately referred to as advanced function) which then automatically features the common parameter, the function needs a [cmdletBinding[()] param() in its declaration:

function xyz {
   [cmdletBinding()]
    param (
      … 
    )
    …
}

(Predifined) cmdLet classes

Typically, the functionality of cmdLets is stored in a .NET class (type). These classes are found in the Microsoft.PowerShell.Commands namespace.

Common base class

All cmdLets derive from System.Management.Automation.Cmdlet.

A cmdlet can be created by deriving it directly from directly from System.Management.Automation.Cmdlet or, alternatively, from System.Management.Automation.PSCmdlet (which itselfs inherits from CmdLet).

The Cmdlet class provides most common used functionality of a cmdlet, such as

object output
record processing

If a cmdlet requires access to the MSH Runtime, the cmdlet must be derived from the PSCmdlet class

CmdLet inherits from System.Management.Automation.Internal.InternalCommand

TODO

write-host

write-host "Foo bar baz" -foregroundColor red -backgroundColor yellow

# ------------------------------

$ar = 1..5

write-host $ar
# 1 2 3 4 5

write-host $ar -separator ", "
# 1, 2, 3, 4, 5

# ------------------------------

write-host "foo bar" -noNewline
write-host " baz"
# foo bar baz

Github repository about-powershell, path: /cmdlets/write-host.ps1

set-executionPolicy

#
#  Run as administrator
#
set-executionPolicy unrestricted

Github repository about-powershell, path: /cmdlets/set-executionPolicy.ps1

new-object

$obj = new-object -typeName PSObject

$obj | get-member
#
#    TypeName: System.Management.Automation.PSCustomObject
# 
# Name        MemberType Definition
# ----        ---------- ----------
# Equals      Method     bool Equals(System.Object obj)
# GetHashCode Method     int GetHashCode()
# GetType     Method     type GetType()
# ToString    Method     string ToString()

Github repository about-powershell, path: /cmdlets/new-object.ps1

WMI related

cmdlets that are related to WMI are

get-WmiObject
get-CimAssociatedInstance
get-CimClass
get-CimInstance
get-CimSession
set-WmiInstance
set-CimInstanceInvoke-WmiMethod
invoke-CimMethod
new-CimInstance
new-CimSession
new-CimSessionOption
register-CimIndicationEvent
register-WmiEvent
remove-CimInstance
remove-WmiObject
remove-CimSession

test-wsman checks if the WinRM service is running.

Transactions

Some cmdlets can be executed within a transaction (and thus be committed or rolled back).

These cmdlets have the -useTransaction parameter.

A transaction is started with start-transaction, rolled back with undo-transaction and committed with complete-transaction.