Select-String

 

Additional Resources for Select-String

Checking for the Existence of a String Value http://www.microsoft.com/technet/scriptcenter/topics/msh/cmdlets/select-string.mspx

 

SYNOPSIS

Identifies patterns in strings.

 

SYNTAX

Select-String [-pattern] <string[]> -inputObject <psobject> [-include <string[]>] [-exclude <string[]>] [-simpleMatch] [-caseSensitive] [-quiet] [-list] [<CommonParameters>]

 

Select-String [-pattern] <string[]> [-path] <string[]> [-include <string[]>] [-exclude <string[]>] [-simpleMatch] [-caseSensitive] [-quiet] [-list] [<CommonParameters>]

 

DETAILED DESCRIPTION

Identifies patterns in strings. By default, Select-String interprets the value of the Pattern parameter as a regular expression and matches input against it. To learn more about regular expressions in Windows PowerShell, type get-help about_regular_expression. You can suppress the regular expression match by using the SimpleMatch parameter. A simple match attempts to find the string specified in the Pattern parameter as a substring of the input.

 

The cmdlet makes it easy to search string content from files. It includes a Path parameter that supports wildcards and when that parameter is used, the contents of the referenced files are retrieved and matched against the value of the Pattern parameter.

 

Output from the cmdlet is, by default, a MatchInfo object which includes detailed information about the matches. The information is most useful when the input to the cmdlet is retrieved from files. The object includes properties like Filename and Line, which have the value 'InputStream' when the input was not from a file. You can use the Quiet parameter to suppress the output of MatchInfo objects. In that case, the resulting output becomes a boolean value that is true if a match occurred and false otherwise.

 

When matching file content, you can use the List parameter to stop after the first match in each input file. You should use this parameter if you only require a single match, because it will result in faster matching commands.

 

PARAMETERS

 

-pattern <string[]>

Specifies the string or regular expression that represents the matching criteria. To learn about regular expressions in Windows PowerShell, type get-help about_regular_expression at the Windows PowerShell command prompt.

 

Required?	true
Position?	1
Default value	Null
Accept pipeline input?	false
Accept wildcard characters?	true

 

-path <string[]>

Specifies strings or files to match against. Wildcard syntax is allowed.

 

Required?	true
Position?	2
Default value	null
Accept pipeline input?	true (ByPropertyName)
Accept wildcard characters?	true

 

-include <string[]>

Include only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	true

 

-exclude <string[]>

Exclude the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	true

 

-simpleMatch <SwitchParameter>

Specifies that a simple match, rather than a regular expression match, should be used.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-caseSensitive <SwitchParameter>

Makes matches case sensitive. By default, matching is not case sensitive.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-quiet <SwitchParameter>

Suppresses most of the output from the cmdlet. When specified, only a boolean value is passed along the pipeline. The value is true if a match was found and false otherwise.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-list <SwitchParameter>

Specifies that only one match should result for each input file. The returned MatchInfo objects only include information about that first match.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-inputObject <psobject>

Accepts an object as input to the cmdlet. Enter a variable that contains the objects or type a command or expression that gets the objects.

 

Required?	true
Position?	named
Default value	AutomationNull.Value
Accept pipeline input?	true (ByValue)
Accept wildcard characters?	false

 

-text <string[]>

Specifies literal text to match against the string or regular expression value of the Pattern parameter.

 

Required?	true
Position?	2
Default value	Null
Accept pipeline input?	false
Accept wildcard characters?	false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

Objects or files.

 

RETURN TYPE

If the Quiet parameter is specified, a boolean value indicating whether the pattern was found.

 

Otherwise, the output will be a set of MatchInfo objects, each of which have the following properties:

 

·          IgnoreCase: Boolean

·          LineNumber: integer (0 if input is not from a file)

·          Line: string

·          Filename: string ("InputStream" if input is not from a file)

·          Path: string ("InputStream" if input is not from a file)

·          Pattern: the string that was actually matched

·          OriginalObject: object that was processed

 

NOTES

 

Select-String is like the Unix tool 'grep' and the Windows tool 'findstr'.

 

Select-String makes comparisons by using the current culture setting on the current thread. You can determine the current culture setting by using the Get-Culturecmdlet.

 

To see all the properties of a MatchInfo object, type: select-string -path test.txt -pattern "test" | get-member | format-list -property *.

 

EXAMPLE 1

 

 

This command performs a case sensitive matching of the literal strings "Hello" and "HELLO" against the pattern "HELLO".

 

 

EXAMPLE 2

 

 

This command searches through all files with the .xml file extension in the current directory and displays the lines in those files that include the string "the the".

 

EXAMPLE 3

 

 

This command retrieves the last 100 events from the application event log and stores them in the $events variable. It pipes that variable to Select-String and specifies a script block as the value of the InputObject parameter. The script block refers to each pipelined object by using $_ and retrieves the message property of each EventLogEntry object. All the message strings are passed to Select-String as input and are matched against the string "failed". Any matches are displayed on the console.

 

EXAMPLE 4

 

 

This command examines all files in the subdirectories of C:\Windows\System32 with the .txt file extension, for the string "Microsoft". The CaseSensitive parameter indicates that the 'M' in 'Microsoft' must be capitalized and the rest of the characters must be lowercase for a match to occur.

 

RELATED LINKS

about_comparison_operators

about_regular_expression