Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Supporting Wildcard Characters in Cmdlet Parameters

 

Often, you will have to design a cmdlet to run against a group of resources rather than against a single resource. For example, a cmdlet might need to locate all the files in a data store that have the same name or extension. You must provide support for wildcard characters when you design a cmdlet that will be run against a group of resources.

System_CAPS_noteNote

Using wildcard characters is sometimes referred to as globbing.

Many Windows PowerShell cmdlets support wildcard characters for their parameter values. For example, almost every cmdlet that has a Name or Path parameter supports wildcard characters for these parameters. (Although most cmdlets that have a Path parameter also have a LiteralPath parameter that does not support wildcard characters.) The following command shows how a wildcard character is used to return all the cmdlets in the current session whose name contains the Get verb.

PS>get-command get-*

Windows PowerShell supports the following wildcard characters.

Wildcard character

Description

Example

Matches

Does not match

*

Matches zero or more characters, starting at the specified position

a*

A, ag, Apple

?

Matches any character at the specified position

?n

An, in, on

ran

[ ]

Matches a range of characters

[a-l]ook

book, cook, look

took

[ ]

Matches the specified characters

[bc]ook

book, cook

look

When you design cmdlets that support wildcard characters, allow for combinations of wildcard characters. For example, the following command uses the Get-ChildItem cmdlet to retrieve all the .txt files that are in the c:\Techdocs folder and that begin with the letters "a" through "l."

get-childitem c:\techdocs\[a-l]*.txt

The previous command uses the range wildcard [a-l] to specify that the file name should begin with the characters "a" through "l." The command then uses the * wildcard character as a placeholder for any characters between the first letter of the file name and the .txt extension.

The following example uses a range wildcard pattern that excludes the letter "d" but includes all the other letters from "a" through "f."

get-childitem c:\techdocs\[a-cef]*.txt

If the wildcard pattern you specify contains literal characters, use the backtick character (`) as an escape character. When you specify literal characters programmatically, use a single backtick. When you specify literal characters at the command prompt, use two backticks. For example, the following pattern contains two brackets that must be taken literally.

"John Smith `[*`]" (specified programmatically)

"John Smith ``[*``]" (specified at the command prompt)

This pattern matches "John Smith [Marketing]" or "John Smith [Development]".

When cmdlet parameters support wildcard characters, a cmdlet operation usually generates an array output. Occasionally, it makes no sense to support an array output because the user might use only a single item at a time. For example, the Set-Location cmdlet does support an array output because the user sets only a single location. In this instance, the cmdlet still supports wildcard characters, but it forces resolution to a single location.

Show: