Positional parameters

PowerShell’s designers knew that some parameters would be used so frequently that you wouldn’t want to continually type the parameter names. Those commonly used parameters are often positional, meaning that you can provide a value without typing the parameter’s name, provided you put that value in the correct position.

There are two ways to identify positional parameters: via the syntax summary or through the full help.

FINDINGPOSITIONALPARAMETERSINTHESYNTAXSUMMARY

You’ll find the first way in the syntax summary: the parameter name—only the name—will be surrounded by square brackets. For example, look at the first two parameters in the second parameter set of Get-EventLog:

[-LogName] <string> [[-InstanceId] <Int64[]>]

The first parameter, -LogName, isn’t optional. We can tell because the entire parameter—its name and its value—aren’t surrounded by square brackets. But the parameter name is enclosed in square brackets, making it a positional parameter—we could provide the log name without having to type -LogName. And because this param- eter appears in the first position within the help file, we know that the log name is the first parameter we have to provide.

The second parameter, -InstanceId, is optional—both it and its value are enclosed in square brackets. Within those, -InstanceId itself is also contained in square brackets, indicating that this is also a positional parameter. It appears in the second position, so we would need to provide a value in the second position if we chose to omit the parameter name.

The -Before parameter (which comes later in the syntax; run Help Get-EventLog and find it for yourself) is optional, because it’s entirely enclosed within square brack- ets. The -Before name isn’t in square brackets, which tells us that if we choose to use that parameter, we must type the parameter name (or at least a portion of it).

There are some tricks to using positional parameters:

 It’s OK to mix and match positional parameters with those that require their names. Positional parameters must always be in the correct positions. For exam- ple, Get-EventLog System -Newest 20 is legal; System will be fed to the -LogName

parameter, because that value is in the first position; 20 will go with the -Newest parameter because the parameter name was used.

 It’s always legal to specify parameter names, and when you do so, the order in which you type them isn’t important. Get-EventLog -newest 20 -Log Application is legal because we’ve used parameter names (in the case of -LogName, we abbreviated it).

 If you use multiple positional parameters, don’t lose track of their positions. Get-EventLog Application 0 will work, with Application being attached to -LogName and 0 being attached to -InstanceId. Get-EventLog 0 Application won’t work, because 0 will be attached to -LogName, and no log is named 0. We’ll offer a best practice: use parameter names until you become comfortable with a particular cmdlet and get tired of typing a commonly used parameter name over and over. After that, use positional parameters to save yourself typing. When the time comes to paste a command into a text file for easier reuse, always use the full cmdlet name and type out the complete parameter name—no positional parameters and no abbreviated parameter names. Doing so makes that file easier to read and understand in the future, and because you won’t have to type the parameter names repeatedly (that’s why you pasted the command into a file, after all), you won’t be creating extra typing work for yourself.

FINDINGPOSITIONALPARAMETERSINTHEFULLHELP

We said there were two ways to locate positional parameters. The second requires that you open the help file using the -full parameter of the Help command.

TRY IT NOW Run Help Get-EventLog -full. Remember to use the spacebar to view the help file one page at a time, and to press Ctrl-C if you want to stop viewing the file before reaching the end. For now, page through the entire file, which lets you scroll back and review it all.

Page down until you see the help entry for the -LogName parameter. It should look something like the following:

-LogName <string>

Specifies the event log. Enter the log name (the value of th e Log property; not the LogDisplayName) of one event log. Wil dcard characters are not permitted. This parameter is require d.

Required? true Position? 1 Default value

Accept pipeline input? false Accept wildcard characters? False

In the preceding example, you can see that this is a mandatory parameter—it’s listed as required. Further, it’s a positional parameter, and it occurs in the first position, right after the cmdlet name.

We always encourage students to focus on reading the full help when they’re get- ting started with a cmdlet, rather than only the abbreviated syntax reminder. Reading the help reveals more details, including that description of the parameter’s use. You can also see that this parameter doesn’t accept wildcards, which means you can’t pro- vide a value like App*—you need to type out the full log name, such as Application. 3.5.4 Parameter values

The help files also give you clues about what kind of input each parameter accepts. Some parameters, referred to as switches, don’t require any input value at all. In the abbreviated syntax, they look like the following:

[-AsString]

And in the full syntax, they look like this:

-AsString [<SwitchParameter>]

Returns the output as strings, instead of objects. Required? false

Position? named Default value

Accept pipeline input? false Accept wildcard characters? False

The [<SwitchParameter>] part confirms that this is a switch, and that it doesn’t expect an input value. Switches are never positional; you always have to type the parameter name (or at least an abbreviated version of it). Switches are always optional, which gives you the choice to use them or not.

Other parameters expect some kind of input value, which will always follow the parameter name and be separated from the parameter name by a space (and not by a colon, equal sign, or any other character). In the abbreviated syntax, the type of input expected is shown in angle brackets, like < >:

[-LogName] <string>

It’s shown the same way in the full syntax:

-Message <string>

Gets events that have the specified string in their messages. You can use this property to search for messages that contai n certain words or phrases. Wildcards are permitted.

Required? false Position? named Default value

Accept pipeline input? false Accept wildcard characters? True

Let’s look at some common types of input:

 String—A series of letters and numbers. These can sometimes include spaces, but when they do, the entire string must be contained within quotation marks.

For example, a string value like C:\Windows doesn’t need to be enclosed in quotes, but C:\Program Files does, because it has that space in the middle. For now, you can use single or double quotation marks interchangeably, but it’s best to stick with single quotes.

 Int, Int32, or Int64—An integer number (a whole number with no decimal portion).

 DateTime—Generally, a string that can be interpreted as a date based on your computer’s regional settings. In the United States, that’s usually something like 10-10-2010, with the month, day, and year.

We’ll discuss other, more specialized types as we come to them. You’ll also notice some values that have more square brackets:

[-ComputerName <string[]>]

The side-by-side brackets after string don’t indicate that something is optional. Instead, string[] indicates that the parameter can accept an array, a collection, or a list of strings. In these cases, it’s always legal to provide a single value:

Get-EventLog Security -computer Server-R2

But it’s also legal to specify multiple values. A simple way to do so is to provide a comma-separated list. PowerShell treats all comma-separated lists as arrays of values:

Get-EventLog Security -computer Server-R2,DC4,Files02

Once again, any individual value that contains a space must be enclosed in quotation marks. But the entire list doesn’t get enclosed in quotation marks—it’s important that only individual values be in quotes. The following is legal:

Get-EventLog Security -computer 'Server-R2','Files02'

Even though neither of those values needs to be in quotation marks, it’s okay to use the quotes if you want to. But the following is wrong:

Get-EventLog Security -computer 'Server-R2,Files01'

In this case, the cmdlet will be looking for a single computer named Server-R2,Files01, which is probably not what you want.

Another way to provide a list of values is to type them into a text file, with one value per line. Here’s an example:

Server-R2 Files02 Files03 DC04 DC03

Next, you can use the Get-Content cmdlet to read the contents of that file, and send those contents into the -computerName parameter. You do this by forcing the shell to execute the Get-Content command first, so that the results get fed to the parameter.

Remember in high school math how parentheses, like ( ), could be used to specify the order of operations in a mathematical expression? The same thing works in PowerShell: by enclosing a command in parentheses, you force that command to exe- cute first:

Get-EventLog Application -computer (Get-Content names.txt)

The previous example shows a useful trick. We have text files with the names of differ- ent classes of computers—web servers, domain controllers, database servers, and so forth—and then we use this trick to run commands against entire sets of computers.

You can also feed a list of values to a parameter in a few other ways, including read- ing computer names from Active Directory. Those techniques are a bit more complex, though, so we’ll get to them in later chapters, after you learn some of the cmdlets you’ll need to make the trick work.

Another way you can specify multiple values for a parameter (provided it’s a man- datory parameter), is to not specify the parameter at all. As with all mandatory param- eters, PowerShell will prompt you for the parameter value. For parameters that accept multiple values, you can type the first value and press Return. PowerShell will then prompt for a second value, which you can type and finish by hitting Return. Keep doing that until you’re finished, and press Return on a blank prompt to let Power- Shell know you’re finished. As always, you can press Ctrl-C to abort the command if you don’t want to be prompted for entries.