Select-String

Localiza texto em cadeias de caracteres e arquivos.

Sintaxe

Select-String [-Path] <string[]> [-Pattern] <string[]> [-AllMatches] [-CaseSensitive] [-Context <Int32[]>] [-Encoding <string>] [-Exclude <string[]>] [-Include <string[]>] [-List] [-NotMatch] [-Quiet] [-SimpleMatch] [<CommonParameters>]

Select-String -InputObject <psobject> [-Pattern] <string[]> [-AllMatches] [-CaseSensitive] [-Context <Int32[]>] [-Encoding <string>] [-Exclude <string[]>] [-Include <string[]>] [-List] [-NotMatch] [-Quiet] [-SimpleMatch] [<CommonParameters>]

Descrição

O cmdlet Select-String pesquisa texto e padrões de texto em cadeias de caracteres e arquivos de entrada. É possível usá-lo como Grep no UNIX e Findstr no Windows.

Select-String é baseado em linhas de texto. Por padrão, Select-String localiza a primeira correspondência em cada linha e, para cada correspondência, exibe o nome do arquivo, o número da linha e todo o texto da linha que contém a correspondência.

Porém, você pode direcioná-lo para detectar várias correspondências por linha, exibir texto antes e depois da correspondência ou exibir apenas um valor Booleano (verdadeiro ou falso) que indique se uma correspondência foi localizada.

Select-String usa correspondência de expressão regular, mas também pode executar uma correspondência simples que pesquisa a entrada do texto especificado.

O Select-String pode exibir todas as correspondências de texto ou parar depois da primeira correspondência em cada arquivo de entrada. Ele também pode exibir todo o texto que não corresponde ao padrão especificado.

Você também pode especificar que Select-String espere uma codificação de caractere específica, como ao pesquisar arquivos de texto em Unicode.

Parâmetros

-AllMatches

Pesquisa mais de uma correspondência em cada linha de texto. Sem esse parâmetro, Select-String localiza apenas a primeira correspondência em cada linha de texto.

Quando o Select-String localiza mais de uma correspondência em uma linha de texto, ele ainda emite apenas um objeto MatchInfo para a linha, mas a propriedade Matches do objeto contém todas as correspondências.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CaseSensitive

Faz com que as correspondências diferenciem maiúsculas de minúsculas. Por padrão, as correspondências não diferenciam maiúsculas de minúsculas.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Context <Int32[]>

Captura o número especificado de linhas antes e depois da linha com a correspondência. Isso permite exibir a correspondência em contexto.

Se você digitar um número como o valor desse parâmetro, esse número determinará o número de linhas capturadas antes e depois da correspondência. Se você digitar dois números como o valor, o primeiro número determinará o número de linhas antes da correspondência a o segundo número determinará o número de linhas após a correspondência.

Na exibição padrão, as linhas com uma correspondência são indicadas por um colchete de ângulo reto (ASCII 62) na primeira coluna da exibição. Linhas desmarcadas são o contexto.

Esse parâmetro não altera o número de objetos gerados pelo Select-String. O Select-String gera um objeto MatchInfo (Microsoft.PowerShell.Commands.MatchInfo) para cada correspondência. O contexto é armazenado como uma matriz de cadeias de caracteres na propriedade Context do objeto.

Quando você canaliza a saída de um comando Select-String para outro comando Select-String, o comando receptor pesquisa apenas o texto na linha correspondida (o valor da propriedade Line do objeto MatchInfo), não o texto nas linhas do contexto. Como resultado, o parâmetro Context não é válido no comando Select-String receptor.

Quando o contexto inclui uma correspondência, o objeto MatchInfo de cada correspondência inclui todas as linhas do contexto, mas as linhas sobrepostas só aparecem uma vez na exibição.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Encoding <string>

Especifica a codificação de caracteres que o Select-String deve supor ao pesquisar o arquivo. O padrão é UTF8.

Os valores válidos são "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode", "Default" e "OEM". "Default" é a codificação da página de código ANSI atual do sistema. "OEM" é o identificador da página de código atual do fabricante original do equipamento do sistema operacional.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Exclude <string[]>

Exclui os itens especificados. O valor desse parâmetro qualifica o parâmetro Path. Digite um elemento ou padrão do caminho, como "*.txt". Os caracteres curinga são permitidos.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Include <string[]>

Inclui somente os itens especificados. O valor desse parâmetro qualifica o parâmetro Path. Digite um elemento ou padrão do caminho, como "*.txt". Os caracteres curinga são permitidos.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-InputObject <psobject>

Especifica o texto a ser pesquisado. Insira uma variável que contenha o texto ou digite um comando ou uma expressão que obtenha o texto.

Necessário?	true
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByValue)
Aceitar caracteres curinga?	false

-List

Retorna apenas a primeira correspondência em cada arquivo de entrada. Por padrão, o Select-String retorna um objeto MatchInfo para cada correspondência que localiza.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-NotMatch

Localiza texto que não corresponde ao padrão especificado.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Path <string[]>

Especifica o caminho para os arquivos a serem pesquisados. Os caracteres curinga são permitidos. O local padrão é o diretório local.

Especifique arquivos no diretório, como "log1.txt", "*.doc" ou "*.*". Se você especificar só um diretório, o comando falhará.

Necessário?	true
Posição?	2
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Pattern <string[]>

Especifica o texto a ser localizado. Digite uma cadeia de caracteres ou uma expressão regular. Se você digitar uma cadeia de caracteres, use o parâmetro SimpleMatch.

Para obter informações sobre expressões regulares, consulte about_Regular_Expressions.

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Quiet

Retorna um valor Booleano (verdadeiro ou falso), em vez de um objeto MatchInfo. O valor será "true" se o padrão for localizado. Caso contrário, será "false".

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-SimpleMatch

Usa uma correspondência simples, em vez de uma correspondência de expressão regular. Em uma correspondência simples, o Select-String pesquisa a entrada do texto no parâmetro Pattern. Ele não interpreta o valor do parâmetro Pattern como uma instrução de expressão regular.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas	System.Management.Automation.PSObject Você pode canalizar qualquer objeto que tenha um método ToString para Select-String.
Saídas	Microsoft.PowerShell.Commands.MatchInfo ou System.Boolean Por padrão, a saída é um conjunto de objetos MatchInfo, um para cada correspondência localizada. Se você usar o parâmetro Quiet, a saída será um valor Booleano que indica se o padrão foi localizado.

Observações

Select-String equivale ao comando Grep no UNIX e ao comando FindStr no Windows.

Para usar Select-String, digite o texto que deseja localizar como o valor do parâmetro Pattern.

Para especificar o texto a ser pesquisado, faça o seguinte:

-- Digite o texto em uma cadeia de caracteres entre aspas e canalize-a para Select-String.

-- Armazene uma cadeia de caracteres de texto em uma variável e especifique a variável como o valor do parâmetro InputObject.

-- Se o texto estiver armazenado em arquivos, use o parâmetro Path para especificar o caminho para os arquivos.

Por padrão, o Select-String interpreta o valor do parâmetro Pattern como uma expressão regular. (Para obter mais informações, consulte about_Regular_Expressions.) No entanto, é possível usar o parâmetro SimpleMatch para substituir a expressão regular correspondente. O parâmetro SimpleMatch localiza instâncias do valor do parâmetro Pattern na entrada.

A saída padrão do cmdlet Select-String é um objeto MatchInfo que inclui informações detalhadas sobre as correspondências. As informações contidas no objeto são úteis quando você está pesquisando texto em arquivos, pois os objetos MatchInfo têm propriedades como Filename e Line. Quando a entrada não é do arquivo, o valor desses parâmetros é "InputStream".

Se você não precisar das informações do objeto MatchInfo, use o parâmetro Quiet, o qual retorna um valor Booleano (verdadeiro ou falso) para indicar se ele localizou uma correspondência, em vez de um objeto MatchInfo.

Ao corresponder frases, Select-String usa a cultura atual que está definida para o sistema. Para localizar a cultura atual, use o cmdlet Get-Culture.

Para localizar as propriedades de um objeto MatchInfo, digite o seguinte:

select-string -path test.txt -pattern "test" | Get-Member | Format-List -property *

Exemplo 1

C:\PS>"Hello","HELLO" | select-string -pattern "HELLO" -casesensitive

Descrição
-----------
Esse comando executa uma correspondência com diferenciação de maiúsculas e minúsculas do texto que foi canalizado para o comando Select-String. 

Como resultado, o Select-String só localiza "HELLO", porque "HELLO" não corresponde.

Como cada uma das cadeias de caracteres entre aspas é tratada como uma linha, sem o parâmetro CaseSensitive, Select-String reconhece as duas cadeias de caracteres como correspondências.

Exemplo 2

C:\PS>select-string -path *.xml -pattern "the the"

Descrição
-----------
Esse comando pesquisa em todos os arquivos com a extensão de nome de arquivo .xml no diretório atual e exibe as linhas desses arquivos que incluem a cadeia de caracteres "the the".

Exemplo 3

C:\PS>select-string -path $pshome\en-US\*.txt -pattern "@"

Descrição
-----------
Esse comando pesquisa os arquivos da Ajuda conceitual do Windows PowerShell (about_*.txt) para obter informações sobre o uso do sinal (@). 

Para indicar o caminho, esse comando usa o valor da variável automática $pshome que armazena o caminho para o diretório de instalação do Windows PowerShell. Neste exemplo, o comando pesquisa o subdiretório en_US, que contém os arquivos da Ajuda do idioma inglês (EUA) do Windows PowerShell.

Exemplo 4

C:\PS>function search-help
{
    $pshelp = "$pshome\es\about_*.txt", "$pshome\en-US\*dll-help.xml"
    select-string -path $pshelp -pattern $args[0]
}

Descrição
-----------
Essa função simples usa o cmdlet Select-String para pesquisar os arquivos da Ajuda do Windows PowerShell por uma cadeia de caracteres específica. Neste exemplo, a função pesquisa o subdiretório "en-US" dos arquivos do idioma inglês (EUA).

Para usar a função para localizar uma cadeia de caracteres, como "psdrive", digite "search-help psdrive".

Para usar essa função em qualquer console do Windows PowerShell, altere o caminho para apontar para os arquivos da Ajuda do Windows PowerShell do sistema e cole a função em seu perfil do Windows PowerShell.

Exemplo 5

C:\PS>$events = get-eventlog -logname application -newest 100

C:\PS> $events | select-string -inputobject {$_.message} -pattern "failed"

Descrição
-----------
Esse exemplo pesquisa a cadeia de caracteres "failed" nos 100 eventos mais recentes no log Aplicativo do Visualizador de Eventos.

O primeiro comando usa o cmdlet Get-EventLog para obter os 100 eventos mais recentes do log de eventos do Aplicativo. Em seguida, ele armazena os eventos na variável $events. 

O segundo comando usa um operador de pipeline (|) para enviar os eventos na variável $events para o Select-String. Ele usa o parâmetro InputObject para representar a entrada da variável $events. O valor do parâmetro InputObject é a propriedade Message de cada objeto enquanto ele é transmitido pelo pipeline. O objeto atual é representado pelo símbolo $_.

À medida que cada evento chega no pipeline, o Select-String pesquisa o valor de sua propriedade Message para a cadeia de caracteres "failed" e exibe todas as linhas que incluem uma correspondência.

Exemplo 6

C:\PS>get-childitem c:\windows\system32\* -include *.txt -recurse |
select-string -pattern "Microsoft" -casesensitive

Descrição
-----------
Esse comando examina todos os arquivos nos subdiretórios de C:\Windows\System32 com a extensão de nome de arquivo .txt e pesquisa a cadeia de caracteres "Microsoft". O parâmetro CaseSensitive indica que o "M" de "Microsoft" deve estar em letra maiúscula e o restante dos caracteres deve estar em letras minúsculas para que Select-String localize uma correspondência.

Exemplo 7

C:\PS>select-string -path process.txt -pattern idle, svchost -notmatch

Descrição
-----------
Esse comando localiza linhas de texto no arquivo Process.txt que não incluem as palavras "idle" ou "svchost".

Exemplo 8

C:\PS>$f = select-string -path audit.log -pattern "logon failed" -context 2, 3

C:\PS> $f.count

C:\PS> ($f)[0].context | format-list

Descrição
-----------
O primeiro comando pesquisa a frase "logon failed" no arquivo Audit.Log. Ele usa o parâmetro Context para capturar duas linhas antes da correspondência e três linhas depois da correspondência. 

O segundo comando usa a propriedade Count de matrizes de objetos para exibir o número de correspondências localizado; nesse caso, duas. 

O terceiro comando exibe as linhas armazenadas na propriedade Context do primeiro objeto MatchInfo. Ele usa notação de matriz para indicar a primeira correspondência (correspondência 0 em uma matriz baseada em 0) e usa o cmdlet Format-List para exibir o valor da propriedade Context como uma lista.

A saída consiste em dois objetos MatchInfo, um para cada correspondência detectada. As linhas do contexto são armazenadas na propriedade Context do objeto MatchInfo.

Exemplo 9

C:\PS>$a = get-childitem $pshome\en-us\about*.help.txt | select-string -pattern transcript


C:\PS> $b = get-childitem $pshome\en-us\about*.help.txt | select-string -pattern transcript -allmatches

C:\PS> $a
C:\Windows\system32\WindowsPowerShell\v1.0\en-us\about_Pssnapins.help.txt:39:       Start-Transcript and Stop-Transcript.

C:\PS> $b
C:\Windows\system32\WindowsPowerShell\v1.0\en-us\about_Pssnapins.help.txt:39:       Start-Transcript and Stop-Transcript.


C:\PS>> $a.matches
Groups   : {Transcript}
Success  : True
Captures : {Transcript}
Index    : 13
Length   : 10
Value    : Transcript


C:\PS> $b.matches
Groups   : {Transcript}
Success  : True
Captures : {Transcript}
Index    : 13
Length   : 10
Value    : Transcript

Groups   : {Transcript}
Success  : True
Captures : {Transcript}
Index    : 33
Length   : 10
Value    : Transcript

Descrição
-----------
Esse exemplo demonstra o efeito do parâmetro AllMatches de Select-String. AllMatches localiza todas as correspondências padrão em uma linha, em vez de localizar apenas a primeira correspondência em cada linha.

O primeiro comando do exemplo pesquisa os arquivos da Ajuda conceitual do Windows PowerShell ("about" Help) para obter instâncias da palavra "transcript". O segundo comando é idêntico, com a exceção de que ele usa o parâmetro AllMatches.

A saída do primeiro comando é salva na variável $a. A saída do segundo comando é salva na variável $b. 

Quando você exibe o valor das variáveis, a exibição padrão é idêntica, conforme mostrado na saída do exemplo.

No entanto, o quinto e o sexto comandos exibem o valor da propriedade Matches de cada objeto. A propriedade Matches do primeiro comando contém apenas uma correspondência (isto é, um objeto System.Text.RegularExpressions.Match), enquanto que a propriedade Matches do segundo comando contém objetos das duas correspondências da linha.

Consulte também

Conceitos

about_Comparison_Operators
about_Regular_Expressions