Huddled Masses » SourceCode http://huddledmasses.org You can do more than breathe for free... Sat, 28 Jan 2012 21:37:20 +0000 en hourly 1 http://wordpress.org/?v=3.3.1 Writing Cmdlets for the PowerShell Pipeline http://huddledmasses.org/writing-cmdlets-for-the-powershell-pipeline/ http://huddledmasses.org/writing-cmdlets-for-the-powershell-pipeline/#comments Tue, 06 Nov 2007 05:25:57 +0000 Joel 'Jaykul' Bennett http://HuddledMasses.org/writing-cmdlets-for-the-powershell-pipeline/ In a continuation of what is, sadly, becoming a series on how the PowerShell Pipeline works … Karl Prosser brought to my attention that certain powershell commands which have an -InputObject parameter don’t actually work when you pass something into it … so I thought I should create a cmdlet to show you how to correctly handle the InputObject parameter with the ValueFromPipeline set so you can pass the input in either way.

To demonstrate the problem, try this:


$a = @("A","B","A","C")
$a | Select -First 3 -Unique
Select -First 3 -Unique -InputObject $a

This should expose two weirdnesses about how the Select-Object cmdlet works:

  1. The -First parameter affects the input before the -Unique parameter does.
  1. When you pass the input in via -InputObject, the whole array is treated as a single object, and the command basically doesn’t do anything.

The big problem with this behavior is that there’s essentially no hint that you’ve done something wrong — there’s actually no way to make Select-Object work properly except by passing the objects in via the pipeline. The bigger problem is that it would have been simple for the Microsoft team to catch this and alert you, but they didn’t — so you probably won’t even notice there’s a problem until you run it on a trivial data set like my example. The even bigger problem is that it doesn’t just affect Select-Object (try it with Where-Object, just for instance).

The simplest fix

When this came up in the #PowerShell IRC channel Oisin initially defended this as an unavoidable side effect of the way the cmdlet system works. However, after playing with the idea for a bit, we found it’s actually trivial to stop, although I found it hard to explain without actually demonstrating an alternative. The simplest possible alternative is just to throw an exception if the value is passed in as an argument instead of via the pipeline. That would preserve the same level of functionality you have now — but cause an error in those cases where it wouldn’t work anyway.


protected override void BeginProcessing()
{
   if (_input != null)
   {
      throw new ArgumentException("You must pass InputObject via the pipeline!");
   }
   base.BeginProcessing();
}

A better way to handle input

Of course, you can do better than that ;) . So, I hereby present the first version of my PowerShell Pipeline Template Cmdlet. It’s pretty simple really (once you get past all the cmdlet overhead): basically, you check in the BeginProcess() method to see if the InputObject parameter has been set, and set an alternate private variable. Then, in the ProcessRecord() method, we have two alternate computation paths: the normal path, and a second path for when the collection is passed in as an argument. In that case, you recurse and call the ProcessRecord method once for each item in the collection.

I’m sure some of you will have some improvements you can make, feel free to continue the development on the PowerShell Central scripts page or by sending feedback in the form below, but for now, here’s the Test-Pipeline Cmdlet Binary and the source code.

The Code


// An improvement! Now we accept a single object (like Select-Object does)
// But, unlike Select-Object, if an array is passed into the argument -InputObject
// we still manage to process each item in the array, as we would in the pipeline
//
// Try it out:   "a","b","c"| Test-Pipeline -verbose
// Versus this:  Test-Pipeline -verbose -input @("a","b","c")
//
// If you don't set the -verbose flag, you shouldn't be able to tell them apart
// The first way, the "1" invocation hits ProcessRecord for "a"
// ... before the "2" invocation hits BeginProcessing()
//
// Version History
//    1.0 Just throws an exception
//    2.0 Finds a way to enumerate ProcessRecord from BeginProcessing
//        There is still a slight difference, which you can see if you test these:
//          Test-Pipeline 1 -input @("a","b","c") -verbose | Test-Pipeline 2 -verbose
//          "a","b","c" | Test-Pipeline 1 -verbose | Test-Pipeline 2 -verbose
//    2.3 Recursed from inside ProcessRecord instead of BeginProcessing
//        Makes the execution look identical in the test case from 2.0
////////////////////////////////////////////////////////////////////////////////
using System;
using System.Collections.Generic;
using System.Text;
using System.Management.Automation;
using System.Collections;

namespace Huddled.TestSnapin
{
    [Cmdlet(VerbsDiagnostic.Test, "Pipeline")]
    public class TestPipelineCommand : Cmdlet
    {

        #region Parameters
        /// <summary>
        /// This is just a name parameter for decorating test cases :)
        /// </summary>
        [Parameter(Position = 0,
            Mandatory = false,
            ValueFromPipelineByPropertyName = false,
            HelpMessage = "A Name for Verbose output"), ValidateNotNullOrEmpty]
        public string Name
        {
            get { return _name; }
            set { _name = value; }
        }
        private string _name = "TestPipeline";


        [Parameter(Position = 1,
            Mandatory = true,
            ValueFromPipeline = true,
            HelpMessage = "Help Text"), ValidateNotNullOrEmpty]
        public object InputObject
        {
            get { return _input; }
            set { _input = value; }
        }
        private object _input;
        private bool _isArgument = false;
        #endregion

        protected override void BeginProcessing()
        {
            WriteVerbose(String.Format("Begin Processing {0}", Name));
            if (_input != null && _input is ICollection)
            {
                _isArgument = true;

                StringBuilder output = new StringBuilder("There's input: ");
                foreach (object _in in (ICollection)_input)
                {
                    output.AppendFormat("{0}, ", _in);
                }
                WriteVerbose(output.ToString());
            }
            base.BeginProcessing();
        }

        protected override void ProcessRecord()
        {
            if (!_isArgument)
            {
                // This is the normal ProcessRecord code
                WriteVerbose(String.Format("Process: {0}", _input));
                WriteObject(_input);
            }
            else
            {
                // This is what we have to do unwrap -InputObject as Arg
                ICollection _collection = _input;
                _isArgument = false; // unset isCollection before recursing
                foreach (object _in in (ICollection)_collection)
                {
                    InputObject = _in;
                    ProcessRecord();
                }
            }
       
        }

        protected override void EndProcessing()
        {
            WriteVerbose(String.Format("End Processing {0}", Name));
            base.EndProcessing();
        }
    }
}
]]> http://huddledmasses.org/writing-cmdlets-for-the-powershell-pipeline/feed/ 4