Tag Archives: Get-Verb

Adding a Help Parameter to a Function

Edit: There’s a quick addition at the bottom of this post. I tried something else, it worked, and so I decided to include it.

I started writing a PowerShell function to replicate the work of an old executable called ICSWEEP. ICSWEEP “is a command-line utility to clear the Temporary Internet Files Cache and/or the TEMP files folder of ALL user profiles that are NOT in use when this command is executed.” ICSWEEP Information. I may or may not walk through the process of writing this function here; it’s to be determined. What I do want to discuss for sure, however, is the last switch in the above image. It’s /?.

We cannot add ? parameter to a function. Below is an image of the message when we attempt to do that in VS Code.

That’s right, right!? You do remember the $? variable. It stores the execution status of the last command as True or False. Instead of ? as a parameter, I used the value of Help. Therefore, someone can invoke my function and use -Help to get help with the function. But could they?

I sat there, wondering, can you create a parameter of a function so that it’ll return its own, comment-based help? It turns out you can. Here’s the early stage of this function. It consists of the comment-based help, a few parameters, and a small amount of code.

function Clear-UserTemporaryFile {
<#
.SYNOPSIS
    The Clear-UserTemporaryFile command ...
.DESCRIPTION
.PARAMETER <Parameter>
.EXAMPLE
.NOTES
    Name: Clear-UserTemporaryFile
    Author: Tommy Maynard
    Comments: --
    Last Edit: 12/13/2022 [1.0.0]
    Version: 1.0.0
#>
    Param (
        [Parameter()]
        [switch]$ALL,
        [Parameter()]
        [string]$TIF,
        [Parameter()]
        [string]$TMP,
        [Parameter()]
        [string]$SIZE,
        [Parameter()]
        [switch]$HELP
        
    )

    if ($HELP) {
       Get-Help -Name "$($MyInvocation.MyCommand.Name)"
       Exit
    }
}

In the above code, I added a simple if statement. It monitors whether or not the Help parameter is used when the function is invoked. If it is, it runs the Get-Help cmdlet against the name of the executing function—itself—using the $MyInvocation variable and then exits the function.

Clear-UserTemporaryFile -Help
NAME
    Clear-UserTemporaryFile

SYNOPSIS
    The Clear-UserTemporaryFile command ...

SYNTAX
    Clear-UserTemporaryFile [-ALL] [[-TIF] <String>] [[-TMP] <String>] [[-SIZE] <String>] [-HELP] [<CommonParameters>]

DESCRIPTION

RELATED LINKS

REMARKS
    To see the examples, type: "Get-Help Clear-UserTemporaryFile -Examples"
    For more information, type: "Get-Help Clear-UserTemporaryFile -Detailed"
    For technical information, type: "Get-Help Clear-UserTemporaryFile -Full"

At this point, some of you may already know where I’m going to go next. There was something else I had forgotten about every cmdlet and function written. They all have something in common. And what’s that? There is a way to return a command’s help using, of all things, the question mark! Take a look using the built-in Get-Verb and Get-Command cmdlets below.

Get-Verb -?
NAME
    Get-Verb

SYNTAX
    Get-Verb [[-Verb] <string[]>] [[-Group] {Common | Communications | Data | Diagnostic | Lifecycle | Other |
    Security}] [<CommonParameters>]

ALIASES
    None

REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only partial help.
        -- To download and install Help files for the module that includes this cmdlet, use Update-Help.
        -- To view the Help topic for this cmdlet online, type: "Get-Help Get-Verb -Online" or
           go to https://go.microsoft.com/fwlink/?LinkID=2097026.
Get-Command -?
NAME
    Get-Command

SYNTAX
    Get-Command [[-ArgumentList] <Object[]>] [-Verb <string[]>] [-Noun <string[]>] [-Module <string[]>]
    [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <int>] [-Syntax] [-ShowCommandInfo] [-All]
    [-ListImported] [-ParameterName <string[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]

    Get-Command [[-Name] <string[]>] [[-ArgumentList] <Object[]>] [-Module <string[]>] [-FullyQualifiedModule
    <ModuleSpecification[]>] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Script
    | Configuration | All}] [-TotalCount <int>] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported] [-ParameterName
    <string[]>] [-ParameterType <PSTypeName[]>] [-UseFuzzyMatching] [-UseAbbreviationExpansion] [<CommonParameters>]

ALIASES
    gcm

REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only partial help.
        -- To download and install Help files for the module that includes this cmdlet, use Update-Help.
        -- To view the Help topic for this cmdlet online, type: "Get-Help Get-Command -Online" or
           go to https://go.microsoft.com/fwlink/?LinkID=2096579.

This means I don’t even need a Help parameter. PowerShell already has this covered, and here’s the proof.

Clear-UserTemporaryFile -?
NAME
    Clear-UserTemporaryFile

SYNOPSIS
    The Clear-UserTemporaryFile command ...

SYNTAX
    Clear-UserTemporaryFile [-ALL] [[-TIF] <String>] [[-TMP] <String>] [[-SIZE] <String>] [-HELP] [<CommonParameters>]

DESCRIPTION

RELATED LINKS

REMARKS
    To see the examples, type: "Get-Help Clear-UserTemporaryFile -Examples"
    For more information, type: "Get-Help Clear-UserTemporaryFile -Detailed"
    For technical information, type: "Get-Help Clear-UserTemporaryFile -Full"

Edit: We know that we were able to use this PowerShell to return the help for our function,

Get-Help -Name "$($MyInvocation.MyCommand.Name)"

but we could’ve just as easily done this:

Invoke-Expression -Command "$($MyInvocation.MyCommand.Name) -?"

The first option invokes the Get-Help cmdlet against our function. The second option invokes the same function that’s already being invoked, adding a -? to the end of the complete command.

PowerShell Approved Verb Synonyms

One of the best design decisions, when PowerShell was initially being created, was using approved verbs in naming a command. When people use those, we can guarantee some consistency between command names. As commands — both cmdlets and functions — we expect to see an approved verb followed by a dash and then a singular noun or nouns. Sometimes there’s a prefix after the dash, but before the noun(s). Here are a few examples of some random commands: Import-Module, Get-VMGroup, Add-AzVhd, Export-AzDataLakeStoreItem, Set-WsusProduct, and Stop-SSMCommand. While these commands display a few of the approved verbs, it’s not all of them. Use the Get-Verb command to view the full list of the approved verbs, from which you should choose when writing a new function or cmdlet.

There may not have always been this many, but in 7.2.0-preview4, there are 100 approved verbs.

[PS7.2.0-preview.4][C:\] Get-Verb | Measure-Object

Count             : 100
Average           :
Sum               :
Maximum           :
Minimum           :
StandardDeviation :
Property          :

Even though there’s a good number of options from which to choose, there may not always feel like there’s one for your newest command. While I’ve brought this up to the community at least a couple of times before, it’s time to do it again. It’s the Get-TMVerbSynonym function. I authored it in June 2016, I updated it in 2017, and I used it earlier today, in 2021. It can be found in the Powershell Gallery and installed using the below command:

[PS7.2.0-preview.4][C:\] Install-Script -Name Get-TMVerbSynonym

The file it downloads is a function inside of a script file — a .ps1 file. In order to add a function inside a script file to the current PowerShell session, you need to dot source the file. That’s what the mystery dot is doing between my prompt and the path to the .ps1 file below.

[PS7.2.0-preview.4][C:\] . C:\Users\tommymaynard\Documents\PowerShell\Scripts\Get-TMVerbSynonym.ps1

Once it’s dot sourced, you can use the function. In closing, here are few examples of the function in action. Each of these commands uses the Format-Table -AutoSize command and parameter in order that the results are easier to read.

[PS7.1.3][C:\] Get-TMVerbSynonym -Verb change | Format-Table -AutoSize

Verb   Synonym     Group  Approved Notes
----   -------     -----  -------- -----
Change Alter                 False
Change Commute               False
Change Convert     Data       True
Change Deepen                False
Change Dress                 False Generic Term
Change Exchange              False
Change Get Dressed           False Generic Term
Change Go                    False Generic Term
Change Interchange           False
Change Locomote              False Generic Term
Change Modify                False
Change Move        Common     True Generic Term
Change Replace               False Generic Term
Change Shift                 False
Change Stay                  False Antonym
Change Switch      Common     True
Change Transfer              False
Change Transfer              False Generic Term
Change Travel                False Generic Term
Change Vary                  False

[PS7.1.3][C:\] Get-TMVerbSynonym -Verb change -Approved | Format-Table -AutoSize

Verb   Synonym Group  Approved Notes
----   ------- -----  -------- -----
Change Convert Data       True
Change Move    Common     True Generic Term
Change Switch  Common     True

[PS7.1.3][C:\] 

If there’s ever a verb you want to use, but it’s not approved, then try this function. You’ll likely be able to choose something that’s close enough, and is approved.

Get the Verbs

So, earlier tonight, my wife, daughter, and I were on the couch. My wife was cleaning out her purse as my daughter helped her organize her change. Me, I was briefly on my phone and looking for a quick list of approved PowerShell verbs. As you likely know, if we create our own cmdlets and functions, we should use an approved verb for the verb, dash, singular noun naming convention: Get-Process, Set-ADUser, Checkpoint-Computer… okay, it’s not always a verb, but you know what I mean.

I couldn’t believe it; I couldn’t just find a simple list of all the verbs, close to one another, and without any explanations. You know the list, the one you basically get when you run Get-Verb. I suppose I should mention that all I had was my phone. There wasn’t a computer close by, and that’s, why I’m putting up a list of the approved verbs (as of PowerShell 5.1 on Windows 8.1), on my website.

Here’s the standard, Get-Verb output that includes the Name and Group. After that, I’ll include the same list, a few more ways. Maybe, just maybe it’ll be here when you, or I, need it next.

PS > Get-Verb

Verb        Group
----        -----
Add         Common
Clear       Common
Close       Common
Copy        Common
Enter       Common
Exit        Common
Find        Common
Format      Common
Get         Common
Hide        Common
Join        Common
Lock        Common
Move        Common
New         Common
Open        Common
Optimize    Common
Pop         Common
Push        Common
Redo        Common
Remove      Common
Rename      Common
Reset       Common
Resize      Common
Search      Common
Select      Common
Set         Common
Show        Common
Skip        Common
Split       Common
Step        Common
Switch      Common
Undo        Common
Unlock      Common
Watch       Common
Backup      Data
Checkpoint  Data
Compare     Data
Compress    Data
Convert     Data
ConvertFrom Data
ConvertTo   Data
Dismount    Data
Edit        Data
Expand      Data
Export      Data
Group       Data
Import      Data
Initialize  Data
Limit       Data
Merge       Data
Mount       Data
Out         Data
Publish     Data
Restore     Data
Save        Data
Sync        Data
Unpublish   Data
Update      Data
Approve     Lifecycle
Assert      Lifecycle
Complete    Lifecycle
Confirm     Lifecycle
Deny        Lifecycle
Disable     Lifecycle
Enable      Lifecycle
Install     Lifecycle
Invoke      Lifecycle
Register    Lifecycle
Request     Lifecycle
Restart     Lifecycle
Resume      Lifecycle
Start       Lifecycle
Stop        Lifecycle
Submit      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
Protect     Security
Revoke      Security
Unblock     Security
Unprotect   Security
Use         Other

As you may have noticed in the previous results, the default output is sorted by the Group. Here comes a second list; however, this list will be sorted by the Verb. I can already see how this may be helpful. In fact, this is the list I was probably after.

PS > Get-Verb | Sort-Object -Property Verb

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

In this example, all I want to return is the verbs. Nine times out of 10, the group doesn’t make a difference to me.

PS > (Get-Verb | Sort-Object -Property Verb).Verb

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

This next example uses Format-Wide so that my results are in columns. Notice how the sorting goes across the rows, as opposed to down the columns. There’s should probably be a built-in way to handle that behavior. Yuck.

PS > Get-Verb | Sort-Object -Property Verb | Format-Wide -Column 4

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

In the next example, I’ll try the -join operator.

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

Also yuck. So yeah, I thought that might turn out better. Well, I’ve got it now — a place to find all the current verbs as of this writing, if I’m ever sitting on the couch, watching two of my favorite people, and unable to decide what verb to use for a new PowerShell tool.

Get-TMVerbSynonym 1.4

Notes: Download link at the bottom of this post.

One of my favorite PowerShell community members, June Blender, posted a question on Twitter. While it wasn’t directed at me, I couldn’t resist. She wanted the approved verb options for the verbs “populate”, “fill in”, or “load”. I couldn’t help myself, because I wrote a function for this very task!

The Get-TMVerbSynonym function’s purpose is to find synonyms for verbs and return whether they’re approved, or not. Well, her Tweet was all it took to finally make some overdue changes, including getting it posted on the PowerShell Gallery. As I called it in one of my follow-up tweets, when June asked where it was then published, I said it was a “TechNet leftover.”

Well, not anymore.

It’s since been updated to version 1.4 and placed on the PowerShell Gallery. The above image was what I posted when it was in version 1.3. This means that it doesn’t reflect two of the newest, view-able changes. The Verb property now indicates the verb it’s checking, and the old Verb property has been renamed to Synonym. This was included to support some other potential updates for an even newer version. Anyway, this means it’s up to five properties, so pipe to Format-Table -AutoSize in order that the results can be easily read.

Additionally, it now includes something I always wanted it to have: an Approved, switch parameter. This means there’s no piping to Where-Object to filter the function to only show the approved synonyms. Here’s an example of the function in action, both with and without the Approved, switch parameter.

Download it now manually, or use Install-Script -Name Get-TMVerbSynonym.

Script Sharing – Get Synonyms for Approved and Unapproved Verbs

Download link at bottom of post. Note: This post contains information that is necessary to know to use this function. Please read it if you think you’ll try using this function.

Update: The previous version of the function (1.0) required the user to register and obtain an API key, and place it inside the function’s code. I’ve only had some 40 downloads, so I’ve opted to include my API key to see if this function can get more usage. This really can be a great tool, and so it seems the best idea for now. If anyone ever hits an error using the API key, please let me know: <my1stname>@<thisdomain>.com. (6/10/2016)

I consider myself a best practice kind of guy; especially when it comes to Windows PowerShell. There’s been a time or two where I’m quite sure that I, politely, called someone out for using an unapproved verb. If you’re familiar with PowerShell, then you know that cmdlet and function names should use the verb-noun naming convention. Now, no one cares about the nouns you choose, but verbs need to be approved.

If you haven’t before, try running the Get-Verb cmdlet. This cmdlet, when used without any parameters, will return all the approved verbs. Even for me, there’s been a time or two when the verb I wanted to use wasn’t approved. In that case, I recommend still finding and using an approved verb, but also creating an alias that you can use to call your properly named, cmdlet or function. Here’s a modified example from one of my previous posts:

Set-Alias -Name Launch-InternetExplorer -Value Open-InternetExplorer
 
Function Open-InternetExplorer {
    # Do Stuff.
}

In this example, that was originally posted here: http://tommymaynard.com/quick-learn-create-a-function-to-open-internet-explorer-like-in-run-2015, I can use Launch as my verb, since I’ve made it part of an alias. The function name with the approved verb is Open-InternetExplorer and my alias, that will run this same function, is Launch-InternetExplorer.

So, where am I going with this: I’ve always wanted a function that would allow me to pull back synonyms for a verb, and today, I have just that. I considered walking though what I did to write this, but instead, because it ended up being somewhat lengthy, I posted it on TechNet for download.

Before I provide a download link, I should mentioned that you’re going to need to do a couple things to make this function work for you.

  1. Go to http://thesaurus.altervista.org/mykey and register for an API key.
  2. Download my function from the link at the bottom of the page.
  3. Open the function in the ISE, or your editor of preference, and replace [string]$Key with [string]$Key ='<Your API Key>’, replacing <Your API Key> with key you received from step 1.

Now when you use the function, it’ll use your API key. In addition, we won’t have to make the -Key parameter mandatory, forcing it to prompt us for the key, even when the $Key variable is being assigned a value inside the function. Thanks!

get-synonyms-for-approved-and-unapproved-verbs01

Update: The newest version is now available for download on the PowerShell Gallery.

Download the Get-TMVerbSynonym advanced function here: https://gallery.technet.microsoft.com/Get-Synonyms-for-Approved-f6625752

Twitter Reply – Rebel Doesn’t Mean Rebel to Everyone

Twitter Reply to: no link

I saw a recent Twitter #PowerShell post and while I wanted to respond to it on Twitter, I didn’t. I was opposed to what it said, but I didn’t feel it was my place to call anyone out in that fashion. That’s why there isn’t a link above, where they might’ve been otherwise.

The twitter post in which I’m referring indicated that a person was a “rebel” by not using an approved PowerShell verb. I saw the included :P, and that’s fine, but only if the author is joking about the whole thing — I didn’t get that they were.

To use an unapproved verb, especially while knowing you shouldn’t, is everything that PowerShell is trying to stay away from. Part of the success of PowerShell has been the consistency in which it’s been developed by Microsoft, and others. While you might consider yourself a rebel, I consider what you’re doing, a problem.

I will admit, there has been a time or two that I’ve struggled with the best option for my verb, but I’ve always found one. Here’s my recommendation if you are not satisfied with the list of approved verbs: Use an alias; don’t be a “rebel.”

Let’s say I have a function I want to invoke using the name Smack-Yourself, and it looks like this:

Function Smack-Yourself {
    Write-Output -Verbose "I've been smacked!"
}

I can tell you without looking; smack is not an approved verb. We’ll check if it exists anyway.

PS C:\> Get-Verb -Verb Smack
PS C:\>

Nope, this verb hasn’t (yet?) been approved by Microsoft.

Instead of using an unapproved verb, let’s give our function an approved verb and then make an alias we can use instead. There’s no best practice for aliases; name them whatever you want. As far as your function name, please stay consistent and follow the verb dash noun naming convention, using an approved verb.

Set-Alias -Name Smack-Yourself -Value Pop-Yourself

Function Pop-Yourself {
    Write-Output -Verbose "I've been smacked!"
}

In the example above, we’ve used Set-Alias to modify (or create) an alias, called Smack-Yourself. When run, this alias will ultimately execute the Pop-Yourself function, where Pop is an approved verb. Even if the approved verb you choose doesn’t perfectly align with the verb you wanted to use, you can use whatever you want, if you’re using an alias.