Soliciting New Verbs

Soliciting New Verbs

  • Comments 19

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:

  • Little or no overlap with existing approved verbs
  • Broadly applicable to multiple technologies - must be domain agnostic
  • Used consistently with similar meaning across multiple contexts
  • Pairing with an opposite is good, but not required

When suggesting a new verb, it's most helpful if you can include the following information in your suggestion:

  • Verb name
  • Description
  • Category
  • List of at least 5 significantly different applicable domains
  • List of at least 3 alternative verbs from the approved list
  • Pair with (optional)

For example, we recently approved Open and Close as new verbs in v2. Our internal discussions boiled down to the following:

  • Verb name: Open
  • Description: To set a resource to its opened state or make it accessible, visible, or available
  • Category: Common
  • List of at least 5 significantly different applicable domains: file, port, dialog, door, archive, container, account, mailbox, queue, chamber, scriptblock
  • List of at least 3 alternative verbs from the approved list: Set, Use, Enable, Show
  • Pair with: Close

Here is our current list of approved verbs:

Verb Category
------ -------------
Add Common
Clear Common
Close Common
Copy Common
Enter Common
Exit Common
Format Common
Get Common
Hide Common
Join Common
Lock Common
Move Common
New Common
Open Common
Pop Common
Push Common
Redo Common
Remove Common
Rename Common
Reset Common
Search Common
Select Common
Set Common
Show Common
Split Common
Switch Common
Undo Common
Unlock Common
Backup Data
Checkpoint Data
Compare Data
Compress Data
Convert Data
ConvertFrom    Data
ConvertTo Data
Dismount Data
Edit Data
Expand Data
Export Data
Import Data
Initialize Data
Limit Data
Merge Data
Mount Data
Out Data
Publish Data
Restore Data
Save Data
Unpublish Data
Update Data
Complete Lifecyle
Disable Lifecycle
Enable Lifecycle
Install Lifecycle
Invoke Lifecycle
Register Lifecycle
Restart Lifecycle
Resume Lifecycle
Start Lifecycle
Stop Lifecycle
Suspend Lifecycle
Uninstall Lifecycle
Unregister Lifecycle
Wait Lifecycle
Debug Diagnostic
Measure Diagnostic
Ping Diagnostic
Repair Diagnostic
Resolve Diagnostic
Test Diagnostic
Trace Diagnostic
Connect Communications
Disconnect Communications
Read Communications
Receive Communications
Send Communications
Write Communications
Block Security
Grant Security
Revoke Security
Unblock Security
Use Other

Thanks,
Dan Harman
Program Manager
Windows PowerShell

Leave a Comment
  • Please add 4 and 8 and type the answer here:
  • Post
  • 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

  • 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.

Page 1 of 2 (19 items) 12