Saturday, June 27, 2015

How-To - Name your functions correctly

When you name functions, there is a set standard which you must follow or you'll see this error if you try and put your function into a module and load it:

WARNING: Some imported command names include unapproved verbs which might make them less discoverable. Use the Verbose parameter for more detail or type Get-Verb to see the list of approved verbs.

That format is the basic combination of a Verb and a Noun joined by a dash ("-").  The Noun can be an alphanumeric string, no spaces and a limited scope of special characters (underscore is ok).  The Verb however, has to be on a specific list.  Lets take a look at the valid list:

PS C:\> Get-Verb | Format-Wide -AutoSize

Add          Clear        Close        Copy         Enter        Exit        Find        Format     
Get          Hide         Join         Lock         Move         New         Open        Optimize   
Pop          Push         Redo         Remove       Rename       Reset       Resize      Search     
Select       Set          Show         Skip         Split        Step        Switch      Undo       
Unlock       Watch        Backup       Checkpoint   Compare      Compress    Convert     ConvertFrom
ConvertTo    Dismount     Edit         Expand       Export       Group       Import      Initialize 
Limit        Merge        Mount        Out          Publish      Restore     Save        Sync       
Unpublish    Update       Approve      Assert       Complete     Confirm     Deny        Disable    
Enable       Install      Invoke       Register     Request      Restart     Resume      Start      
Stop         Submit       Suspend      Uninstall    Unregister   Wait        Debug       Measure    
Ping         Repair       Resolve      Test         Trace        Connect     Disconnect  Read       
Receive      Send         Write        Block        Grant        Protect     Revoke      Unblock    
Unprotect    Use

If you run Get-Verb by itself, you'll get a list that runs off the page, but also shows which group the verbs belong to.  For the most part, try to use the verb which mostly relates to the action that you are trying to do.  You can see what other functions do by simply looking at same verb function's help:

PS C:\> Get-Help wait* | Format-Table Name,Synopsis -AutoSize

Name          Synopsis                                                                              
----          --------                                                                              
Wait-Job      Suppresses the command prompt until one or all of the Windows PowerShell background...
Wait-Debugger Stops a script in the debugger before running the next statement in the script.       
Wait-Event    Waits until a particular event is raised before continuing to run.                    
Wait-Process  Waits for the processes to be stopped before accepting more input.                    

To see verbs from all commands that are currently loaded, try this little block.  I've marked it up the code to help explain what each line does.  Try running the first line (leaving off the pipe "|"), then the first and second lines, then the first 3 lines, etc.  You can see how passing the output of one cmdlet into the next works this way.

Get-Command |                      #Gets all commands from all loaded modules 
select -ExpandProperty Name |      #Expands the Name column
Where-Object{$_.contains("-")} |   #Only selects names containing the dash character 
ForEach-Object{$_.split("-")[0]} | #For each of the names, split it up into 2 objects on the dash, select only the 1st
select -Unique |                   #Remove duplicates
sort |                             #sort alphabetically
ConvertFrom-Csv -Header "Name" |   #Converts a string list into an object list
Format-Wide -AutoSize              #Displays the list in a multi-column list

Lastly, if you are planning on releasing a module with a bunch of functions, try naming them in a similar way to indicate they are all from your module.  Most third party modules do this.  The format should be Verb-PrefixNoun.  For example, the NetApp DataONTAP Powershell module uses the prefix "Na", so there commands look like this:

  • Get-NaLun
  • Set-NaVol
  • Restore-NaHostFile

No comments: