One of the drawbacks to using a PowerShell script or function is that you have to write it. For many IT Pros, especially those new to PowerShell, it can be difficult to know where to start. I think more people would write their own tools if there was an easy way to automatically write them. So here's my solution. I wrote a function called New-PSCommand that is intended as a rapid development tool for a PowerShell advanced function. It should work in either PowerShell v2 or v3.
ManageEngine ADManager Plus - Download Free Trial
Exclusive offer on ADManager Plus for US and UK regions. Claim now!
Here's the function, although I'm not going to spend much time explaining how it works but rather how to use it.
Function New-PSCommand {
#comment base help goes here
[cmdletbinding()]
Param(
[Parameter(Mandatory=$True,HelpMessage="Enter the name of your new command")]
[ValidateNotNullorEmpty()]
[string]$Name,
[ValidateScript({
#test if using a hashtable or a v3 [ordered] hash table
($_ -is [hashtable]) -OR ($_ -is [System.Collections.Specialized.OrderedDictionary])
})]
[Alias("Parameters")]
[object]$NewParameters,
[switch]$ShouldProcess,
[string]$Synopsis,
[string]$Description,
[string]$BeginCode,
[string]$ProcessCode,
[string]$EndCode,
[switch]$UseISE
)
Write-Verbose "Starting $($myinvocation.mycommand)"
#add parameters
$myparams=""
$helpparams=""
Write-Verbose "Processing parameter names"
foreach ($k in $newparameters.keys) {
Write-Verbose " $k"
$paramsettings = $NewParameters.item($k)
#process any remaining elements from the hashtable value
#@{ParamName="type[]",Mandatory,ValuefromPipeline,ValuefromPipelinebyPropertyName,Position}
if ($paramsettings.count -gt 1) {
$paramtype=$paramsettings[0]
if ($paramsettings[1] -is [object]) {
$Mandatory = "Mandatory=`${0}," -f $paramsettings[1]
Write-Verbose $Mandatory
}
if ($paramsettings[2] -is [object]) {
$PipelineValue = "ValueFromPipeline=`${0}," -f $paramsettings[2]
Write-Verbose $PipelineValue
}
if ($paramsettings[3] -is [object]) {
$PipelineName = "ValueFromPipelineByPropertyName=`${0}" -f $paramsettings[3]
Write-Verbose $PipelineName
}
if ($paramsettings[4] -is [object]) {
$Position = "Position={0}," -f $paramsettings[4]
Write-Verbose $Position
}
}
else {
#the only hash key is the parameter type
$paramtype=$paramsettings
}
$item = "[Parameter({0}{1}{2}{3})]`n" -f $Position,$Mandatory,$PipelineValue,$PipelineName
$item +="[{0}]`${1}" -f $paramtype,$k
Write-Verbose "Adding $item to myparams"
$myparams+="$item, `n"
$helpparams+=".PARAMETER {0} `n`n" -f $k
#clear variables but ignore errors for those that don't exist
Clear-Variable "Position","Mandatory","PipelineValue","PipelineName","ParamSettings" -ErrorAction SilentlyContinue
} #foreach hash key
#get trailing comma and remove it
$myparams=$myparams.Remove($myparams.lastIndexOf(","))
Write-Verbose "Building text"
$text=@"
Function $name {
<#
.SYNOPSIS
$Synopsis
.DESCRIPTION
$Description
$HelpParams
.EXAMPLE
PS C:\> $Name
.NOTES
Version: 0.1
Author : $env:username
.INPUTS
.OUTPUTS
.LINK
#>
[cmdletbinding(SupportsShouldProcess=`$$ShouldProcess)]
Param (
$MyParams
)
Begin {
Write-Verbose "Starting `$(`$myinvocation.mycommand)"
$BeginCode
} #begin
Process {
$ProcessCode
} #process
End {
$EndCode
Write-Verbose "Ending `$(`$myinvocation.mycommand)"
} #end
} #end $name function
"@
if ($UseISE -and $psise) {
$newfile=$psise.CurrentPowerShellTab.Files.Add()
$newfile.Editor.InsertText($Text)
}
else {
Write $Text
}
Write-Verbose "Ending $($myinvocation.mycommand)"
} #end New-PSCommand function
The premise of this function is to take a hash table of parameter definitions and create a new PowerShell advanced function.
The hash table key is the name of your parameter and the key is its type. The only other value you need is the name for your new function. The New-PSCommand function creates a new advanced function, complete with comment-based help, and writes the text to the pipeline. That way you can either review it, pipe it to Out-File or copy it to the clipboard.
PS C:\>$paramhash=@{Name="string[]";Test="switch";Path="string"}
PS C:\> New-PSCommand -name "Set-MyScript" -Newparameters $paramhash | out-file "c:\scripts\set-myscript.ps1"
The hash table of parameters for my Set-MyScript function includes an array of strings for $Name, a string for $Path, and a switch for $Test. Here's the output:
Function Set-MyScript {
<#
.SYNOPSIS
.DESCRIPTION
.PARAMETER Path
.PARAMETER Name
.PARAMETER Test
.EXAMPLE
PS C:\> Set-MyScript
.NOTES
Version: 0.1
Author : Jeff
.INPUTS
.OUTPUTS
.LINK
#>
[cmdletbinding(SupportsShouldProcess=$False)]
Param (
[Parameter()]
[string]$Path,
[Parameter()]
[string[]]$Name,
[Parameter()]
[switch]$Test
)
Begin {
Write-Verbose "Starting $($myinvocation.mycommand)"
} #begin
Process {
} #process
End {
Write-Verbose "Ending $($myinvocation.mycommand)"
} #end
} #end Set-MyScript function
All you need to do is fill in the script with the code you want to run. New-PSCommand does all of the grunt work for you leaving you just the fun part. I also support an alternate hashtable setup if you want to specify some parameter attributes. Create a hash table using this format:
@{ParamName="type[]",Mandatory,ValuefromPipeline,ValuefromPipelinebyPropertyName,Position}
Here's an example:
$h = @{Name="string[]",$True,$True,$False,0;
Path="string",$false,$false,$false,1;
Size="int",$false,$false,$true;
Recurse="switch"
}
I also let you specify commands to use in the Begin, Process and End scriptblocks. You can also define values for the help synopsis and description.
The last little bell on this tool is that if you run it in the PowerShell ISE, you can use the -UseISE switch which will open your new script in a new file in the ISE. This means you could open a new PowerShell tab in the ISE and run commands like this:
$hash = [ordered]@{
Name="string[]",$True,$True,$False,0
Path="string",$false,$false,$false,1
PixieDust="int",$false,$false,$true
NoUnicorn="switch"
}
$begin={
#initialize some variables
$arr=@()
$Love=$True
$ring=1
}
$end="write-host 'Finished' -foreground Green"
$synopsis = "Get magical user data"
$desc = @"
This command will do something really amazing and magical. All you need to do is provide
the right amount of pixie dust and shavings from a unicorn horn.
This requires PowerShell v4 and a full moon.
"@
. C:\scripts\New-PSCommand.ps1
New-PSCommand -Name Get-UserData -NewParameters $hash -BeginCode $begin -EndCode $end -Synopsis $synopsis -Description $desc -UseISE
By the way, I'm running PowerShell v3 so I can use a [ordered] hash table which I encourage you to use if you can. When executed, I get a new script in the ISE ready for me to finish.
Function Get-UserData {
<#
.SYNOPSIS
Get magical user data
.DESCRIPTION
This command will do something really amazing and magical. All you need to do is provide
the right amount of pixie dust and shavings from a unicorn horn.
This requires PowerShell v4 and a full moon.
.PARAMETER Name
.PARAMETER Path
.PARAMETER PixieDust
.PARAMETER NoUnicorn
.EXAMPLE
PS C:\> Get-UserData
.NOTES
Version: 0.1
Author : Jeff
.INPUTS
.OUTPUTS
.LINK
#>
[cmdletbinding(SupportsShouldProcess=$False)]
Param (
[Parameter(Position=0,Mandatory=$True,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$False)]
[string[]]$Name,
[Parameter(Position=1,Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelineByPropertyName=$False)]
[string]$Path,
[Parameter(Mandatory=$False,ValueFromPipeline=$False,ValueFromPipelineByPropertyName=$True)]
[int]$PixieDust,
[Parameter()]
[switch]$NoUnicorn
)
Begin {
Write-Verbose "Starting $($myinvocation.mycommand)"
#initialize some variables
$arr=@()
$Love=$True
$ring=1
} #begin
Process {
} #process
End {
write-host 'Finished' -foreground Green
Write-Verbose "Ending $($myinvocation.mycommand)"
} #end
} #end Get-UserData function
I hope that a tool like this helps cut down on your development time. Please download New-PSCommand and let me know what you think.
Very interesting post!
Have you thought of making an add-on for ISE/PowerGUI to “Create a new function in current script”?
Quick typo:
“The hash table key is the name of your parameter and the value is it’s type.”
I have such a add-on and I thought I had published it. If not, I’ll have to polish it up and get it posted.