Automating the world one-liner at a time…
With the recent changes in v2 to increase the visibility of the cmdlet design guidelines, we want to make sure we have a solid set of verbs on the approved verb list before we ship v2. We've already talked with a number of partners and customers and have made some recent changes to the verb list. In addition, we'd love to have feedback from our community on any holes you perceive we have in our current list of approved verbs.
To provide some context, here are the things we think about when deciding whether to add a new verb:
When suggesting a new verb, it's most helpful if you can include the following information in your suggestion:
For example, we recently approved Open and Close as new verbs in v2. Our internal discussions boiled down to the following:
Here is our current list of approved verbs:
Thanks,Dan HarmanProgram ManagerWindows PowerShell
PingBack from http://www.anith.com/?p=31630
What about the ones that YOU GUYS are already using? E.g.: "ForEach", "Group", "Sort", "Tee", and "Where"
Also, I can't remember, do you suggest Convert* instead of Encode/Decode?
There's a clear asymmetry in that for "New" (which in any case is an adjective, rather than a verb) there is no corresponding "Delete".
* Delete
* Opposite of 'New'
* Common
* For something free-standing (not obviously in an Add/Remove model) that can be created ("New") and managed directly, an explicit way of getting rid of it, including existing items like Alias and Service (at least) also general items like -- document, database, hierarchy
* The least-worst match is "Remove", which is already used in cases where "New" should really have been "Add" e.g. -ItemProperty; all the other end-of-life verbs make far worse complements
* Pair with New
If we weren't starting from this broken state of an officially blessed non-verb verb, then Create/Destroy would have been the obvious pair.
In the security category there is a grant and revoke, but no deny. Deny permissions apply to SQL, NTFS, SharePoint and perhaps other domains. The deny setting is used to override inherited and direct permissions. I'm not sure what block and unblock mean, however Revoke should be used to remove a previously granted or denied permission.
I find the Transform verb useful for data. It is useful for when you are making some changes in data but retaining the same format/schema. The verb Convert doesn't make sense because there is not a schema change.
These are great comments - keep them up.
Some of these are falling into the trap of being so well-versed in a domain that it feels like English.
Dan talked about the template for answers. It's really one of the crucial steps we use in determining the fitness of a new verb. It’s what we go through, and if the data isn’t there it needs to be generated by somebody.
Another point is that some domains are extremely related (i.e.: Active Directory and Exchange,) where a new verb makes sense for both of those. Try to think of "significantly different" in a broader sense -- Photoshop, networking, Outlook, small business, airplanes, etc.
Once you have a proposed verb, you flip it on its head and ask, “would this be the best verb if used outside of that domain?”
By definition, a restricted set of verbs will always imply some loss of detail. For example, the Transform / Convert quandry is only a subtle distinction in the XML world. They will usually feel a bit “forced,” but users appreciate not having to know very subtle technology nuances when transitioning between products. For those situations, a parameter is your best friend.
Lee Holmes [MSFT]
Windows PowerShell Development
Microsoft Corporation
Proposed deny verb in template format:
Verb name = Deny
Description = Deny setting is used to override inherited and direct permissions. To remove a Deny permission use Revoke. Revoke applies to both Grants and Denies.
Category = Security
Domains = SQL Server, NTFS, SharePoint, IIS, AD
Alt verbs = Set, Update, Block
Pair with Revoke
There are a couple of things I'd like to clarify based on the comments above. First, we have are a handful of verbs (ForEach, Group, Sort, Tee, Where) that are only for use by PowerShell. For each of these verbs, there is only one generic "Object" cmdlet that uses them. We only want to have one implementation of these cmdlets. For instance, there's only one ForEach and only one Where. Having multiple implementations of these could cause confusion for users.
With respect to Create/Destroy, these are great in English, but they have geopolitical issues. This is why you never see Create or Destory as actions in Microsoft products. It's always New and Remove or Delete.
Great suggestions - keep them coming!
Dan Harman
Program Manager
Windows PowerShell
I use powershell to monitor traffic on two CAN bus networks - for electric wheel chairs...
Sometimes I want to "Bridge" the two networks together - so that traffic from either is transmitted to the other.
I also hear this term used in Joomla - for "Bridging" one Web based photo album app to another - making sure the content of the two are kept in sync.
I think of it as Actively bridging two things together in a continous fashion.
Maybe it's just me... I could use new-bridge, or maybe start-bridge.
Then again maybe it makes sense to:
$t1 = new-database
$t2 = new-database
$b = bridge-database $t1 $t2 -SyncDeletions
$b.start();
$b.stop();
It seems we have Start/Stop/Restart
What about Connect/Disconnect/Reconnect?
The verb I use all the time is "Check". While in v1 check-* cmdlets were renamed to test-*, these two verbs have an important differenct.
Test implies an action like a synthetic transaction where you provide some input and verify the output. Check, on the other hand, is more passive where you are just peeking in to see how something is doing.
Moving out of the technology arena allows me to provide a great example. If I want to know whether my baby is sleeping or not, I don't "test" the baby, rather I "check" the baby.
The same really applies to things like configuration or services. If I want to know whether or not a service is running, test doesn't fit, but check does (regardless of what the Test-ServiceHealth cmdlet in Exchange is called.) The same goes for verifying that something is configured properly, I really want to just check the current state - not test it.
Verb name: Check
Description: To determine if an entity is in a particular state
Category: Diagnostic
List of at least 5 significantly different applicable domains: Services, file, account, mailbox, queue, configuration, DNS
List of at least 3 alternative verbs from the approved list: Test, Ping, Measure
Pair with: NA
-Chris
In any case it is very good that Microsoft Germany doesn't translate these verbs. The translation of verbose to 'AUSFÜHRLICH' in Write-Verbose output is bad enough (to be precise it is a bug and it happens in PowerShell).
Generally the internationalization of process names and performance counters is was one of the worst decisions Microsoft did.
Please spend the fools who caused this a holiday in Purgatory where they can meet the inventors of a infamous basic version using german keywords.
If you haven't seen the post on PowerShell standard verbs from the PowerShell team it is worth reading
Verb name: Script
Category: Common
Applicable Domains: Windows shares, Active Directory, Databases, IIS, Exchange, Virtual Server
Alternative Verbs: Get, Backup, Export
Pair with: Not Applicable
Description: Used to generate a script to recreate an object that is easy to modify or reuse elsewhere. The script created could be domain specific (i.e. TSQL) or a PowerShell script. This is very useful when you have objects that have properties configured by multiple commands. This is true even if you can get the object from PowerShell and it shows the additional properties. Just because you might be able to see all the properties, it doesn't mean it includes an easy way to generate a similar object.
Here are 3 examples:
--------------
First, a Windows share, in order to recreate it you need a number of properties that were probably created seperately. You have the actual share properties (ShareName, FileSystem Path, caching...), the share permissions (who has access to the share), and finally the NTFS permissions (who has access to the underlying file system). Even if you have one command that had parameters for all of those, you would still want to be able to generate a script to recreate an existing share.
Script-Share -Name "Installs" -ComputerName MyServer -IncludeNTFSPermissions -IncludeSharePermissions
Alternatives for Windows Share:
Get-ShareScript -Name "Installs" -ComputerName MyServer -IncludeNTFSPermissions -IncludeSharePermissions
Backup-Share -Name "Installs" -ComputerName MyServer -IncludeNTFSPermissions -IncludeSharePermissions -ScriptOnly
Export-Share -Name "Installs" -ComputerName MyServer -IncludeNTFSPermissions -IncludeSharePermissions -AsScript
Second, a SQL Server database. You might want to generate a script that includes the definition of tables, views, stored procedures, database creation, users logins... Doing so by seeing the current properties is very dificult to say the least.
Script-SQLDatabase -ServerInstance DBSERVER1 -Database Commerce -IncludeObjects 'Tables','Views','Stored Procedures','Permissions' -IncludeUseDatabase
Alternatives for SQL:
Get-SQLDatabaseScript -ServerInstance DBSERVER1 -Database Commerce -IncludeObjects 'Tables','Views','Stored Procedures','Permissions' -IncludeUseDatabase
Backup-SQLDatabase -ServerInstance DBSERVER1 -Database Commerce -IncludeObjects 'Tables','Views','Stored Procedures','Permissions' -IncludeUseDatabase -ScriptOnly
Export-SQLDatabase -ServerInstance DBSERVER1 -Database Commerce -IncludeObjects 'Tables','Views','Stored Procedures','Permissions' -IncludeUseDatabase -ScriptSchemaOnly
And finally, a Windows Service. There are already 8 cmdlets to work with services including New-Service and Get-Service. If you want a PowerShell script to recreate an existing service none of the existing ones can do it. You would want it to give you a New-Service cmdlet with the correct parameters in order to recreate the service.
Script-Service -Name MyService
Alternatives for Service:
Get-ServiceScript -Name MyService
Backup-Service -Name MyService -ScriptOnly
Export-Service -Name MyService -AsScript
The downside to using alternative verbs is that you need to use additional references in either the Noun or in parameters to make it clear that it will return a script. If you have a cmdlet that only returns a script, it almost requires you to change the Noun in order for it to be understandable. But, if you do that it will no longer be able to get all commands related to that Noun as easily.
Thanks for all the greate work you've done with PowerShell so far.