Tweet

Como usar a ajuda no Windows PowerShell

Vamos aprender neste artigo a usar a ajuda embutida do Powershell.  A ajuda é extremamente importante, pois nos permitirá consultar a descrição e sintaxe corretas de execução dos comandos, além de nos mostrar todos os parâmetros e opções disponíveis.

Podemos visualizar a ajuda de um comando ou cmdlet usando os comandos get-help ou help (que é, tecnicamente, uma função), como nos exemplos:

get-help Get-Event
help Get-Event

Veja que apareceu uma ajuda resumida (Parcial) do comando Get-Event. A ajuda completa ainda não está instalada. O próprio texto exibido nos diz como instalar a ajuda completa: executando o comando Update-Help, estando conectados à Internet. Vamos executá-lo agora:

Update-Help

Os arquivos da ajuda serão baixados e instalados no diretório System32. Você precisa ter privilégios de Administrador para fazer isso.

Após instalar a ajuda completa do Powershell, vamos consultar novamente a ajuda do comando Get-Event para verificarmos se há mais informações disponíveis:

help Get-Event

Veja que agora a ajuda os trouxe muito mais informações a respeito do comando consultado.

Caso o servidor em questão não possua acesso direto á Internet, não se preocupe: você pode salvar a ajuda toda já baixada em um servidor com o comando Save-Help, e então copiá-la para uma pasta de rede com acesso a partir do servidor sem Internet, ou simplesmente copiá-la para uma pasta no próprio servidor, e então executar o comando Update-Help com o parâmetro -SourcePath, que deve apontar para o local onde a ajuda foi copiada.

Vamos salvar a ajuda online em uma pasta compartilhada no servidor srv100, de nome Ajuda (\\srv100\Ajuda):

Save-Help -DestinationPath \\srv100\Ajuda

Veja o conteúdo da ajuda salvo na pasta C:\Ajuda:

E agora, se quisermos importar os arquivos da ajuda para um servidor, basta executar o comando abaixo:

Update-Help  -SourcePath  \\srv100\Ajuda

Podemos também visualizar a ajuda de um item usando a palavra man, que é um alias para a função help:

man cd

Usaremos em nosso curso o comando help, pois ele envia, automaticamente, a saída para o comando more, que irá paginá-la e exibi-la sem “correr” todo o conteúdo de uma vez pela tela. Um detalhe interessante é que o comando more não funciona no ISE, que irá sempre exibir todo o conteúdo da ajuda de uma vez na tela.

Exemplos de uso da ajuda de um comando com alguns parâmetros opcionais:

help dir

Mostra a ajuda do comando dir após enviá-la via pipe para o comando more (paginação)

help *dir*

Permite ver a ajuda de um comando que tenha a palavra-chave dir em seu nome, usando caracteres curinga.

help dir -Examples

Mostra exemplos do comando dir, se estiverem disponíveis.

help dir -Full

Chama a ajuda completa do comando dir

help dir -online

Chama a ajuda online do comando dir.

help dir -ShowWindow

Mostra a ajuda do comando em uma janela gráfica (se estiver usando GUI)

Como interpretar a saída da ajuda do PowerShell

A ajuda do Powershell mostra as informações divididas em seções, que vemos a seguir:

• Nome – Nome do comando
• Sinopse – Descrição sucinata da função do comando
• Sintaxe – Forma correta de escrever o comando e seus parâmetros
• Parâmetros – Lista dos parâmetros e informações sobre eles
• Links Relacionados – Outros termos para pesquisa que tenham relação com o comando
• Aliases – Aliases que apontam para esse comando
• Comentários – Informações adicionais sobre o comando

Dessas seções, uma das mais importantes é Sintaxe. Vejamos um trecho da sintaxe de um comando, chamando a ajuda do comando Get-Eventlog e analisando os pares parâmetro – valor informados na seção Sintaxe:

help Get-Eventlog

Sintaxe:

Get-Eventlog [-logname] <string>   [[InstanceId]] <Int64[]>]  [-After <DateTime>] ….

Interpretando esse trecho da sintaxe temos:

• [-logname] <string> – Parâmetro obrigatório. Porém, escrever a palavra -logname é opcional, o que é denotado pelo uso dos colchetes [ ]  a envolvendo. Esse parâmetro espera a entrada de um dado do tipo string (caracteres gerais). Outro ponto importante é que se a palavra -logname não for utilizada, o valor do parâmetro deve ser passado na primeira posição do comando, pois é o primeiro parâmetro listado – trata-se de um parâmetro posicional.
• [[InstanceId]] <Int64[]>]  – Parâmetro opcional. Tanto o nome do parâmetro quanto o tipo de dado esperado estão entre colchetes. Veja que o nome do parâmetro está dentro de um segundo conjunto de colchetes, então se usarmos esse parâmetro podemos optar por digitar ou não seu nome – ele também é posicional, neste caso estando na posição dois. Para usá-lo em outra posição dentro do comando, será obrigatório fornecer seu nome também – é um parâmetro Nomeado.
• [-After <DateTime>]  – Parâmetro opcional. Porém, nesse caso, se o parâmetro for usado será obrigatório digitar o seu nome (-After) – o nome não está dentro de colchetes, indicando que se trata de um parâmetro nomeado, mas não posicional.

Podemos visualizar informações sobre cada parâmetro, incluindo se o parâmetro é posicional ou nomeado, invocando a ajuda completa do comando:

help Get-Eventlog  -Full

Veja as informações retornadas, por exemplo, sobre o parâmetro -After:

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

Trata-se de um parâmetro que não é obrigatório (necessário = false) e que não é posicional (posição = named), sendo nomeado. Se fosse posicional, a linha Posição mostraria o número de sua posição, como ocorre com o parâmetro -logname:

Veja que sua posição é 1, além de ser um parâmetro obrigatório (Necessário = true).

No próximo artigo vamos começar a explorar o uso dos comandos do Powershell para executar tarefas úteis no sistema.