Is this a good "pattern" for processing collection-based parameters which belong to parameter sets of a function?

Question

I've been writing advanced functions for many years now and have even written quite a few modules at this point. But there's one question for which I have never really been able to find an answer.

Let's look at a Cmdlet that Microsoft provides in the MSMQ module, as an example, and "re-implement" it as an advanced PowerShell function: Send-MsmqQueue. But this function will be a bit different than the one provided by the MSMQ module in that not only will it accept multiple MSMQ queues for the $InputObject parameter, but also multiple MSMQ queue names for the $Name parameter, where these two parameters belong to different parameter sets. (The Cmdlet version of this function normally only accepts a single string value for the $Name parameter.) I won't be showing a complete re-implementation, just enough to illustrate what I, at times, find myself doing when this situation arises. (NOTE: one other slight difference is that I will be using the classes from System.Messaging namespace instead of the PowerShell-provided ones in Microsoft.Msmq.PowerShell.Commands namespace. So assume that implicitly, somewhere, Add-Type -AssemblyName System.Messaging has been executed.)

function Send-MsmqQueue {
    [CmdletBinding(DefaultParameterSetName = 'Name')]
    [OutputType([Messaging.Message])]
    Param (
        [Parameter(
            Mandatory,
            ValueFromPipeline,
            ParameterSetName = 'InputObject')
        ]
        [Messaging.MessageQueue[]] $InputObject,

        [Parameter(
            Mandatory,
            ValueFromPipeline,
            ParameterSetName = 'Name')
        ]
        [string[]] $Name,

        # Below is the original parameter name, not mine ;)
        [Messaging.Message] $MessageObject

        # All other normal Send-MsmqQueue parameters elided as they are not
        # needed to illustrate the premise of my question.
    )

    Process {
        # When I have parameters defined as above, the first thing I do in my
        # Process block is "homogenize" the data so I don't have to implement
        # two foreach loops or do the branching on each foreach loop iteration
        # which can obscure the main logic that is being executed, i.e., I get
        # this done all "up-front".
        #
        # One aspect of my question is, from purely a PowerShell perspective,
        # is this hurting performance in any meaningful way? (I know that when it
        # comes to specific implementation details, there are INFINITE ways to
        # write non-performant code, so from purely a PowerShell perspective,
        # as far as the language design/inner-workings, is this hurting
        # performance?
        #
        # NOTE: I don't normally need the wrapping "force this thing to be an
        # array" construct (,<array_items>), BUT, in this case, the C#
        # System.Messaging.MessageQueue class implements IEnumerable,
        # which PowerShell (unhelpfully) iterates over automatically, and results
        # in the messages in the queues being iterated over instead of the queues
        # themselves, so this is an implementation detail specific to this
        # particular function.
        $Queues = (,@(
            if ($PSCmdlet.ParameterSetName -ieq 'Name') {
                # Handle when the parameter is NOT passed by the pipeline...
                foreach ($n in $Name) { [Messaging.MessageQueue]::new($n) }
            } else {
                $InputObject
            }
        ))

        # I like using 'foreach (...) { ... }' instead of ForEach-Object because
        # oftentimes, I will need to break or continue based on implementation
        # details, and using ForEach-Object in combination with break/continue
        # causes the pipeline to prematurely exit.
        foreach ($q in $Queues) {
            $q.Send($MessageObject)
            # Normally, I wouldn't return this, especially since it wasn't
            # modified, but this is a re-implementation of MSFT's Send-MsmqQueue,
            # and it returns the sent message.
            $MessageObject
        }
    }
}

As I stated in the introduction to this question, I have written many functions which take varying collection-based parameters belonging to different parameter sets which can be piped into the function, and this is the pattern that I use. I'm hoping someone can either confirm that this is OK from a PowerShell language/style perspective and/or help me understand why I should not do this and what I ought to consider instead.

Thank you!

Answer 1

A fundamental performance decision is whether you want to optimize for argument-passing vs. pipeline input:

• Declaring your parameters as arrays (e.g. [string[]] $Name) allows efficient passing of multiple input objects by argument (parameter value).

• However, doing so hurts pipeline performance, because a single-element array is then created for each every pipeline input object, as the following example demonstrates: It outputs String[] for each of the scalar string elements of the array passed via the pipeline:

  'one', 'two' | 
    & {
      param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [string[]] $Name
      )
      process {
        $Name.GetType().Name # -> 'String[]' *for each* input string
      }
    }
  

  • Note: For brevity, the example above as well all others in this answer use a script block in lieu of a function definition. That is, a function declaration (function foo { ... }) followed by its invocation (... | foo) is shortened to the functionally equivalent ... | & { ... }

See GitHub issue #4242 for a related discussion.

---

With array parameters, you indeed need to ensure element-by-element processing yourself, notably inside the process block if they're also pipeline-binding.

As for "homogenizing" parameter values of different types so that only one processing loop is required, two fundamental optimizations are possible:

• Declare only a single parameter and rely either on PowerShell to automatically convert values of other types to that parameter's type, or implement an automatically applied custom conversion, which obviates the need for "homogenizing" altogether:

  • The conversion is automatic if the parameter type has a public, single-parameter constructor that accepts an instance of the other type as its (only) argument or - in case the other type is [string], if the type has a static ::Parse() method with a single [string] parameter; e.g.:

    # Sample class with a single-parameter
    # public constructor that accepts [int] values.
    class Foo {
      [int] $n
      Foo([int] $val) {
        $this.n = $val
      }
    }
    
    # [int] values (whether provided via the pipeline or as an argument)
    # auto-convert to [Foo] instances
    42, 43 | & {
      [CmdletBinding()]
      param(
        [Parameter(ValueFromPipeline)]
        [Foo[]] $Foo
      )
      process {
        $Foo # Diagnostic output.
      }
    }
    

    • In your case, [Messaging.MessageQueue] does have a public single-parameter constructor that accepts a string (as evidenced by your [Messaging.MessageQueue]::new($n) call), so you could simply omit the $Name parameter declaration, and rely on the automatic conversion of [string] inputs.

    • A general caveat:

      • This automatic conversion - which also happens with casts (e.g, [Foo[]] (0x2a, 43), see below) and the (rarely used) type-conversion form of the intrinsic .ForEach() (e.g., (0x2a, 43).ForEach([Foo])) - is stricter than calling a single-element constructor with respect to matching the constructor's parameter type.
      • I'm unclear on the exact rules, but using a [double] value, for instance, succeeds with [Foo]::new(42.1) (that is, conversion to [int] is automatically performed), but fails with both [Foo] 42.1 and (42.1).ForEach([Foo]) (the latter currently produces an obscure error message).

  • If the conversion isn't automatic, implement a custom conversion that PowerShell then applies automatically, by way of decorating your parameter with a custom attribute that derives from the abstract ArgumentTransformationAttribute class; e.g.:

    using namespace System.Management.Automation
    
    # Sample class with a single-parameter
    # public constructor that accepts [int] values.
    class Foo {
      [int] $n
      Foo([int] $val) {
        $this.n = $val
      }
    }
    
    # A sample argument-conversion (transformation) attribute class that
    # converts strings that can be interpreted as [int] to [Foo] instances.
    class CustomTransformationAttribute : ArgumentTransformationAttribute  {
      [object] Transform([EngineIntrinsics] $engineIntrinsics, [object] $inputData) {            
        # Note: If the inputs were passed as an *array argument*, $inputData is an array.
        return $(foreach ($o in $inputData) {
          if ($null -ne ($int = $o -as [int])) { [Foo]::new($int) }
          else                                 { $o }
        })
      }
    }
    
    # [string] values (whether provided via the pipeline or as an argument)
    # that can be interpreted as [int] now auto-convert to [Foo] instances,
    #  thanks to the custom [ArgumentTransformationAttribute]-derived attribute.
    '0x2a', '43' | & {
      [CmdletBinding()]
      param(
        [Parameter(ValueFromPipeline)]
        [CustomTransformation()] # This implements the custom transformation.
        [Foo[]] $Foo
      )
      process {
        $Foo # Diagnostic output.
      }
    }
    

• If you do want separate parameters, optimize the conversion process:

  • The auto type-conversion rules described above also apply to explicit casts (including support for arrays of values), so you can simplify your code as follows:

    if ($PSCmdlet.ParameterSetName -eq 'Name') {
      # Simply use an array cast.
      $Queues = [Messaging.MessageQueue[]] $Name
    } else {
      $Queues = $InputObject
    }
    

  • In cases where element-by-element construction to effect conversion is required:

    if ($PSCmdlet.ParameterSetName -eq 'Name') {
      # Note the ","
      $Queues = foreach ($n in $Name) { , [Messaging.MessageQueue]::new($n) }
    } else {
      $Queues = $InputObject
    }
    

    • Note the use of the unary form of , the array constructor ("comma") operator, as in your attempt, albeit:

      • inside the foreach loop, and

      • without @(...) enclosure of the object to wrap in a single-element array, as @(...) itself would trigger enumeration.

      • While Write-Output -NoEnumerate ([Messaging.MessageQueue]::new($n)), as shown in Mathias' answer works too, it is slower. It comes down to a tradeoff between performance / concision vs. readability / signaling the intent explicitly.

    • The need to wrap each [System.Messaging.MessageQueue] instance in an aux. single-element wrapper with unary , / to use Write-Output -NoEnumerate stems from the fact that this type implements the System.Collections.IEnumerable interface, which means that PowerShell automatically enumerates instances of the type by default.^[1] Applying either technique ensures that the [System.Messaging.MessageQueue] is output as a whole to the pipeline (for details, see this answer).

      • Note that this is not necessary in the first snippet, because $Queues = [Messaging.MessageQueue[]] $Name is an expression, to which automatic enumeration does not apply.

      • The above also implies that you need the same technique if you want to pass a single [System.Messaging.MessageQueue] instance or a single-element array containing such an instance via the pipeline; e.g.:

         # !! Without `,` this command would *break*, because
         # !! PowerShell would try to enumerate the elements of the queue
         # !! which fails with an empty one.
         , [System.Messaging.MessageQueue]::new('foo') | Get-Member
        

    • By not using an if statement as a single assignment expression ($Queue = if ...) and instead assigning to $Queue in the branches of the if statement, you additionally prevent subjecting $InputObject to unnecessary enumeration.

---

^{[1] There are some exceptions, notably strings and dictionaries. See the bottom section of this answer for details.}

Answer 2

This pattern ("homogenizing" the input entities based on chosen parameter set) is perfectly valid, and constitutes - in my personal opinion at least - good parameter design.

That being said, you might want to use Write-Output -NoEnumerate to avoid the clunky ,@(...) unwrapped-wrapped-array unpacking trick:

if ($PSCmdlet.ParameterSetName -ieq 'Name') {
    # Handle when the parameter is NOT passed by the pipeline...
    $Queues = foreach ($n in $Name) {
        $queue = [Messaging.MessageQueue]::new($n)
        Write-Output $queue -NoEnumerate
    }
}
else {
    # Input is already [MessageQueue[]], avoid pipeline boundaries entirely
    $Queues = $InputObject 
}