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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | 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.
1 | Clear-UserTemporaryFile -Help |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | 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.
1 | Get-Verb -? |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | 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. |
1 | Get-Command -? |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | 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.
1 | Clear-UserTemporaryFile -? |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | 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,
1 | Get-Help -Name "$($MyInvocation.MyCommand.Name)" |
but we could’ve just as easily done this:
1 | 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.