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: