Commands and cmdlets

Commands are the fundamental part of any shell language; they’re what you type to get things done. As you saw in the previous chapter, a simple command looks like this:

command –parameter1 –parameter2 argument1 argument2

A more detailed illustration of the anatomy of this command is shown in figure 2.2.

This figure calls out all the individual elements of the command.

THECORECONCEPTS 39 All commands are broken down into the command name, the parameters specified to the command, and the arguments to those parameters.

NOTE The distinction between parameter and argument may seem a bit strange from a programmer’s perspective. But if you’re used to lan-guages such as Python and Visual Basic that allow for keyword param-eters, PowerShell parameters correspond to the keywords, and arguments correspond to the values.

The first element in the command is the name of the command to be executed. The PowerShell interpreter looks at this name and determines what has to be done. It must figure out not only which command to run but which kind of command to run.

In PowerShell, there are four categories of commands: cmdlets, shell function com-mands, script comcom-mands, and native Windows commands. (We’ll cover the different categories in detail in the following sections.) Following the command name come zero or more parameters and/or arguments. A parameter starts with a dash, followed by the name of the parameter. An argument, on the other hand, is the value that will be associated with, or bound to, a specific parameter. Let’s look at an example:

PS (1) > Write-Output -InputObject Hello Hello

In this example, the command is Write-Output, the parameter is -InputObject, and the argument is ^Hello.

What about the positional parameters mentioned in figure 2.1? When a Power-Shell command is created, the author of that command specifies information that allows PowerShell to determine which parameter to bind an argument to, even if the parameter name itself is missing. For example, the Write-Output command has been defined so that the first parameter is -InputObject. This lets you write

PS (2) > Write-Output Hello Hello

instead of having to specify -InputObject. The piece of the PowerShell interpreter that figures all of this out is called the parameter binder. The parameter binder is

command -parameter1 -parameter2 arg1 arg2 Command

name Parameter with

argument

Switch parameter Positional argument

Figure 2.2 The anatomy of a basic command. It begins with the name of the command, followed by some num-ber of parameters. These may be switch parameters that take no arguments, regular parameters that do take argu-ments, or positional parameters, where the matching parameter is inferred by the argument’s position on the command line.

smart—it doesn’t require that you specify the full name of a parameter as long as you specify enough for it to uniquely distinguish what you mean. This means you can write any of the following

PS (3) > Write-Output -input Hello Hello

PS (4) > Write-Output -IN Hello Hello

PS (5) > Write-Output -i Hello Hello

and the parameter binder still does the right thing. (Notice that it doesn’t matter whether you use uppercase or lowercase letters either.)

What else does the parameter binder do? It’s in charge of determining how to match the types of arguments to the types of parameters. Remember that PowerShell is an object-based shell. Everything in PowerShell has a type. For this to work seam-lessly, PowerShell has to use a fairly complex type-conversion system to correctly put things together, a subject that’s covered in chapter 3. When you type a command at the command line, you’re really typing strings. What happens if the command requires a different type of object? The parameter binder uses the type converter to try to convert that string into the correct type for the parameter.

Here’s a simple example. Let’s use the Get-Process command to get the process with the process ID 0. Instead of passing it the number 0, put the argument in quotes to force the argument to be a string. This means that the ^-id parameter, which requires a number, will be passed a string instead:

PS (7) > Get-Process -Id "0"

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName --- --- --- --- --- --- -- 0 0 0 28 0 0 Idle

When you attempt to run this command, the parameter binder detects that ^-id needs a number, not a string, so it takes the string “0” and tries to convert it into a number. If this succeeds, the command continues, as you see in the example. What happens if it can’t be converted? Let’s try it:

PS (8) > Get-Process -Id abc

Get-Process : Cannot bind parameter 'Id'. Cannot convert value "abc"

to type "System.Int32". Error: "Input string was not in a correct format."

At line:1 char:16

+ Get-Process -Id <<<< abc PS (9) >

You get an error message explaining that the type conversion failed. We’ll discuss this in more detail in chapter 3 when we talk about types. Because we’ve introduced the use of quotation marks, let’s see one more example. What happens if the argument

THECORECONCEPTS 41 you want to pass to the command starts with a dash? This is where the quotes come in. Let’s use Write-Output to print out the string “-InputObject”:

PS (1) > Write-Output -InputObject "-InputObject"

-InputObject

And it works as desired. Alternatively, you could type this:

PS (2) > Write-Output "-InputObject"

-InputObject

The quotes keep the parameter binder from treating the quoted string as a parameter.

Another, less frequently used way of doing this is by using the special “end-of-parameters” parameter, which is two hyphens back to back (^--). Everything after this sequence will be treated as an argument, even if it looks like a parameter. For exam-ple, using ^-- you can also write out the string -InputObject without using quotes:

PS (3) > Write-Output -- -InputObject -InputObject

The -- sequence tells the parameter binder to treat everything after it as an argument, even if it looks like a parameter. This is a convention adopted from the UNIX shells and is standardized in the POSIX Shell and Utilities specification.

The final element of the basic command pattern is the switch parameter. These are parameters that don’t require an argument. They’re usually either present or absent (so obviously they can’t be positional). A good example of this is the ^-Recurse parameter on the dir command. This switch tells the dir command to display files from a specified directory as well as all its subdirectories:

PS (1) > dir -Recurse -Filter c*d.exe c:\windows

Directory: Microsoft.PowerShell.Core\FileSystem::C:\windows\

system32

Mode LastWriteTime Length Name - --

---a--- 8/10/2004 12:00 PM 102912 clipbrd.exe -a--- 8/10/2004 12:00 PM 388608 cmd.exe

PS (2) >

As you can see, the -Recurse switch takes no arguments.

NOTE Although it’s almost always the case that switch parameters don’t take arguments, it’s possible to specify arguments to them. We’ll save discussion of when and why you might do this for section 7.2.6, which focuses on scripts (shell functions and scripts are the only time you need this particular feature, so we’ll keep you in suspense for the time being).

Now that we’ve covered the basic anatomy of the command line, let’s go over the types of commands that PowerShell supports.