PowerShell function for creating a PowerShell function template

A couple of weeks ago I published a blog article PowerShell function for creating a script module template and I thought I would follow-up that article with the same type of function for creating a PowerShell function template. Instead of having to remember things like checking to make sure an approved verb is used, that a Pester test is created, and comment based help is entered in the right format, a template such as the one shown in the following code example can make your life much simpler.

  1#Requires -Version 3.0 -Modules Pester
  2function New-MrFunction {
  3
  4<#
  5.SYNOPSIS
  6    Creates a new PowerShell function in the specified location.
  7
  8.DESCRIPTION
  9    New-MrFunction is an advanced function that creates a new PowerShell function in the
 10    specified location including creating a Pester test for the new function.
 11
 12.PARAMETER Name
 13    Name of the function.
 14
 15.PARAMETER Path
 16    Path of the location where to create the function. This location must already exist.
 17
 18.EXAMPLE
 19     New-MrFunction -Name Get-MrPSVersion -Path "$env:ProgramFiles\WindowsPowerShell\Modules\MyModule"
 20
 21.INPUTS
 22    None
 23
 24.OUTPUTS
 25    System.IO.FileInfo
 26
 27.NOTES
 28    Author:  Mike F Robbins
 29    Website: http://mikefrobbins.com
 30    Twitter: @mikefrobbins
 31#>
 32
 33    [CmdletBinding()]
 34    [OutputType('System.IO.FileInfo')]
 35    param (
 36        [ValidateScript({
 37          If ((Get-Verb -Verb ($_ -replace '-.*$')).Verb) {
 38            $true
 39          }
 40          else {
 41            Throw "'$_' does NOT use an approved Verb."
 42          }
 43        })]
 44        [string]$Name,
 45
 46        [ValidateScript({
 47          If (Test-Path -Path $_ -PathType Container) {
 48            $true
 49          }
 50          else {
 51            Throw "'$_' is not a valid directory."
 52          }
 53        })]
 54        [string]$Path
 55    )
 56
 57    $FunctionPath = Join-Path -Path $Path -ChildPath "$Name.ps1"
 58
 59    if (-not(Test-Path -Path $FunctionPath)) {
 60
 61        New-Fixture -Path $Path -Name $Name
 62        Set-Content -Path $FunctionPath -Force -Value "#Requires -Version 3.0
 63function $($Name) {
 64
 65<#
 66.SYNOPSIS
 67    Brief synopsis about the function.
 68
 69.DESCRIPTION
 70    Detailed explanation of the purpose of this function.
 71
 72.PARAMETER Param1
 73    The purpose of param1.
 74
 75.PARAMETER Param2
 76    The purpose of param2.
 77
 78.EXAMPLE
 79     $($Name) -Param1 'Value1', 'Value2'
 80
 81.EXAMPLE
 82     'Value1', 'Value2' | $($Name)
 83
 84.EXAMPLE
 85     $($Name) -Param1 'Value1', 'Value2' -Param2 'Value'
 86
 87.INPUTS
 88    String
 89
 90.OUTPUTS
 91    PSCustomObject
 92
 93.NOTES
 94    Author:  Mike F Robbins
 95    Website: http://mikefrobbins.com
 96    Twitter: @mikefrobbins
 97#>
 98
 99    [CmdletBinding()]
100    [OutputType('PSCustomObject')]
101    param (
102        [Parameter(Mandatory,
103                   ValueFromPipeline)]
104        [string[]]`$Param1,
105
106        [ValidateNotNullOrEmpty()]
107        [string]`$Param2
108    )
109
110    BEGIN {
111        #Used for prep. This code runs one time prior to processing items specified via pipeline input.
112    }
113
114    PROCESS {
115        #This code runs one time for each item specified via pipeline input.
116
117        foreach (`$Param in `$Param1) {
118            #Use foreach scripting construct to make parameter input work the same as pipeline input (iterate through the specified items one at a time).
119        }
120    }
121
122    END {
123        #Used for cleanup. This code runs one time after all of the items specified via pipeline input are processed.
124    }
125
126}"
127
128    }
129    else {
130        Write-Error -Message 'Unable to create function. Specified file already exists!'
131    }
132
133}

When the function is run, two files are created. One for the function containing the template code and one for the Pester test:

1New-MrFunction -Name Get-MrPSVersion -Path "$env:ProgramFiles\WindowsPowerShell\Modules\MyModule"

function-template1a.jpg

Sure, PSScriptAnalyzer or a Pester test could be used to make sure that things like an approved verb are used but both of those options are reactive instead of proactive. If I ended up using an unapproved verb initially until I used one of those tools, I may have hard coded it all over the place so why not treat things like using an approved verb kind of like parameter validation. Don't allow the user to continue until valid input (an approved verb in this case) is provided instead of finding the problem in hindsight.

The function shown in this blog article is a work in progress and can be downloaded from my PowerShell repository on GitHub. Feel free to fork the repository and submit pull requests if you can think of improvements that could be made to the code.

µ