Powershell: Guidance on common verb implemenations?

[richardszalay]

Is there any guidance on the behaviour of various verbs? I was surprised that I couldn't find anything, as I would have that that behavioural consistency across verbs would be useful for users of PowerShell.

As an example, here are two questions that I'd love answered for my pshosts module:

• Should Get cmdlets always return an error when the item is not found and a wildcard pattern was not provided? (pshosts currently emits an error)
• Is it acceptable for a Set cmdlets to create the item if it does not already exist? If not, would it be acceptable behind a -Force flag? (pshosts raises an error if the item does not exist, and Force has no effect on this behaviour)

[iSazonov]

Main document is Approved Verbs for Windows PowerShell Commands.
It seems it don't answer on your questions. If so we should update it by results the discussion.

My understanding is that cmdlet behavior should be based on underline API behavior and our common expectations. Usually we expect that "Get" return an existing object, "New" creates an object and "Set" only changes existing object.

[richardszalay]

Good point RE Get. I guess I should add a Test verb to check for existence.

The Set issue is a little more nuanced. In my scenario, Set-HostEntry something.local -Loopback feels like it should just set the local hosts entry even if that means adding one. The AWS SDK (which, granted, doesn't always provide the best example of PS conventions) tends to match this behaviour in things like Set-DefaultAWSRegion and Set-AWSCrentials.

[iSazonov]

In another areas SET can create an entity. In cmd.exe SET can create new environment variable. In PowerShell we can expect that Set-EnvironmentVariable will be create new environment variable too. Best practice is - New-EnvironmentVariable.

[SteveL-MSFT]

If existing documentation is lacking, please open issues at http://github.com/powershell/powershell-docs. Thanks!

[iSazonov]

@SteveL-MSFT @sdwheeler Please move the issue to docs repo (you have rights for this operation).

[sdwheeler]

I don't see any issue here. The docs exist.

[richardszalay]

@SteveL-MSFT FWIW the docs were just a basic list when this issue was created. Even now, only the Set query above is actually included in those docs but I'll leave it to your team as to whether you think the Get behaviour is worth defining.

[SteveL-MSFT]

@richardszalay your feedback is appreciated, if you believe Get needs more content, please open a new issue in the PowerShellDocs repo