Adding Parameter Sets to a Function

• PowerShell Studio
• Functions
• Windows PowerShell

User Rating: 5 / 5

Like many of you, I really live at the command line, because automation is more efficient than single actions. But, as the command line becomes more complex, we need tools to restore our efficiency. The complex syntax of parameter sets in functions is one of those cases. In this post, I learn to use the Function Editor in PowerShell Studio. I’m not just playing in a GUI. I’ve automated the command line.

——

When I write functions, I often start with the basic command – the one that makes the function work – and then build in features. I might even start with fixed values to test the concept and, after testing, convert them to parameters. Next, I add error handling. And, thinking about errors and the user experience often leads me to add parameter sets.

The syntax for parameter sets and a default parameter set, which requires the CmdletBinding attribute, is tricky. I wrote the about_Function help topics that explain the syntax of these elements, but I still never remember them. Typically, I use snippets for the syntax, or search for an old function to use as a template (dir *ps1 | Select-String DefaultParameterSetName | Select FileName –Unique).

But, in PowerShell Studio, I don’t have to remember any of it. The new Function Editor handles all of the syntax so I can concentrate on my function. Here’s how it works.

I’ll start with a very simple function that gets the value of the HelpUri property of a command. The HelpUri value is the online location of a help topic. It’s actually stored in one of two places, but I want to keep this very simple.

function Get-HelpUri ($Command)
{
    $cmd = Get-Command $Command -ErrorAction SilentlyContinue
    if (!($cmd))
    {
        throw "Cannot find $Command"
    }
    $cmd.HelpUri
}

I still have a lot to do to make this function work correctly, but at this point, I realize that users might want the HelpUri values of all commands in a module. So, I need to add a Module parameter. The Command and Module parameters are exclusive, so I need two parameter sets. But, instead of looking up the syntax for parameter sets, I use the automation in PowerShell Studio 2014.

Here’s the magic. I right click my function and then click Edit Function.

The Function Builder parses the simple function. I don’t need to enter anything that I’ve already defined.

I click Enable Cmdlet Binding, add a Module parameter, set the types for my parameters, and make them mandatory. I don’t need to think about syntax, just about my function.

Next, I add the parameter sets: CmdletSet for the Command parameter and ModuleSet for the Module parameter. I verify that the CmdletSet is selected as the default parameter set. Then, in the Parameters section, I assign each parameter to a parameter set.

Finally, I add the starter help content and output type. (I can do this later, but I like to get a head start.) Then, I click OK.

Wowee!

I haven’t spent a minute fooling with syntax. I didn’t have to worry about square brackets, matching parentheses, the exact names of the attributes (is that ParameterSet or ParameterSetName?), or anything other than my function.

Now, I can work on the implementation of my new Module parameter and other details of my function. Later, when I decide to make the parameters take input from the pipeline, I don’t need to worry about the syntax of the ValueFromPipeline parameter attribute. I just right-click my function and click Edit Function again.

The Function Editor is a real boost to my productivity. In a way, the Function Editor does for Windows PowerShell what Windows PowerShell did for the Windows UI. The result is uniformity, repeatability, efficiency, and fewer errors. That’s just what I need.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next