Monad breaking change announcement: Approved verb names enforcement.


In order to prevent a mass usability nightmare with developers picking their own improvised cmdlet verbs, the Monad team, based on customer feedback, decided to enforce the use approved verbs.


 


The idea is to provide a more uniform and consistent interface to the end user. If a user needs to get something, he or she should know that what they are looking for is a get-something cmdlet. The user can then use the command discovery cmdlet (get-command get-*) to look for a getters and so forth…


With this change, if a non standard verb is to be used, the developer will be forced to add “__” to the beginning of the cmdlet name in order to make their cmdlet usable:


Example: in order to create a “play-nice” cmdlet where “play” is not an approved verb the developer will need to prepend the verb name with two underscore characters as follows “__play”.


Users can still get around this issue by simply aliasing the underscored cmdlet name as follows:


 


Set-Alias Play-Nice __Play-Nice


 


In order to ensure we have a complete list of valid verbs, we need to get your feedback on the list below to ensure we did not miss anything. Please speak now or forever hold your peace J


 


 



























































































































































































































































































































































































































Ubiquitous Verbs


Definition


Common Parameters


Obsoletes


Pair


Add


Add, append or attach an element


At, After, Before, Create,  Filter, ID, Name, Value, Whatif


append, attach, concatenate, insert


Remove


Clear


Remove all the elements or content of a container


 


flush, erase, release, unmark, unset, nullify


 


Copy


Copy a resource to another name or another container


Acl, Overwrite, Recurse, Strict, Whatif


duplicate, clone, replicate


 


Get


/object /content /children


All, As, Compatible, Continuous, Count, Encoding, Exclude, Filter,  Include, ID, Interval, Name, Path, Property, Recurse, Scope, Sortby,


read, open, cat, type, dir, obtain, dump, acquire, examine, find, search


Set


Lock


To protect from changes or deletion


 


secure, fasten


Unlock


Move


Move a resource


 


transfer, name, migrate


 


New


create a new resource


Description, ID, Name, Value


create, generate, build, make, allocate


Remove


Remove


Remove a resource from a container


(Get), Drain, Erase, Force, Whatif


delete, disconnect, detach, drop, purge, flush, erase, release


Add/New


Rename


Give a resource a new name


 


 


 


Set


/object /content /children


Passthru,


write, reset, assign, configure


Get


Join


to unite so as to form one unit


 


combine, unite, link, 1connect, relate, associate


split


Split


To become separated into parts, especially to undergo lengthwise division. Divided into portions, parts, or fragments


 


Divide, separate, fragment, disunite


join


Unlock


To undo the Lock operation. To give access to; open


 


unsecure, unfasten


Lock


Data Verbs


Definition


 


Obsoletes


Pair


Backup


 


 


 


Restore


Compare


Compare this resource with another one and produce a set of differences


 


Diff


 


Convert


Change from one encoding to another or from one unit base to another (e.g. feet to meters)


 


 


 


Export


Make a copy of a set of resources using an interchange format


(get), Add, As, AsScript, Delete, Description, FileName, Location, Strict, Whatif


extract, backup


Import


Import


Create a set of resources using an interchange format


FileName, Location


bulk load, load


Export


Initialize


Prepare a resource for use. Assign a beginning value to something


 


erase, renew, rebuild, reinitialize, setup


 


Limit


Limit the consumption of a resource or apply a constraint on a resource


 


quota


 


Merge


Take multiple instances and create a single instance


 


coalesce


 


Restore


Rollback state to a predefined snapshot/checkpoint


 


 


Checkpoint


Update


update or refresh a resource from a source of truth


 


refresh, renew, recalculate, reindex


 


Mount


Attach a named entity to a hierarchy at the pathname location. To set in position


 


fix, organize, prepare


Dismount


Dismount


To get off. To detach.


 


detach, take-down


Mount


out


direct to a port. Output something to a port.


 


output.


 


 


 


 


 


 


Lifecycle Verbs


Definition


 


Obsoletes


Pair


Disable


Stop and/or configure something to be unavailable (e.g unable to not start again)


 


 


Enable


Enable


Configure to be available (e.g. able to start)


 


 


Disable


Install


Settle in an indicated place or condition (optionally initializing for use)


 


setup, load


Uninstall


Restart


Terminate existing activity and begin it again (with the same or checkpointed configuration)


 


recycle


 


Resume


Begin an activity again after it was suspended


 


 


Suspend


Start


Begin an activity


 


launch, initiate, boot


Stop


Stop


Discontinue or cease an activity


 


End, kill, terminate, cancel


Start


Suspend


Suspend an activity temporarily


 


Pause


Resume


Uninstall


 


 


 


Install


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


 


Diagnostics verb


Definition


 


Obsoletes


Pair


Debug


Interactively interact with a resource or activity for the purpose finding a flaw or better understanding of what is occurring.


 


 


 


Measure


calculate/identify resources consumed by a specified operation or retrieve statistics about a resource


 


 


 


Ping


Determine whether a resource is alive and responding to requests


 


 


 


Resolve


Map a shorthand name will be bound to a longname


 


where, which


 


Test


Verify the operational validity or consistency of a resource


 


diagnose, verify, analyze, salvage, verify


 


Trace


Trace activities performed by a specified operation


 


 


 


 


 


 


 


 


Communications


Definition


 


Obsoletes


Pair


Send


Convey by an intermediary to a destination


 


put, broadcast, mail, fax,


receive


Receive


Take or acquire from a source


 


read, accept, peek,


send


Connect


Associate subsequent activities with a resource


 


 


disconnect


Disconnect


 


 


 


Connect


write


communicate or express. Display data.


 


display, communicate


read


read


To obtain (data) from a storage medium, such as a magnetic disk.


 


input


write


 


 


 


 


 


 


 


 


 


 


Security


Definition


 


Obsoletes


Pair


Grant


 


 


 


Revoke


Revoke


 


 


 


Grant


Block


prevent access to or usage of


 


 


unblock


Unblock


allow access to or usage of


 


 


block


 


 


 


 


 


Other Verbs


Definition


 


Obsoletes


Pair


Use


 


 


 


 


 


Wassim


Comments (30)

  1. Anonymous says:

    Why are out, write, read lowercase and the rest mixed-case?

  2. MSDN Archive says:

    Thank you pointing that out. No special reason. The mixed-case issue has been updated.

    Thanks

    Wassim [MSFT]

  3. Will those verbs make it to "VerbCommon"(http://windowssdk.msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref13/html/T_System_Management_Automation_VerbsCommon.asp) class in Msh API?

    If those verbs make it to "VerbsCommon" class, we wouldn’t have to worry much about case-sensitivity for cmdlets containing common verbs.

  4. I am sorry for double posting.

    But i had to point out a typo in "Communications" section.

    If you go to "pair" column, you will see "receve" on "Send" row.

  5. Sean McLeod says:

    Hmm, what about verbs for domains you haven’t thought of?

    For example I’m creating some image processing cmdlets, e.g.

    resize-image, rotate-image etc.

  6. Sean McLeod says:

    On the image verb examples I mean’t to finish off with:

    So these will end up having to be:

    __resize-image, __rotate-image and will look "funny" unless users alias them.

  7. Christopher Morgan says:

    A comment on parameter naming rather than verbs:

    *Please* refrain from using ‘PassThru’ when ‘PassThrough’ is the correct term.  I am sure I am not the only reluctant user of ‘International English’ who will object!  It would be a breach of Microsoft’s own coding guidelines to use ‘inappropriate abbreviations/contractions for entity naming’

    Keep up the good work.  When do you expect to have a beta refresh that is standardised?

    "Now I’ve spoken, let’s keep the peace"

  8. MSDN Archive says:

    I was actually surprised to find Thru in the dictionary when this first came up as I was arguing for PassThrough as well.  Unfortunately I lost that argument when Thru was found in the dictionary.  http://dictionary.reference.com/search?q=thru

    Jeff Jones [MSFT]

    Monad Development

    Microsoft Corporation

    This posting is provided "AS IS" with no warranties, and confers no rights.

  9. Denis says:

    I like the rules but are you worried that cmdlets will use the verbs but not keep the proper semantics? In other words, proper verbs will be used but the intended meaning will not be right? Is this better/worse? Probably better as I see it but wondering if this was thought about.

    To use Sean’s example, I’m afraid someone might be too tempted to creat a Convert-Image rather than rotate-image.

  10. Ruben says:

    So it’s Start-Music rather than Play-Music? And Limit-Image rather than Crop-Image? And Use-Image rather than View-Image or Display-Image (Write- or Get-Image would not be right). And Transform-* doesn’t feel ike Convert-*. Neither does Flush-* feel like Clear-*. To me Flush-Buffer would be something completely different from Clear-Buffer. And what about Eject-Disc? Or Print-Report (you know, to a printer); or are we returning to Write-Report > LPT1: and teletype machines?

    I don’t know. I think the guidelines are great. But to enforce them in such an intrusive manner, hmmmm… I think you’re actualy *forcing* unnatural and therefore inconsistent verbs on people this way. Language is a fickle thing; don’t think you can just call Limit-Language and be done with it.

  11. lordabdul says:

    What happens to "format-table" and other formatting CmdLets? Do they now use the "write" verbs?

    About the non-approved verbs problem, couldn’t there be a way to add "approved" verbs, just the same way you can add trusted providers and scripts? If the user/admin doesn’t want the new verb to be approved, the CmdLets are used with the "__".

  12. Keith Hill says:

    I think lordabdul has an intersting idea.  What if MSH itself stuck on the leading "__".  That way I could write my cmdlets with a normal cmdlet name like resize-image.  Then by default in MSH you would have to type __resize-image to use the cmdlet unless the user specifically said the cmdlet (or snapin) is approved.  Then the user could just type resize-image.

  13. lordabdul says:

    Thanks Keith.

    I’m wondering if the enforcement of "__" and approved verbs is going to change anything anyway, especially if new CmdLets come with an installer that adds aliases to the common "profile.msh" script, in order to use the new commands without the "__". This may need an admin approval… or not, since the installer is already launched with admin rights. So, from the user’s point of view, this may not change anything… doesn’t it?

  14. John Vottero says:

    I agree with Ruben, this is going to make things worse, not better.  Suppose I want to see what the IP route table looks like, is that write-route?  I would expect write to take something and write it somewhere.  In that context, write does not replace display.  I agree that you need a list of approved verbs and I may even agree with some sort of enforcement but, you need to add LOTS more verbs to the approved list.

    It might be easier to come up with a list of unapproved verbs.

  15. IM says:

    Hi,

    Can I suggest putting a link to the monad download page in your sidebar?

  16. Monad では、コマンドレットの名前は [動詞]-[名詞] とするルールがあります。get-command や format-table といったように、動詞と、目的語となる名詞の組み合わせになっています。コマンドレットは簡単に追加することができ、やはりこのルールは守りましょうということになっていますが、さらに「動詞は、承認済みのものだけを使う」というルールが追加されることになりました。…

  17. I am wondering how "Initialize" in "Data Verbs" section can obsolet "erase" when the definition is to "prepare a resource for use"

    while "erase" is to be obsolete by "clear" verb in "Ubiquitous verbs" section.

    And yeah, another typo in obsoletes column of "join" in ubiquitous verbs; "1connect"

  18. Mark Ayers says:

    This is a truly bad idea!  The proper verb committee can never get it right for everyone, for ever.  Set standards but allow others to decide when to break those standards.

  19. Ben says:

    Bad idea. To illustrate:

    There’s a verb for "out" but not for "in" or any opposite for "out".

    You’re never going to get a complete list or even a list that will cover most eventualities; just thinking of general domains music, sound, video, graphics, HW access, user interaction, GUI’s, etc. you’re missing a load.

    To that you can add industry-specific domains like banking, insurance, manufacturing, etc., etc.

    I know Monad is predominantly aimed at SysAdmins but once it’s there, users *will* use it to write functional scripts for whatever domains they’re in.

    There’s a reason why natural language is so rich…

    Anyway, have fun 🙂

  20. MSDN Archive says:

    Hi,

    Based on your feedback, the Monad development team decided not to go ahead with the approved verb enforcement change. Thank you all for your participation and for voicing your concerns.

    Wassim [MSFT]

  21. Andrey Skvortsov says:

    Entirely agree with Mark.You can provide "standard" list of available verbs but must be a way to reduce/extend it.

    Thanks.

  22. Kurt says:

    Why not noun-verb instead of verb-noun.

    Organizing methods with the data they operate on is arguably one of the core principles in OO programming.  I wouldn’t even dare to count the number of methods in the .NET framework libraries (perhaps you could write a script) but could you imagine having MSDN library sorted by method then class?

    When I look for a function my first idea is to search for the concept, the verbs are often much more ambiguous then the concept for example if I want to search a csv file for specific all records containing XYZ I would want to look for commands that work with csv files, if forced to choose a verb I might try something such as "search" a csv file, "read" a csv file, "find" records in csv file, looking at the standard verbs might lead me to try "get" records from a csv.  And why is it export-csv but to write html output you have convert-html and is export-csv really anymore descriptive then write-csv.  

    The emphisis on verbs has also created the issue where the noun part no longer describes what is being manipulated but rather what is being created such as convert-html to what? or format-wide whats a wide? so searching for concepts like csv becomes a guessing game and and scanning lots of help.  I would much rather have longer unique verb/verb sentances then consistant verbs with unique but arbitrary nouns.  

    Aside from this issue, I’m very excited about MSH and think you’ve done an awsome job 🙂

    – Kurt

  23. Kurt says:

    Why not noun-verb instead of verb-noun.

    Organizing methods with the data they operate on is arguably one of the core principles in OO programming.  I wouldn’t even dare to count the number of methods in the .NET framework libraries (perhaps you could write a script) but could you imagine having MSDN library sorted by method then class?

    When I look for a function my first idea is to search for the concept, the verbs are often much more ambiguous then the concept for example if I want to search a csv file for specific all records containing XYZ I would want to look for commands that work with csv files, if forced to choose a verb I might try something such as "search" a csv file, "read" a csv file, "find" records in csv file, looking at the standard verbs might lead me to try "get" records from a csv.  And why is it export-csv but to write html output you have convert-html and is export-csv really anymore descriptive then write-csv.  

    The emphisis on verbs has also created the issue where the noun part no longer describes what is being manipulated but rather what is being created such as convert-html to what? or format-wide whats a wide? so searching for concepts like csv becomes a guessing game and and scanning lots of help.  I would much rather have longer unique verb/verb sentances then consistant verbs with unique but arbitrary nouns.  

    Aside from this issue, I’m very excited about MSH and think you’ve done an awsome job 🙂

    – Kurt

  24. applepwc says:

    hi,Kurt:

    If you really love noun-verb.You can use this in your profile :

    foreach( $command in $(get-command -type cmdlet)) { set-alias "$($comman

    d.noun)-$($command.verb)" $command }

  25. Jonny says:

    As a VMS sysadmin for years I came to just the opposite conclusion – years before object programming became available.  This is best demonstrated by the Queue commands.  You had to learn that queues could be Initialized, Set, Started, Stopped, Deleted, etc by looking in completely separate places of the help documentation.  You had to sift through all sorts of useless info (process, device, etc) that the verb also applied to to glean out the parts you actually needed.  If you didn’t know the command to use (such as initialize vs. create) you had to hunt all over to get anything done (so much so, that a separate ‘queue’ entry was later created in the help files – one of very few non-command entries).  At the time I realized the architects of DCL had got it wrong, even if it was, initially, more inutitive – at least when tranlated into english.  

    However, do this for long and you realize that the first thing you think of is the noun, not the verb (i.e. I need a process or queue) – then you think of when and where to operate on that noun (lets create it here…) – so for the frequent user (the admin) – noun-verb is actually more intuitive thought process.

    – jon

    – jon

  26. > However, do this for long and you realize that the first thing you think of is the noun, not the verb (i.e. I need a process or queue) – then you think of when and where to operate on that noun (lets create it here…) – so for the frequent user (the admin) – noun-verb is actually more intuitive thought process.

    There is room for reasonable people to disagree on this topic.  While VMS DCL was awesome, it had problems as well.  The discoverability issue that you highlight is one of them.  We address discoverablility in a couple of ways.  One is wildcarding. The following command would tell you everything you could do with QUEUEs:

    ps> Get-Help *QUEUE*

    When you get detailed help for any of the QUEUE commands, we include a RELATED LINKS section  which will provide pointers to the other QUEUE commands an any related documentation.

    At this point, you could say that those techniques would help you with a NOUN-VERB approach as well and you’d be right – as I said, reasonable positions can be made for either approach.  In choosing, I gave heavy weight to the issue that making VERBs first put the USER EXPERIENCE as the high-order bit and the DOMAIN SPECIFICS as the low-order bit.  I felt that this was an important message to feature and product teams.  It is only natural for people to think about their users using their feature and to optimize for that vs thinking about the users entire experience and optimizing for that.  For any particular domain, you’d like it the other way around but when you have to deal with lots of domains, the standardization is a BIG benefit.

    BTW – the other problem with VMS was that a technical issue they had (around naming registration) lead to people (over time) doing NOUN-VERB in addition to VERB-NOUN.  Thus the benefits of a hardcore VERB-NOUN model where diminished.

    Jeffrey Snover