What I Understand about PowerShell Approved Verbs

1-PowerShell-Tips.md

PowerShell Tips

Write-Host vs Write-Output

Write-Host writes directly to the console; Write-Output writes to the pipeline, which often ends up to the console but not necessarily.

For example: Write-Host "The Cake is a lie" | Out-Null won't work as expected, Write-Output "The Cake is a lie" | Out-Null will.

False Friends

The following verbs don't exist in the Approved verbs list:

• Retrieve: Use Get instead;
• Locate: Use Find or Search instead;
• Build (I really miss this one): Use New, Initialize or Publish instead;
• Configure: Use Initialize instead;
• Put: Use Set, Add, Move, Register or Install instead;
• Load: Use Import instead;
• Setup: Use Install or Initialize instead.

Reserved Verbs

Format, ForEach, Where, Group, Sort and Tee are reserved verbs. These are used by the PowerShell language, or by special case commandlets.

2-Differences-Between-PowerShell-Approved-Verbs.md

Differences Between PowerShell Approved Verbs

Get vs. Find vs. Search

Get-* retrieves a precise something (i.e. an object, a resource, a value... Anything that can be represented by a POCO in PowerShell and .NET) from a given container of things. It takes a relatively short time.

Find-* tries to retrieve something from a given container of things. It takes a relatively long time.

Search-* tries to retrieve a reference of something from a given container of things. It takes a relatively long time.

Select

Select-* extracts or transforms from its input to produce some differently structured output. Think of it like the Linq's Select clause.

Depending on the parameters it's been given, Select-Object can act as a filter like Where-Object, through Where-Object is much lower level.

Get vs. Read vs. Receive

Get-* retrieves data from an resource (e.g. a file, an object, an environment variable).

Read-* retrieves data from the console or the pipeline. The notion of stream isn't very far.

Receive-* retrieves data asynchronously (e.g. from the network).

Set vs. Write vs. Send

Set-* amends the data of a resource (e.g. a file, an object, an environment variable).

Write-* produces and displays data on the console or the pipeline. Writing data is a final outcome.

Send-* issues data asynchronously (e.g. over the network). Sending data is only a first step, this data will be acted upon later, likely by another process.

Write vs. Out

Write-* produces some output.

Out-* redirects the output of a pipeline. Think of it like Bash's redirections (e.g. > /dev/null, >> /var/log/cake.log).

New vs. Add

New-* makes up a brand new something, likely empty or in a default state.

Add-* appends data to an existing something.

Add vs. Register

Add-* appends data to a something.

Register-* creates a record about something in a container (e.g. a database).

Initialize vs. Install

Initialize-* performs the first configuration of something.

Install-* sets something up when it wasn't there before. Install is higher level than Initialize: it can be seen as { New | Move | Copy } + [ Initialize ].

New vs. Install

New-* makes up a brand new something, likely in a default state.

Install-* puts an existing something in the right place. It may also configure it by the way. Install is higher level than New: it can be seen as { New | Move | Copy } + [ Initialize ].

Test vs. Assert vs. Confirm vs. Approve

Test-* checks the existence, availability, and basic correctness (i.e. coherence, shape, structure, syntax) of something.

Confirm-* :: rethorical question or answer to an external request?

Assert-* Doesn't seem to be used anywhere. The only examples on the MSDN return 404s...

Approve-* is not used neither...

3-PowerShell-Approved-Verbs-Defininitions.md

PowerShell Approved Verbs Defininitions

Add

Approved Verbs Listing: Adds a resource to a container, or attaches an item to another item. For example, the Add-Content cmdlet adds content to a file. Avoid using Append, Attach, Concatenate, or Insert instead.

VerbsCommon.Add: Synonyms: Add to, append or attach.

Approve

Approved Verbs Listing: Confirms or agrees to the status of a resource or process.

VerbsLifecycle.Approve: Agree to the status of a resource or process.

Assert

Approved Verbs Listing: Affirms the state of a resource. Avoid using Certify instead.

VerbsLifecycle.Assert: State or affirm the state of an object.

Confirm

Approved Verbs Listing: Acknowledges, verifies, or validates the state of a resource or process. Avoid using Acknowledge, Agree, Certify, Validate, or Verify instead.

VerbsLifecycle.Confirm: Acknowledge, verify, or validate the state of a resource.

Find

Approved Verbs Listing: Used to look for an object. Looks for an object in a container that is unknown, implied, optional, or specified.

VerbsCommon.Find: Search for an object.

Get

Approved Verbs Listing: Used to retrieve a resource, such as a file. Specifies an action that retrieves a resource. Avoid using Read, Open, Cat, Type, Dir, Obtain, Dump, Acquire, Examine, Find, or Search instead.

VerbsCommon.Get: Get the contents / object / children / properties / relations / ... of a resource.

Initialize

Approved Verbs Listing: Prepares a resource for use, and sets it to a default state. Avoid using Erase, Init, Renew, Rebuild, Reinitialize, or Setup instead.

VerbsData.Initialize: Prepare a resource for use. Assign a beginning value to something.

Install

Approved Verbs Listing: Places a resource in a location, and optionally initializes it. Avoid using Setup instead.

VerbsLifecycle.Install: Settle in an indicated place or condition (optionally initializing for use).

New

Approved Verbs Listing: Used to create a new resource. Creates a resource. (The Set verb can also be used when creating a resource that includes data, such as the Set-Variable cmdlet.) Avoid using Create, Generate, Build, Make, or Allocate instead.

VerbsCommon.New: Create a new resource.

Out

Approved Verbs Listing: Sends data out of the environment. For example, the Out-Printer commandlet sends data to a printer.

VerbsData.Out: Out - direct to a port. Output something to a port.

Read

Approved Verbs Listing: Used to get information from a source, such as a file. Acquires information from a source. Avoid using Acquire, Prompt, or Get instead.

VerbsCommunications.Read: To read - to obtain (data) from a storage medium or port.

Receive

Approved Verbs Listing: Accepts information sent from a source. This verb is paired with Send. Avoid using Read, Accept, or Peek instead.

VerbsCommunications.Receive: Take or acquire from a source.

Register

Approved Verbs Listing: Creates an entry for a resource in a repository such as a database.

VerbsLifecycle.Register: Record details about an item in a public store or publishing location.

Search

Approved Verbs Listing: Used to create a reference to a resource in a container. Creates a reference to a resource in a container. Avoid using Find or Locate instead.

VerbsCommon.Search: Get a reference to a resource or summary information about a resource by looking in a specified collection. Does not actually retrieve that resource.

Select

Approved Verbs Listing: Locates a resource in a container. For example, the Select-String commandlet finds text in strings and files. Avoid using Find or Locate instead.

VerbsCommon.Select: To take as a choice from among several; pick out.

Send

Approved Verbs Listing: Delivers information to a destination. This verb is paired with Receive. Avoid using Put, Broadcast, Mail, or Fax instead.

VerbsCommunications.Send: Convey by an intermediary to a destination.

Set

Approved Verbs Listing: Used to modify an existing resource, optionally creating the resource if it does not exist, such as the Set-Variable cmdlet. Replaces data on an existing resource or creates a resource that contains some data. For example, the Set-Date cmdlet changes the system time on the local computer. (The New verb can also be used to create a resource.) Avoid using Write, Reset, Assign, or Configure instead.

VerbsCommon.Set: Set the contents / object / properties / relations / ... of a resource.

Test

Approved Verbs Listing: Verifies the operation or consistency of a resource. Avoid using Diagnose, Analyze, Salvage, or Verify instead.

VerbsDiagnostic.Test: Verify the operational validity or consistency of a resource.

Write

Approved Verbs Listing: Adds information to a target. Avoid using Put or Print instead.

VerbsCommunications.Write: To write - communicate or express. Display data.