Heading

Como em qualquer linguagem de programação, PowerShell suporta comentários. De facto, suportará dois estilos de comentários. No entanto, como verá mais adiante neste artigo, PowerShell pode usar comentários de duas formas interessantes e inesperadas que podem ser bastante poderosas.

Utilizar Comentários

O estilo de comentário mais comum que verá é uma linha precedida por um símbolo #. (Deixo-vos decidir se querem chamar a isso um hashtag, um símbolo de libra, ou mesmo um bom velho octothorpe!)

Como exemplo, poderá ter um bloco de comentários no início do seu programa com detalhes sobre o mesmo:

Comentários como este podem ir para qualquer lugar no seu código. Uma forma alternativa de o fazer, contudo, seria mais aquilo a que eu chamaria um estilo de linguagem C ou por vezes referido como um comentário em bloco:

Este estilo permite-lhe adicionar mais facilmente linhas de comentários sem ter um # à frente de cada uma. É livre de usar um ou outro estilo ou mesmo ambos. Basta lembrar, no entanto, a utilidade de blocos de comentários como este quando voltar a depurar o seu próprio código daqui a um ano. No entanto, os comentários também não têm de vir no início de uma linha. Na verdade, pessoalmente, só me encontro a utilizar blocos de comentários como os acima referidos no início de um guião ou mesmo antes de um bloco de código particularmente complicado. É muito mais provável que faça comentários em linha, como por exemplo:

Incluí este comentário num script recente porque o | Out-Null não era algo que eu esperava que fosse exigido, e sei que daqui a um ano, se não tivesse o comentário lá, estaria a pensar porque o tinha lá. Ou pior, retirava-o e depois perguntava-me porque recebi uma mensagem de cancelamento que continuava a aparecer.

Note que quando se começa um comentário com um #, tudo até ao fim da linha é tratado como um comentário. Isto pode ser útil, por exemplo, quando se está a testar e pode querer comentar o fim de um comando.

Isto permite-lhe mais tarde remover o comentário e obter o –online versão de ajuda, mas e se quiser um comentário no meio? Mais uma vez, o PowerShell dá-lhe esse poder.

Note que ao utilizar um comentário em estilo de bloco, obtém a capacidade de ter um comentário no meio do seu comando e ainda executar ou interpretar itens à direita do mesmo. Finalmente, pode estar a pensar, “e se eu quiser imprimir um # ou fazer algo semelhante”? Se tentar

Vai ver que não escreve o que quer. Simplesmente obtém:

É aqui que o túmulo-acento ` vem a calhar.

Isto irá imprimir a mensagem que deseja.

Também pode embrulhar toda essa cadeia entre aspas:

Isso funcionaria, mas queria dar um exemplo de como escapar ao # qualificativo.

Se você, como eu, usa frequentemente o PowerShell ISE para escrever scripts, há um último truque útil que quero partilhar, mas só posso descrever e dar algumas imagens para, não fornecer realmente um script para ele. É um atalho de teclado que não é específico mas útil se tiver um pedaço de código que queira comentar, digamos para teste. Coloque o cursor no início da linha e mantenha pressionado Shift-Alt use as teclas de setas para o mover para cima ou para baixo. Verá aparecer uma linha fina (azul no meu ecrã). Depois de marcar as linhas que deseja comentar, basta escrever um # e ele aparecerá no início de cada linha.

Este é um exemplo do código a comentar:

Ao clicar à direita do texto na linha 40 e depois de premir várias vezes Shift-Alt e a seta para cima, verá a linha azul:

Após premir # <space> verá os caracteres adicionados ao código:

Como nota, pode usar este truque em qualquer parte da linha (por isso se quiser colocar um monte de comentários no fim de um número de linhas pode usar este truque para facilmente colocar o # para si) e não é obviamente específico para comentar, mas esse é um dos usos mais óbvios. Também o pode fazer usando expressões regulares. Realce o bloco de código em questão:

Então Ctrl-H para obter a caixa de diálogo Encontrar e Substituir. Certifique-se de que as expressões Encontrar na Selecção e Regular são seleccionadas:

O carpete ^ é usado para fixar o início de uma linha e, claro, o # (há lá um espaço) basicamente insere um # e um espaço no fim das linhas em destaque. Note que se não conseguir destacar um bloco de código, este funcionará em todo o seu script.

E Mais

No entanto, se isso fosse tudo o que os comentários pudessem fazer no PowerShell este seria um artigo muito curto e aborrecido (e o meu editor estaria a abanar a cabeça dizendo: “Greg, preciso de mais de 850 palavras!”) Como muitas coisas no PowerShell, os criadores acrescentaram características que o tornam mais poderoso do que se poderia esperar.

Preparei recentemente uma apresentação que estava a fazer no Hampton Roads SQL Server User Group. Durante esta apresentação, executei um script no PowerShell que inicia e pára o SQL Server. Para o fazer, preciso de o executar como administrador. Claro que me tinha esquecido completamente que durante uma prática, e quando a executei como eu próprio, acabou por cometer vários erros feios. Isto não foi um showtopper, mas não é o que se quer durante uma demonstração. Isto fez-me pensar em como poderia garantir que isto não aconteceria durante a conversa real.

O meu primeiro pensamento foi encontrar um cmdlet que verificasse quem eu estava ligado como e depois abortar se não fosse o utilizador certo. Parte do problema com esta abordagem é que quando se executa um programa (como o PowerShell ISE) como administrador, aparece como o utilizador que fez o log in. Isto ia ser mais difícil do que eu pensava.

Once novamente, PowerShell surpreendeu-me. Resolver este problema é trivial. Para ver como resolver o problema, abra o PowerShell ISE como você mesmo (ou seja, o PowerShell ISE). NÃO seleccione Executar como administrador e certifique-se de que o seu utilizador não tem privilégios de administrador local) e introduza o seguinte código:

Guarda isto para um ficheiro chamado restart timer service example.ps1 e depois tente executá-lo. A menos que seja um administrador local na sua máquina, deverá obter um ecrã de erro semelhante ao abaixo.

Se executar isto utilizando a opção Executar como Administrador, deverá executar sem erro. Neste exemplo, a falha é bastante benigna, mas talvez esteja a escrever um script onde uma falha não seria tão inofensiva. Para resolver este problema, basta colocar o seguinte comentário no topo do script acima e salvá-lo novamente.

Agora irá obter um erro diferente:

Ainda é um pouco feio mas muito melhor do que correr o script e talvez quebrar algo. Note que se simplesmente cortar e colar o guião numa nova janela, mas não o guardar, o PowerShell tentará executar tudo. Basicamente, o #requires é ignorado, a menos que se trate de um ficheiro realmente guardado. Isto resolveu o meu problema inicial, mas pôs-me a investigar outras características das quais não tinha conhecimento. Para #requires, há uma lista completa:

Como pode ver, estes dão-lhe muito poder para controlar como e quando o seu script é executado. O #Requires –Version é útil se o seu script requer características que só estão disponíveis numa versão mais recente do PowerShell. Note-se que este é um número mínimo. A versão do PowerShell que está a executar deve corresponder a esta ou ser superior. Não pode usar isto para requerer uma versão anterior de PowerShell. Por exemplo, uma cmdlet útil que usei num script recente é compress-archive. Felizmente, este script era específico para o problema que eu estava a tentar resolver, mas se eu estivesse a tentar escrever um script mais geral, poderia querer colocar #requires –Version 5.0 na paragem do meu script. Para demonstrar, guardar o seguinte script como requer o exemplo da versão.ps1.

Se correr isto dentro da sua instância PowerShell ISE existente, deve correr sem problemas, mas se tentar correr numa versão mais antiga, tal como PowerShell 2.0, o script irá errar na linha #requires e nunca executar o resto do script. Este é o resultado desejado.

Para testar, poderia também colocar algo como –Version 99.99 e verá mensagens de erro semelhantes aos exemplos abaixo, mas queria mostrar como isto funcionaria no mundo real em sistemas existentes e também demonstrar a capacidade da linha de comando para regressar a uma versão anterior do PowerShell.

Para testar isto, terá de usar a versão de linha de comando do PowerShell e iniciá-la como se segue:

Então execute o ficheiro que guardou acima requires version example.ps1. Deverá ver um erro tal como:

Enquanto eu recomendaria colocar o #Requires comment logo no início do ficheiro, na verdade, pode colocá-lo em qualquer lugar e ele actuará da mesma forma. Se recriar o ficheiro acima mas mover o comentário para baixo após o Get-Process e guardar como requer o exemplo da versão 2.ps1.

Tente executá-lo na versão 2.0 como acima, e obterá um erro semelhante e todo o script falhará a execução.

Isto significa que não pode ter parte de um script que pode correr sob uma versão mais antiga (ou correr como não-administrador) e depois parte que requer uma versão em particular ou correr como administrador. Se quiser fazer algo assim em código, precisa de se tornar mais inteligente. Guarde o seguinte script como Requires version example Version 3.ps1.

Se executar isto na Versão 5 ou superior, criará o ficheiro Process.txt e zipá-lo-á para cima. Se o executar sob uma versão anterior, tal como o –Version 2.0 acima, o script ainda será capaz de criar o ficheiro Process.txt uma vez que Get-Process é um cmdlet disponível na versão 2.0. Uma vez que Compress-Archive não está, o script saltará esse passo e dará uma mensagem de erro. Depende de si se quiser escrever scripts que possam detectar a versão do PowerShell e comportar-se de forma diferente dependendo da versão, mas em muitos casos se quiser simplesmente abortar o script, o #Requires comment é de longe a forma mais fácil de lidar com as coisas.

Duas últimas advertências sobre a utilização de um #Requires comment. Deve começar no início da linha; não se pode ter quaisquer espaços ou separadores antes dela. Além disso, não se pode tentar ser mais esperto e colocá-lo como parte de um bloco de tentativa/captura para o manusear de forma mais graciosa. Guarde o seguinte guião para ilustrar as duas advertências: Requer o exemplo de versão Versão 4.ps1.

Nota é a #requires na linha 6 que abortou o guião, não o da linha 1, e a tentativa/captura não teve efeito. #Requires são globais e têm impacto em todo o script, independentemente da sua localização, desde que comecem na linha. E sim, pode ter mais do que um #Requires num guião. Pode ser necessária uma versão específica do PowerShell, certos módulos para estar presente e para RunAsAdministrator.

Duas advertências finais no #Requires – RunAsAdministrator comentário. Foi introduzido no PowerShell versão 4.0 e não funciona em sistemas não-Windows (sim, lembrem-se, o PowerShell é agora cross-platform!). Guarde o seguinte script como Requires Administrator.ps1.Irá precisar de uma instância Linux para testar isto, mas supondo que o faça, PowerShell pode ser instalado no Linux usando os métodos aqui explicados. Uma vez instalado, copie ou guarde o script acima na sua instância Linux. Para executar o script, pode entrar:

Deverá ver

Finalmente, poderá estar a perguntar-se se pode usar comentários em estilo de bloco com o #Requires. A partir dos meus testes limitados, isto não funciona. É necessário colocar cada Requer na sua própria linha com um # anterior. Este guião funciona:

Este script não funciona:

Conclusão