Administering with Windows PowerShell and Active Directory Administrative Center (part 2)

When you find a cmdlet that appears to support a task you want to perform, you can expose the documentation for the cmdlet using the Get-Help cmdlet. The simplest form of help is provided by typing the Get-Help cmdlet followed by the cmdlet name you want help with. For example:

Get-Help Get-ADGroupMember

Without a parameter, the Get-Help cmdlet shows a synopsis, a more detailed description, and the syntax of the cmdlet. The following optional parameters of Get-Help produce various types and levels of detail:

For example, to get help, including examples, about the Get-ADGroupMember cmdlet, which lists—or enumerates—the members of a group, type the following:

Get-Help Get-ADGroupMember -detailed

The Windows PowerShell Get-Help cmdlet is the best place to start looking for information about cmdlets, especially when you are just getting started with Windows PowerShell. Windows PowerShell cmdlets are well documented with a standard documentation format, and the Get-Help cmdlet, with the -Examples, -Detailed, and -Full parameters, exposes that documentation.

Unlike Command Prompt, in which commands return text that then must be parsed and processed as text, Windows PowerShell returns objects—representations of the resource itself.

An object is a programming construct. From a technical perspective, a .NET object is an instance of a .NET class that consists of data and the operations associated with that data. Think of an object as a virtual representation of a resource of some kind. For example, the Get-ADUser cmdlet returns an object representing a user. The following command returns an object representing the user with the sAMAccountName mike.fitz:

Get-ADUser -Identity mike.fitz

When you run this command, the console displays several properties of the user. But it is important to note that the cmdlet itself returns more than text: It returns an object representing the user. You can then manipulate the user by examining or setting its attributes or performing actions such as disabling the account.

Objects can have properties—also called attributes—that represent data maintained by the resource. An object representing a user, for example, has properties for the user’s first and last name. When you get a property, you are retrieving the data of the resource. When you set a property, you are writing that data to the resource.

Objects also have methods, which are actions that you can perform on the object. When you perform a method on the object that represents the resource, you perform the action on the resource itself.

In the examples thus far, you have not yet done anything with the objects other than showing default properties. However, objects returned by a cmdlet can be stored in variables for later use. A variable is a named memory location that stores a value or object, and returns the value when needed. In Windows PowerShell, variable names are preceded by a dollar sign ($). The variable name itself is not case sensitive.

To assign a variable—that is, to create and define a variable—simply use the following syntax:

$variable = value

For example, the following command assigns the object retrieved by the Get-ADUser cmdlet to a variable named $user:

$user = Get-ADUser mike.fitz

A variable created from the Command Prompt persists during the Windows PowerShell session—that is, until you close the Windows PowerShell console. You can then use the variable as a parameter for another cmdlet. For example, the Set-ADUser cmdlet sets the value of a subset of the most common user attributes. You can use Set-ADUser to disable the user account represented by the variable $user by typing the following command:

Set-ADUser -Identity $user -Enabled $false

The -identity parameter name is optional. The value of the parameter, as mentioned earlier, can be a distinguished name, a SAM account name, an object name, a GUID, or a SID. The identity can also be provided as a user object—in this example, the user object stored in the variable $user.

Windows PowerShell has built-in variables, including the following:

In the example earlier, the value of the -Enabled parameter is set to the Boolean value false by using the built-in variable $false.

You can also pipe the object or objects returned by one cmdlet as input to a subsequent cmdlet. Windows PowerShell features a pipeline: a channel through which the output of a cmdlet can be passed to the following cmdlet on the same command line. The pipeline is represented by the pipe character (|).

For example, type the following to disable the account for Mike Fitzmaurice:

Get-ADUser mike.fitz | Set-ADUser -Enabled $false

The Get-ADUser cmdlet gets an object representing the user and passes the object down the pipeline to the Set-ADUser cmdlet, which sets the value of the enabled flag to the logical value false.

The concept illustrated in this simple example is an important one. When working in Windows PowerShell, you will often get one or more objects, pass the objects down the pipeline, and do something to them. In this example, we created an object reference to one user, then passed that object to a cmdlet that disabled the user account. The next command in the pipeline could just as easily be the Add-ADGroupMember cmdlet to add the user to a group, or the Remove-ADUser cmdlet to delete the user account.

In addition, when a cmdlet returns more than one object (known as a collection of objects) and passes the collection down the pipeline, a subsequent cmdlet can operate on each of the objects it receives. For example, the Get-ADGroupMember cmdlet returns a collection of objects representing group members. To disable the accounts of all users in the Sales group, type the following command:

Get-ADGroupMember -Identity Sales | Set-ADUser -Enabled $false

The collection of users returned by the Get-ADGroupMember cmdlet is piped to the Set-ADUser cmdlet. The Set-ADUser cmdlet operates on each object that is passed to it, disabling each user.

Extend the Pipeline to More than One Line

A Windows PowerShell task may involve multiple cmdlets, parameters, and expressions. More complicated tasks may create a long pipeline with structures including functions, iterative loops, and conditional statements. Often, the pipeline is extended to more than one line to improve readability. There are several ways to enter one line of a pipeline and then continue the pipeline on a subsequent line:

• The tick mark (`) When a tick mark is the last character of a line, it serves as a line break and line continuation marker. Windows PowerShell assumes that the subsequent line is a continuation of the current line. The following two-line command uses a tick mark to break the line for readability:

  Get-ADGroupMember -Identity Sales | `
  Set-ADUser -Enabled $false

• The pipe symbol (|) When the pipe symbol is the last character of a line, it, too, serves to indicate that the command is not complete, so Windows PowerShell continues the command with the subsequent line, as in the following example:

  Get-ADGroupMember -Identity Sales |
  Set-ADUser -Enabled $false

• Curly braces ({}) Curly braces enclose a structure such as an expression or a procedure—a script block, for example. A left curly brace marks the beginning of a structure. The pipeline continues on one or more lines until the right curly brace is found, marking the end of the structure.

When you type a line in the Windows PowerShell console and the line ends with a tick mark or a pipe symbol, or the line contains a left curly brace that is not closed with a right curly brace, the console prompt becomes a double right chevron, shown in Figure 2. This prompt is a visual indication that the command is being continued. To indicate that the command is complete, you must enter a blank line at the prompt, as shown in Figure 2. When Windows PowerShell receives the blank line, it executes the multi-line command.

Figure 2. A multi-line command

Windows PowerShell allows a cmdlet to have aliases, which are alternate names for the cmdlet. For example, gsv is an alias for Get-Service, a cmdlet that returns a collection of services on a system. The Get-Alias cmdlet lists aliases. Without a parameter, Get-Alias lists all aliases in the current Windows PowerShell session. To list aliases for a specific cmdlet, type the following command:

Get-Alias -Definition cmdlet

where cmdlet is the cmdlet for which you want to list aliases.

If you see a cmdlet that does not follow the Verb-Noun syntax, the cmdlet is using an alias. Sometimes it can be difficult to interpret what a command is doing when an alias is used. To list the cmdlet associated with a specific alias, type the following command:

Get-Alias Alias

where Alias is the alias you want to define.

Windows PowerShell aliases enable you to use common Command Prompt (Cmd.exe) and UNIX commands. For example, dir and ls list the objects in a directory; they are aliases for the Get-ChildItem cmdlet. You can clear the Windows PowerShell console screen with the Clear-Host cmdlet, or you can use the alias cls. Windows PowerShell provides aliases for command-shell commands, however Windows PowerShell cmdlets do not take the same parameters as Cmd.exe commands. For example, to retrieve a directory of folders and all subfolders in Command Prompt, type dir /s. In Windows PowerShell, type dir -recurse.