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.
