cmdlet parameter sets

I'm writing a cmdlet that has a set of 4 switch parameters. A user can
specify one and only one of these 4 for a given execution. In order to
implement that, should I put the switchparameters in a single parameter set?
Is that the right way to skin this problem?

Darren

Darren Mar-Elia wrote: If I understand correctly what you're looking for, I'd set 4 different
parameter sets, and use SwitchParameter within each.

The parameter set will make sure only one parameter is passed, and your
SwitchParameter will ensure *something* was passed as an argument to the
parameter.

You can also set a default parameter set if one is likely to be used
more often than others.

Marco

--
Microsoft MVP - Windows PowerShell
http://www.microsoft.com/mvp

PowerGadgets MVP
http://www.powergadgets.com/mvp

Blog:
http://marcoshaw.blogspot.com

Thanks Marco-
So let me clarify it so I can ensure I'm understanding your response.

Let's assume that the cmdlet is setting permissions. There are 4 permission
possibilities:

Read
Write
Modify
Delete

I want the user to pass only one of these four when they execute the cmdlet.

So it sounds like what you are saying is that I should create 4 parameter
sets and put one option in each? The way I was trying it was to create one
parameter set that contains all four options, but I haven't quite gotten it
right yet.


Darren


"Marco Shaw [MVP]" <marco.shaw@_NO_SPAM_gmail.com> wrote in message
news:%23tWYPVWIIHA.4956@xxxxxx

Darren Mar-Elia wrote: I might be wrong on what I said about the default, but will try to find
time to double-check.

If you put all the parameters into one parameter set, I think the goes
against the use of a parameter set in the first place.

Even using parameter sets like I'm suggesting isn't really the
documented use. Parameter sets would generally be used, as per the SDK
docs, etc., when you want to force the combination of some of the
parameters together (Read *and* Write, Read *and* Modify, etc.).

But someone else with more dev experience can feel free to override me
here...

Marco

--
Microsoft MVP - Windows PowerShell
http://www.microsoft.com/mvp

PowerGadgets MVP
http://www.powergadgets.com/mvp

Blog:
http://marcoshaw.blogspot.com

On Nov 7, 1:10 pm, "Marco Shaw [MVP]" <marco.shaw@_NO_SPAM_gmail.com>
wrote: Marco is right on the money here with using four different
parametersets. If you have four mutually exclusive switchparameters,
the best way to enforce this without using a programmatic approach is
to place each into its own parameterset. Only one parameterset can be
active at runtime, ergo only one of the four switchparameters can be
specified.

Regarding a default parameterset, this is not required if you only
have four switch parameters and four parametersets. A default
parameterset is only used to decide the active parameterset should an
ambiguity arise where the user specified parameters match more than
one parameterset.

Hope this helps,

- Oisin / x0n.

Oisin-
That's great info! Thanks.


"Oisin Grehan" <oising@xxxxxx> wrote in message
news:1194466029.652290.295990@xxxxxx

Hi Darren,

Can I ask a question about this? In this particular case, wouldn't an
enumeration be more appropriate? It might depend on the details of your
cmdlet I guess, but think about this. If you use 4 different parameter sets
and then attempt to call the cmdlet in PowerShell with two parameters, one
of which is unique to each parameter set, you will be presented with this
error:

"Parameter set cannot be resolved using the specified named parameters."

You can see this if you call Get-ChildItem -path . -literalPath C:\

Alternatively, if you make the parameter an enumeration, then if you attempt
to call the cmdlet in PowerShell with an invalid value your cmdlet can
return something much more user friendly, such as this:

"Cannot bind parameter 'Foo'. Cannot convert value "bar" to type
"My.Enumeration.Type" due to invalid enumeration values. Specify one of the
following enumeration values and try again. The possible enumeration values
are "Read, Write, Modify, Delete".

You can see this by calling Set-ExecutionPolicy foo

The only caveat to this is that if you don't want to support more than one
at a time and you don't want users inadvertently passing in an incorrect
value such as Read,Write and having it treated as a valid value you have to
force your enumeration values use individual bits (e.g. 0x01 for Read, 0x02
for Write, 0x04 for Modify, 0x08 for Delete) and then switch on the
parameter in the cmdlet code to check to see if it is equal to one of the
bits.

This might be a better solution for you usability wise than offering four
mutually exclusive switch parameters and multiple parameter sets. Parameter
sets are great when they are necessary but I think they add complexity,
impact usability, and hurt the user experience when they are not.

--
Kirk Munro
Poshoholic
http://poshoholic.com

"Darren Mar-Elia" <dmanonymous@xxxxxx> wrote in message
news:9B206A69-1941-43E2-90F3-D6ADC307EE25@xxxxxx

On Nov 7, 4:22 pm, "Kirk Munro" <so...@xxxxxx> wrote:
Hey, I've looks like I'm having a disagree-with-kirk day here, but I
think this is a little too absolute a statement to make. ParameterSets
might add some complexity for the developer, but IMO, they don't add a
proportionate complexity to the end user experience. I think using
enums in posh script is a poor replacement for well-named and
constrained switches. Relying on an error mechanism for discovery just
doesn't sit right with me. The discovery mechanism should always be
get-help or -? ; if you look at any core cmdlet's help right now,
you'll see that by using parametersets, the different combinations are
listed quite nicely for you in a sequential and separate manner. Using
parametersets also aids the generation of said documentation for a
developer. We use them extensively in Pscx, which is not a reason to
use them in itself, but I digress.

That said, parametersets are lacking in a number of ways, the most
painful being that a parameter can only be a member of one
parameterset. This means that using a pure attribute based constraint
for switches, Marco's example of constraining separate parameters
"read", "write" and "modify" to just "read,write" and "read,modify" is
not possible because the "read" property must then sit in two
parametersets. So, like you say, it really depends on the complexity
of the cmdlet - sometimes you have to use an enumeration as it's
better than just allowing a pure string input, but for this case, I
would strongly recommend using parametersets as this is exactly what
they are designed for. Yes, the error could be better, but this is
more reason to ship excellent and concise help with your cmdlets.

Cheers,

- Oisin / x0n

disagree-with-Kirk day? lol

I guess it depends on the cmdlet.

Some cmdlets have a *lot* of parameters, so parameter sets are quite
difficult to read in the documentation and mutually exclusive switch
parameters could easily become lost. This may simply be an issue with the
documentation formatting though. For other cmdlets, if they don't have many
parameters but they use 4 parameter sets, each with one unique switch
parameter, I would still argue that an enumeration is easier from an end
user perspective. I don't like error mechanisms for discovery (even if they
are convenient), but you don't need to rely on those. The help information
should give you whatever information you might need about a parameter.

Get-Help Get-Command -parameter CommandType

Or if you know the parameter type you can just get the valid values this
way:

[System.Enum]::GetValues("System.Management.Automation.PSMemberTypes")
With respect to this statement, someone might thing this is a little too
absolute to make as well. And in either case, whether you use enumerations
or parameter sets with switches, get-help is the discovery mechanism. Enums
give the added benefit of returning the valid values if you're wrong as well
though. So as I said above you don't have to rely on the error mechanism
for discovery -- they are just convenient when you're being lazy.

I'm still on the Enum side of the fence for now.

--
Kirk Munro
Poshoholic
http://poshoholic.com


"Oisin Grehan" <oising@xxxxxx> wrote in message
news:1194472003.733009.215920@xxxxxx