Advanced Windows PowerShell Scripting Video Training

Advanced Windows PowerShell Scripting Video Training
Advanced Windows PowerShell Scripting Video Training

Wednesday, January 31, 2018

What are Positional Parameters?

Often while teaching PowerShell, we get into a discussion about how someone, usually me, types this:

Get-Help Get-Date

Instead of

Get-Help –Name Get-Date

PowerShell parameters utilize positioning.  Good authors of cmdlets will determine which parameter will be the most frequently used and put that parameter in the first position.  That means if the user types a cmdlet, they can immediately provide the data for that parameter without calling the parameter name.  Take a look at the –Name parameter of Get-Help
-Name
    Gets help about the specified command or concept. Enter the name of a cmdlet, function, provider,
    script, or workflow, such as `Get-Member`, a conceptual topic name, such as `about_Objects`, or an
    alias, such as `ls`. Wildcard characters are permitted in cmdlet and provider names, but you
    cannot use wildcard characters to find the names of function help and script help topics.
   
    To get help for a script that is not located in a path that is listed in the Path environment
    variable, type the path and file name of the script.
   
    If you enter the exact name of a help topic, Get-Help displays the topic contents. If you enter a
    word or word pattern that appears in several help topic titles, Get-Help displays a list of the
    matching titles. If you enter a word that does not match any help topic titles, Get-Help displays
    a list of topics that include that word in their contents.
   
    The names of conceptual topics, such as `about_Objects`, must be entered in English, even in
    non-English versions of Windows PowerShell.
   
    Required?                    false
    Position?                    0
    Default value                None
    Accept pipeline input?       True (ByPropertyName)
    Accept wildcard characters?  false

Two things to take note of.  First of all, the type of data that this parameter accepts is [String].  The second is the value of Position which is zero.  That means if the user types the cmdlet Get-Help and then a value of the type string, that value will be the argument for the –Name parameter. 

I often stress the need for full command syntax in scripts so everyone knows what parameters you are using but I am also guilty of using positional parameters for my more common cmdlets like Get-Help and Where-Object.  Here is some code to help you see the parameter in the first position and what type of data it expects.  Just be forwarded, it will load all of your modules into memory.
$Commands = Get-Command

ForEach ($CMD in $Commands) {
    $Obj = [PSCustomObject]@{
        'Cmdlet' = $CMD.Name
        'PositionOne' = (($CMD | Get-Help).parameters.parameter | where position -eq 0).Name
        'Type' = (($CMD | Get-Help).parameters.parameter| where position -eq 0).Type.Name
        }

    Write-OutPut $Obj
}


No comments: