Parameter sets in a PowerShell function determine the parameter combinations the function accepts. The example discussed in this post illustrates the use parameter sets

Adam Bertram

Adam Bertram is a 20-year IT veteran, Microsoft MVP, blogger, and trainer. Adam is the founder of the e-learning tech screencast platform TechSnips. Catch up on Adam’s articles at adamtheautomator.com, or follow TechSnips on Twitter at @techsnips_io.
Contents of this article

When building functions, it's always a best practice to think ahead a bit and decide which values inside that function may change over time. These values will be good candidates to use as function parameters. When you have a function that has parameters you must use together or parameters that may conflict with others, it's time to start thinking about parameter sets.

Parameter sets "compartmentalize" various parameters. Executing a function only allows one parameter set. Parameter sets let you define function parameters in a way where you can be sure only a certain number of parameters occur once for each execution. To explain parameter sets, let's take an example function with a couple of parameters in a single parameter set.

The function above is a simple function that checks to see if a server's file share is available. If so, it will return True. If not, it will return False. We can execute this function interactively. Perhaps you've got this loaded in a module and periodically test file shares on servers via the PowerShell console.

One day you might come across a situation where you have a bunch of servers that need to have a few different shares available, and you want to determine whether they do. A snippet of the CSV looks like below.

CSV file servers with their file shares

CSV file servers with their file shares

CSV data ^

After some finagling, you may eventually come up with a way to run your Test-FileShare function against all of the computers in the CSV file.

This works, but you'd be better off using the PowerShell pipeline and doing something like this:

As it is, this isn't possible because you haven't built in pipeline support, nor do the properties match up. To build pipeline support into the function, add a parameter called InputObject and build it to accept pipeline input by object like the example below.

Since you've now got a situation where the function will accept input via the InputObject parameter or the others, you can build some if/then logic into the function.

You can now use the pipeline to pass all of those CSV rows to your function. But then you might try to use it interactively like you always have by passing a single computer name and share name to it. You'll find it now prompts you for the InputObject parameter.

Parameter set names ^

You want to be able to keep all the parameters mandatory because they are mandatory, but just in different circumstances. You need parameter sets! We need a parameter set for when we use InputObject and a parameter set for when we use both ComputerName and ShareName. We create parameter sets by assigning the ParameterSetName attribute to each parameter.

We can now use either the InputObject parameter or the ComputerName and ShareName. This allows us to call the function in two different contexts depending on the situation we encounter.

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

5+

Users who have LIKED this post:

  • avatar
  • avatar
  • avatar
Share
7 Comments
  1. David Woosley 1 year ago

    I don't think the spaces before and after the equals sign are allowed.

    ParameterSetName = 'InputObject'

    Regards,

    David

    1+

    • David, did you try it?

      2+

      Users who have LIKED this comment:

      • avatar
    • Panzerbjrn 7 months ago

      It is, it just, IMO, looks terrible...

      0

      • Luc Fullenwarth 7 months ago

        @panzerbjrn

        It's just a question of habits and usages.
        That's how human psychology works: we end loving most of what we do.

        All you need to know is that both methods are working in PowerShell.
        Once you know that, it's up to you to choose your favorite method.

        1+

  2. David Figueroa 1 year ago

    You can use spaces around the = signs without any problem.  I do that all the time in my parameter declarations..

    David F.

    1+

  3. David Woosley 1 year ago

    Y'all are clearly wrong. How dare you question my three months of part-time Powershell coding!

    1+

  4. Mason 1 year ago

    Thanks, Adam! One note:

    is missing from the InputObject parameter. 🙂

    1+

Leave a reply

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2019

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account