<\/p>\n
![\"Hey,](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/q-for-powertip.jpg\" "\\"Hey,")
Hey, Scripting Guy! I do a lot of work from the Windows PowerShell command line. In fact, I write very few scripts, but I run lots of commands. I would like to create a custom Windows PowerShell function that contains the capability of several commands. This would allow me to be able to type a single command, and have it perform multiple actions. I used to be able to do things like this in other languages. Can it be accomplished in Windows PowerShell?<\/p>\n
— EJ<\/p>\n
<\/p>\n
![\"Hey,](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/a-for-powertip.jpg\" "\\"Hey,")
Hello EJ, <\/p>\n
Microsoft Scripting Guy Ed Wilson here. This is going to entail quite a bit of detail to answer, so I am going to get out of the way and let James get to work on your answer. <\/p>\n
James Brundage is the founder of Start-Automating (http:\/\/www.start-automating.com<\/a>), a company dedicated to saving people time and money by helping them automate. Start-Automating offers Windows PowerShell training and custom Windows PowerShell and .NET Framework development. James formerly worked on the Windows PowerShell team at Microsoft, and he is the author of the PowerShellPack<\/a>, a collection of Windows PowerShell scripts to enable building user interfaces, interact with RSS feeds, get system information, and more.<\/p>\n <\/p>\n In the previous post<\/a>, I covered how to use splatting to create commands that wrap other commands. Wrapper commands allowed us to take something unwieldy (such as Get-Counter ‘\\Processor(_total)\\% Processor Time’<\/strong>) into something convenient and memorable (such as Watch-ProcessorPerformance<\/strong>). Today, we learn how to build bridges.<\/p>\n Specifically, we learn how to bridge the functionality of two complicated commands to make one convenient one. Creating wrappers and bridges can help make a mess of long command lines into a neat pile or organized commands. We’re also going to learn how to handle wrapping commands with default parameters.<\/p>\n We’ll do this by writing a function called Watch-File<\/strong>. Watch-File<\/strong> will merge two commands, Register-ObjectEvent<\/a> and Get-ChildItem<\/strong>. It will also add one parameter that will let us choose which events to watch for, which will effectively map to the –EventName<\/strong> parameter of Register-ObjectEvent<\/strong>.<\/p>\n Watch-File<\/strong> is a great candidate because: <\/p>\n To write this command, we’ll need to understand a little more about the stuff that surrounds splatting, CommandMetaData<\/strong> and ProxyCommands<\/strong>. You used both of these things in the last article, but New-ScriptCmdlet<\/strong> hid them so that you didn’t have to deal with them. Now that we’re writing a more complex command, we won’t be able to avoid the inner workings.<\/p>\n Remember how proxy commands were designed to wrap other commands in Windows PowerShell so that they can be called remotely? Well, in order for this to work, the ProxyCommands<\/strong> had to be able to get a lot more information about the command than was available in the CommandInfo<\/strong> object (what comes back from Get-Command<\/strong>). In Windows PowerShell 1.0, there were a couple of internal classes that had this extra information, CommandMetaData<\/strong> and ParameterMetaData<\/strong>. In Windows PowerShell 2.0, these classes were made public and had a little bit added onto them. The ProxyCommand<\/strong> class takes this information and generates a parameter block and cmdlet binding.<\/p>\n You can add or remove items to the command and parameter metadata, so if you’re looking at wrapping commands with a few parameters, you can often approach writing it in terms of manipulating this metadata.<\/p>\n To get the right parameter block for these commands, we’ll use some ParameterMetaData<\/strong> magic. Every command in Windows PowerShell has a CommandMetaData<\/strong> object, and that in turn contains several ParameterMetaData<\/strong> objects. To make this function, we need to collect all the parameters from Register-Object<\/strong> event, omit the two parameters we won’t be wanting anymore, and then add one for the type of file change we want.<\/p>\n When you’re using a programming language to write other programs, this is called metaprogramming. While this walkthrough covers a lot of ground about how to use splatting to fuse two functions together, it also contains a lot of very useful information about techniques you can use anytime you want to write scripts that write other scripts in Windows PowerShell.<\/p>\n Let’s start by getting all of the parameters from Register-Object<\/strong> event. The command to do this is shown here:<\/p>\n Now let’s filter out the parameters we don’t want:<\/p>\n To get the right parameter block for these commands, we’ll use some ParameterMetaData<\/strong> magic.<\/p>\n In order to use the same underlying tricks that the New-ScriptCmdlet<\/strong> does (the New-ScriptCmdlet<\/strong> was discussed in yesterday’s Hey, Scripting Guy! post<\/a>), we need to add these new parameters to a command metadata object. The command to do this is shown here:<\/p>\n Now let’s add the parameters from Register-ObjectEvent<\/strong>. To do this, use the add<\/strong> method:<\/p>\n We’ll need to add one more parameter to the combined list, but that parameter is a lot harder to build from scratch with command metadata than it is to type, so let’s turn what we’ve got now into a parameter block. We can do this with a nifty method on a class that Windows PowerShell uses to make Import\/Export-PSSession<\/a> work: [Management.Automation.ProxyCommand]::GetParamBlock()<\/strong>, as shown here:<\/p>\n Now to add our new parameter. Our new parameter will be called -For<\/strong>, and it will accept as input any valid event name on the class IO.FileSystemWather<\/strong>. By default, it will watch for the events: Deleted<\/strong>, Changed<\/strong>, and Renamed<\/strong>. To make sure the arbitrary string that we give the function is actually an event name, we’ll use the ValidateScript<\/strong> attribute. ValidateScript<\/strong> is a really great tool to have in your scripting repertoire, especially when you want to constrain strings to be a particular sort of information. Here’s what the parameter would look like on its own:<\/p>\n Making one combined parameter block is now just one little string with a couple of variables:<\/p>\n $newParameter”<\/span> <\/div>\n<\/blockquote>\n In order to use splatting to join the commands and the default values, we’ll need to keep creating hashtables<\/strong> to provide the input. The technique I’ve learned to use for this is pretty simple. Find all of the variables that have a name that matches the input for a command, and put them into a hashtable<\/strong>. To make sure we do this efficiently, we’ll collect the parameter names from Get-ChildItem<\/strong> and Register-ObjectEvent <\/strong>in the begin block. This technique is illustrated here:<\/p>\n You might notice that the $paramblock<\/strong> variable I created earlier holds a string. The $beginBlock<\/strong> I created above holds a script block. This is done purely for the ease of authoring. When writing scripts that will in turn write other scripts, I find that it is helpful to put any portion of the code that will not change into a script block. As script block, as you may recall, is delineated by braces (curly brackets). This does a number of things for us, such as the ones listed here:<\/p>\n We’re almost done. The Process block is the last piece of the function about which we need to worry. After this is completed, stringing the whole thing together is pretty trivial. The Process block needs to collect the parameters for Get-ChildItem<\/strong> and Register-ObjectEvent<\/strong> cmdlets. To do this, it will look for any variable that is declared that also has a value. Then it needs to loop through the results of Get-ChildItem<\/strong>, create a FileSystemWatcher<\/strong> for each<\/a> item, and run Register-ObjectEvent<\/strong> once for each –For<\/strong> provided. The following code accomplishes all these tasks:<\/p>\nA Series on Splatting (and Stuff)<\/h4>\n
Part 3 – Bridging Commands Together with Splatting and CommandMetaData<\/h5>\n
\n
\n
\n
<\/span>Where-Object<\/span> <\/span>{<\/span>
<\/span>$_<\/span>.Name<\/span> <\/span>-ne<\/span> “InputObject” <\/span>-and<\/span> <\/span>$_<\/span>.Name<\/span> <\/span>-ne<\/span> “EventName”
<\/span>}<\/span> <\/div>\n<\/blockquote>\n\n
\n
<\/span>$null<\/span> <\/span>=<\/span> <\/span>$getChildItemMetaData<\/span>.Parameters.Add(<\/span>$parameter<\/span>.Name,<\/span> <\/span>$parameter<\/span>)<\/span>
<\/span>}<\/span> <\/div>\n<\/blockquote>\n\n
\n
[ValidateScript({
if (-not ([IO.FileSystemWatcher].GetEvent($_))) {
$possibleEvents = [IO.FileSystemWatcher].GetEvents() |
ForEach-Object { $_.Name }
throw “$_ is not an event on [IO.FileSystemWatcher]. Possible values are: $possibleEvents”
}
return $true
})]
[string[]]
$For = (“Deleted”, “Changed”, “Renamed”)
‘<\/span> <\/div>\n<\/blockquote>\n\n
\n
<\/span>$getChildItemParameterNames<\/span> <\/span>=<\/span>
<\/span>(<\/span>Get-Command<\/span> <\/span>Get-ChildItem<\/span>).Parameters.Keys<\/span>
<\/span>$registerObjectEventParameterNames<\/span> <\/span>=<\/span>
<\/span>(<\/span>Get-Command<\/span> <\/span>Register-ObjectEvent).Parameters.Keys<\/span>
<\/span>}<\/span> <\/div>\n<\/blockquote>\n\n
\n
<\/span>#<\/span> <\/span>Declare<\/span> <\/span>a<\/span> <\/span>hashtable<\/span> <\/span>to<\/span> <\/span>store<\/span> <\/span>each<\/span> <\/span>set<\/span> <\/span>of<\/span> <\/span>parameters<\/span>
<\/span>$getChildItemParameters<\/span> <\/span>=<\/span> <\/span>@{}<\/span>
<\/span>$registerObjectEventParameters<\/span> <\/span>=<\/span> <\/span>@{}<\/span>
<\/span>#<\/span> <\/span>Walk<\/span> <\/span>