Compartilhar via

Monad breaking change announcement: Approved verb names enforcement.

  • Artigo

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

  • Anonymous
    February 16, 2006
    Why are out, write, read lowercase and the rest mixed-case?

  • Anonymous
    February 16, 2006
    Thank you pointing that out. No special reason. The mixed-case issue has been updated.

    Thanks
    Wassim [MSFT]

  • Anonymous
    February 16, 2006
    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.

  • Anonymous
    February 16, 2006
    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.

  • Anonymous
    February 16, 2006
    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.

  • Anonymous
    February 16, 2006
    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.

  • Anonymous
    February 17, 2006
    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"

  • Anonymous
    February 17, 2006
    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.

  • Anonymous
    February 17, 2006
    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.

  • Anonymous
    February 17, 2006
    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.

  • Anonymous
    February 17, 2006
    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 "__".

  • Anonymous
    February 17, 2006
    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.

  • Anonymous
    February 18, 2006
    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?

  • Anonymous
    February 18, 2006
    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.

  • Anonymous
    February 19, 2006
    Hi,
    Can I suggest putting a link to the monad download page in your sidebar?

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

  • Anonymous
    February 20, 2006
    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"

  • Anonymous
    February 20, 2006
    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.

  • Anonymous
    February 22, 2006
    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 :-)

  • Anonymous
    February 27, 2006
    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]

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

    Thanks.

  • Anonymous
    April 11, 2006
    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

  • Anonymous
    April 11, 2006
    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

  • Anonymous
    April 12, 2006
    PingBack from http://blogs.msdn.com/monad/archive/2006/04/12/575056.aspx

  • Anonymous
    April 12, 2006
    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 }

  • Anonymous
    April 25, 2006
    PingBack from http://blogs.msdn.com/powershell/archive/2006/04/25/583267.aspx

  • Anonymous
    April 29, 2006
    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

  • Anonymous
    April 29, 2006
    The comment has been removed

  • Anonymous
    June 05, 2008
    PingBack from http://green.onnix.co.cc/?p=54

  • Anonymous
    June 01, 2009
    PingBack from http://uniformstores.info/story.php?id=19057