Parameters
Most cmdlets accept parameters. Parameters have names preceded
by a dash and are not case sensitive. For example, the
-Identity parameter of the
Get-ADGroupMember cmdlet specifies the group that
you want to enumerate. The -Identity parameter is
used by most Active Directory cmdlets to reference a specific object.
The value of the parameter can be a distinguished name or a
sAMAccountName (Pre-Windows 2000 Logon Name), as
in the following examples:
Get-ADGroupMember -Identity "cn=Sales,ou=Groups,dc=contoso,dc=com"
Get-ADGroupMember -Identity Sales
You can also use an object name, a Globally Unique Identifier
(GUID), or a Security Identifier (SID) to reference an object. Some
parameters accept values without specifying the parameter name. The
-Identity parameter of the
Get-ADGroupMember cmdlet is one such parameter.
The parameter name is optional. Therefore, the following command is
also valid:
Get-ADGroupMember Sales
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:
-
-Examples Shows usage examples of the cmdlet.
-
-Detailed Shows detailed information about the cmdlet and
each of its parameters, as well as examples.
-
-Full Shows all documentation of the cmdlet.
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.
Note
SHORTCUT TAKEN
In the previous example, it is assumed that every member of
the Sales group is a user. If the Sales group contained another
group as a nested member, the command shown in the previous example
would fail because the Set-ADUser cmdlet cannot
operate on a group object piped to it. You could address this
scenario by piping the output of
Get-ADGroupMember to the
Where-Object cmdlet, which can filter the
pipeline to pipe only user objects to the
Set-ADUser cmdlet.
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.
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.
