Windows

Problem

Your function primarily takes its input from the pipeline, and you want it to perform the same steps for each element of that input.

Solution

To write a pipelineoriented function, define your function using the filter keyword, rather than the function keyword. PowerShell makes the current pipeline object available as the $_ variable.

filter GetPropertyValue($property)

{

$_.$property

}

Discussion

Afilter is the equivalent of a function that uses the cmdletstyle keywords and has all its code inside the process section.

Problem

Your script, function, or script block primarily takes input from the pipeline, and you want to write it in a way that makes this intention both easy to implement and easy to read.

Solution

To cleanly separate your script into regions that deal with the initialization, perrecord processing, and cleanup portions, use the begin, process, and end keywords, respectively.

Example 108. A pipelineoriented script that uses cmdlet keywords

function InputCounter

{ begin {

$count = 0 }

Problem

You want to interact with input that a user sends to your function, script, or script block via the pipeline.

Solution

To access pipeline input, use the $input variable as shown by Example 107.

Example 107. Accessing pipeline input

function InputCounter {

$count = 0

## Go through each element in the pipeline, and add up

## how many elements there were.

foreach($element in $input)

{

$count++

}

$count }

Problem

You want to access the arguments provided to a script, function, or script block.

Solution

To access arguments by name, use a param statement:

param($firstNamedArgument, [int] $secondNamedArgument = 0)

"First named argument is: $firstNamedArgument" "Second named argument is: $secondNamedArgument"

To access unnamed arguments by position, use the $args array:

"First positional argument is: " + $args[0] "Second positional argument is: " + $args[1]

Problem

You’ve developed a useful set of functions and want to share them between multiple scripts.

Solution

First, place these common function definitions by themselves in a script, with a name that starts with Library. While the Library prefix is not required, it is a useful naming convention. Example 104 demonstrates this approach.

Example 104. A library of temperature functions

## LibraryTemperature.ps1 ## Functions that manipulate and convert temperatures

Problem

You want your script or function to return data to whatever called it.

Solution

To return data from a script or function, write that data to the output pipeline:

## GetTomorrow.ps1 ## Get the date that represents tomorrow

function GetDate

{

GetDate

}

$tomorrow = (GetDate).AddDays(1) $tomorrow

Discussion

Problem

You have a section of your script that works nearly the same for all input, aside from a minor change in logic.

Solution

As shown in Example 103, place the minor logic differences in a script block, and then pass that script block as a parameter to the code that requires it. Use the invoke operator (&) to execute the script block.

Example 103. A script that applies a script block to each element in the pipeline

Problem

You have commands in your script that you want to call multiple times, or a section of your script that you consider to be a “helper” for the main purpose of your script.

Solution

Place this common code in a function, and then call that function instead. For example, this Celsius conversion code in a script:

param([double] $fahrenheit)

## Convert it to Celsius $celsius = $fahrenheit 32 $celsius = $celsius / 1.8

## Output the answer "$fahrenheit degrees Fahrenheit is $celsius degrees Celsius."

Problem

You want to store your commands in a script, so that you can share them or reuse them later.

Solution

To write a PowerShell script, create a plaintext file with your editor of choice. Add your PowerShell commands to that script (the same PowerShell commands you use from the interactive shell) and then save it with a .ps1 extension.

Discussion

Example 94 shows how to easily send email messages from your scripts.

In addition to the fields shown in the script, the System.Net.Mail.MailMessage class supports properties that let you add attachments, set message priority, and much more.

Example 94. SendMailMessage.ps1