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"
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.
µ