Complex Powershell Functions

Amacc — Sat, 07 Dec 2019 03:32:52 +0000

The other day I mentioned my distaste for using loops like foreach in
powershell. I feel like that for most cases where a foreach loop is used
there is generally a lot more elegant way to use the pipeline. There was
a reference to the Out-IniFile script that has been uploaded. I think this is
actually a great example of a function that is probably a little more
complicated than it should be.

First I would say that the foreach should probably go, there is a great
function that can be used on powershell dictionaries called GetEnumerator.
This will take the key value pairs and split them into an array of objects
with the parameters Name and Value. This works great with the pipeline
since functions can use the named paramater version to get the data to its
own typed variable. This helps since you can leverage the powershell type
system to ensure that invalid data wont be passed down. This eliminates
type checks like !($($InputObject[$i].GetType().Name) -eq "Hashtable").

Next I would say that structure needs to be updated to be optimized for
utilizing the pipeline to its fullest. In that pursuit of that goal and keeping
things dry I try to organize my scripts based on common actions, so if your
writing things to file can you batch the operations in a single place
and just take an array of events. This Out-IniFile script actually lends
itself pretty well to that since there are really only a few commands

Parse input
write verbose
Write to file

This would be easily translated to a couple of real simple functions.
So the first function is goint to take an input object, break it apart
into strings and then write the content to file.

function out-inifile{
    param(
        [Parameter(ValueFromPipeline)][hashtable] $InputObject,
        $FilePath,
        $Encoding
    )
    process{
        $InputObject.GetEnumerator() |  # Split the input item by name & value
            Out-INI                  |  # Get the strings to write
            Add-Content -Path $FilePath -Value $_ -Encoding $Encoding
    }
}

So then the second function just needs to accept a Name and a Value (using
the type system for validation) and pass the new strings downstream. So
within a function you can return data two ways, first with the good old
return statement, second by emitting the data by placing it on its own
line. The first is useful for controlling code flow, say there is need to
return an error code and stop processing. The second is useful for sending
multiple items as an array to a pipeline processor (this works similarly to
the yield keyword in python).

Function Out-INI{
    param(
        [Parameter(ValueFromPipelineByPropertyName)][string] $Name,
        [Parameter(ValueFromPipelineByPropertyName)][hashtable] $Value
    )
    process {
        "[$Name]"                            # Emit Header
        $Value.GetEnumerator() |
            %{ "$($_.Name)=$($_.Value)"}     # Emit key=value
        ""                                   # Emit empty line
    }
}

This lets us capture the header, all the internal keys then the final empty
line. Then the first method will write all the lines to the file.

This code can be found on the powershell gallery at
https://www.powershellgallery.com/packages/PowershellTools/1.1.1

Powershell & The Pipeline

Amacc — Sat, 07 Dec 2019 03:31:15 +0000

So in my experience in working in a complex it environment is that it doesn't
take that long before you see a number of scripts like this floating around.

$computers = import-csv somecomputerlist.csv

foreach ($computer in $computers) { 
    if(Test-Connection $computer.ComputerName){
        # Do something with the computer here
    }
}

Then I might be asked to give some guidance on where
Then someone tasked with a cleanup effort might be pointed to me for guidance
on the effort. So I guess its definitely a good first start, they are at
least pulling data from a file instead of hardcoding it into the script.

Most of the time my suggestion is to move it to a function so that we can get
some reuse out of this bad boy. Then a few days a request comes in to
review some changes.

Function Process-Computers {
    param ([string[]]$computers)
    foreach ($computer in $computers) { 
        if(Test-Connection $computer.ComputerName){
            # Do something with the computer here
        }
    }
}

So I guess this is a good start, we can dot source the file then do something
like the following.

Process-Computers ( Get-Content $SomeFilePath )

Get-ChildItem $computerReportsDirectory | 
    %{ Process-Computers (Get-Content $_ }

But we could do better. So where do we go from here?

The Pipeline

Powershell functions are a little unique when
compared with other languages, they have the ability to declare a proces loop.
This process loop is integrated into the parameters block to pull pieces of
data off of the incoming items. So how would we use this?

Function Process-Computers{
    param(
        [Parameter(ValueFromPipelineByPropertyName)]
        [string]$ComputerName
    )
    process{ 
        if(Test-Connection $ComputerName){
            # Do something with the computer here
        }
    }
}

Wait a minute where did the loop go? So to explain that first we need to
talk about the pipeline. So we can think of the pipeline operator as a device
that lets us redirect the output of one command into the input of another.
So with a command like

gci \\some\share | test-path

we would think of it as taking the output of listing a remote directory and
running the test-path command on them.

This is integrated into the way that
functions work in powershell in 2 ways, the parameters and the process block.

Parameters

The pipeline integration with the parameters comes in the form of the Parameter
variable decorator options. There are 2 options that we have available
ValueFromPipelineByPropertyName and ValueFromPipeline. The first will take the
object and assign it to that variable and the latter will set itself to a
reference of the inputs parameter.

Function SomeFunction{
    param(
        [Parameter(ValueFromPipeline)]
        $Input,
        [Parameter(ValueFromPipelineByPropertyName)
        [string]$Name
    )
    process{
        $Name -eq $Input.Name
    }
}

Process Block

Then in the above statement the process block will act similar to the body of
a loop, placing an array of items one by one through the process block. Take
note that in the parameter we still can type the variable, so the name above
would be of type string when used in the process block. This does mean that
if the name field actually was an object it would be cast to a string using.

This then allows for a wide array of use cases.

Import-CSV serverlist |
    Process-Computers

invoke-restmethod http://cmdb.link/servers | # Query for the results
    select -expandproperty results |         # Expand the results array
    Process-Computers

Forem: Amacc

Complex Powershell Functions

Powershell & The Pipeline

The Pipeline

Parameters

Process Block