forked from jdhitsolutions/ISEScriptingGeek
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathNew-PSCommand.ps1
More file actions
234 lines (176 loc) · 13.6 KB
/
New-PSCommand.ps1
File metadata and controls
234 lines (176 loc) · 13.6 KB
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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
#requires -version 3.0
Function New-PSCommand {
<#
.SYNOPSIS
Create an advanced function outline
.DESCRIPTION
This command will create the outline of an advanced function based on a hash table of new parameter values. You will still need to flesh out the function and insert the actual commands.
You might need to tweak parameters in the resulting code for items such a default value, help message, parameter aliases and validation.
The New-PSCommand command takes a lot of the grunt work out of the scripting process so you can focus on the actual working part of the function.
.PARAMETER Name
The name of the new function
.PARAMETER NewParameters
A hash table of new parameter values. The key should be the parameter name. The entry value should be the object type. You can also indicate if it should be an array by using [] with the object type. Here's an example:
@{Name="string[]";Test="switch";Path="string"}
Or you can use an "advanced" version of the hash table to specify optional parameter attributes that follows the 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"
}
You can also specify an ordered hash table if you are running PowerShell v or later.
.PARAMETER ShouldProcess
Set SupportsShouldProcess to True in the new function.
.PARAMETER Synopsis
Provide a brief synopsis of your command. Optional.
.PARAMETER Description
Provide a description for your command. You can always add and edit this later.
.PARAMETER BeginCode
A block of code to insert in the Begin scriptblock. This can be either a scriptblock or a string.
.PARAMETER ProcessCode
A block of code to insert at the start of the Process scriptblock. This can be either a scriptblock or a string.
.PARAMETER EndCode
A block of code to insert at the start of the End scriptblock. This can be either a scriptblock or a string.
.PARAMETER UseISE
If you are running this command in the ISE, send the new function to the editor as a new file.
.EXAMPLE
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"
Create an advanced script outline for Set-MyScript with parameters of Name, Test and Path. Results are saved to a file.
.EXAMPLE
PS C:\> $hash = [ordered]@{Name="string[]",$True,$True,$False,0;Path="string",$false,$false,$false,1;Size="int",$false,$false,$true;Recurse="switch"}
PS C:\> $begin={
#initialize some variables
$arr=@()
$a=$True
$b=123
}
PS C:\> $end="write-host 'Finished' -foreground Green"
PS C:\> $synopsis = "Get user data"
PS C:\> $desc = @"
This command will do something really amazing. 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.
"@
PS C:\> New-PSCommand -Name Get-UserData -NewParameters $hash -BeginCode $begin -EndCode $end -Synopsis $synopsis -Description $desc -useise
Create an advanced function from the ordered hash table. This expression will also insert extra code into the Begin and End scriptblocks as well as enter text for the help synopsis and description. The new command will be opened in the ISE.
.NOTES
Last Updated : 4/15/2014
Version : 2.0
Author : Jeffery Hicks (http://jdhitsolutions.com/blog)
.LINK
http://jdhitsolutions.com/blog/2012/12/create-powershell-scripts-with-a-single-command
.LINK
About_Functions
About_Functions_Advanced
About_Functions_Advanced_Parameters
#>
[cmdletbinding()]
Param(
[Parameter(Mandatory=$True,HelpMessage="Enter the name of your new command")]
[ValidateNotNullorEmpty()]
[string]$Name,
[ValidateScript({
#test if using a hashtable or an [ordered] hash table in v3 or later
($_ -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=@"
#requires -version 3.0
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 {
$Text
}
Write-Verbose "Ending $($myinvocation.mycommand)"
} #end New-PSCommand function