Windows PowerShell

  • Artigo

WTFM: Writing the Fabulous Manual

Don Jones

“ RTFM ” é um dos acrônimos Favoritos do setor de TI (pelo menos a língua inglesa parte dele). Ele é extenso diferente por diferentes pessoas, mas geralmente ele é aceito para ser algo como “ Read the fabulosa manual ” e ele normalmente tem em resposta a uma pergunta que provavelmente poderia ter sido respondida mais rapidamente e completamente se o asker tinha simplesmente ler as instruções. À medida que trabalhar com o Windows PowerShell, no entanto e começar a criar scripts e funções para outros usuários, é você fazendo-se de que existe realmente um conjunto de instruções para que eles possam ler? É, em outras palavras, escrita manual fabulosa (WTFM)?

‘ Nenhum comentário ’ nunca é a resposta certa

Se você tiver qualquer experiência qualquer computador de programação ou scripts, você está familiarizado com o uso de comentários in-line para ajudar a documentar a função de uma determinada parte do código. Naturalmente, o Windows PowerShell oferece suporte para comentários: O shell ignora qualquer linha que começa com #, permitindo que você coloque quaisquer comentários que desejar.

Infelizmente, para ler esses comentários, você deve abrir o script no bloco de notas do Windows ou outro editor e é um comportamento diferente da que você provavelmente usaria para um cmdlet do shell, que se integra ao sistema de ajuda interna do shell. Um dos conceitos base no Windows PowerShell é que você só deve precisa aprender um único conjunto de habilidades e os comportamentos para qualquer tarefa determinada; se já aprendeu a usar o Get-Help comando de para obter instruções sobre como um cmdlet nativo, por que devem as coisas funcionam qualquer forma diferente para um script ou uma função?

No v2 do shell, as coisas Don ter para funcionar de maneira diferente. O Windows PowerShell v2 apresenta um novo formulário de documentação chamado obter ajuda com base no comentário. Essencialmente, o shell sabe procurar especialmente formatados comentários dentro de uma função ou de script e ele analisa os comentários para construir o mesmo tipo de exibição ajuda que você veria com um cmdlet nativo. Ajuda do cmdlet é realmente escrita no formato XML; ajuda baseados em comentário não só é mais fácil construir manualmente, mas também são transferidas juntamente com qualquer script ou função que ele está anexado, tornando seu script ou a função independente e fáceis de distribuir.

Defina um objetivo de produzir um script ou uma função que pode exibir a Ajuda através do comando interno Get-Help , formatação ajudá-lo exatamente como que um cmdlet nativo, como mostra a 1 Figura Let’s.

 

Figura 1 Ajuda formatado como um cmdlet nativo no Windows PowerShell.

Para WTFM, RTFM

O Windows PowerShell inclui completa ajuda interna para obter ajuda com base no comentário: Basta executar ajudar about_comment_based_help . Basicamente, as regras para obter ajuda com base no comentário são simples:

  • Os comentários devem ser a primeira coisa dentro do script (se a Ajuda se aplica a todo o script) ou da função (se a Ajuda é específica para uma função).
  • Os comentários devem usar formatação específica e palavras-chave para que a funcionalidade de Ajuda do shell pode ser analisado-las corretamente.

Você pode usar qualquer um dos comentários de uma linha, precede cada linha com #, ou você pode usar o novo bloco de comentário. Esses são mais fácil de digitar, porque você Don usar um # na frente de cada linha. Inicie um comentário de bloco, digitando < # em uma linha sozinha e a finaliza com # > em uma linha por si só. Qualquer coisa entre essas duas linhas será considerada parte do comentário.

As instruções da Ajuda serão construídas como uma série de blocos. Cada bloco começa com uma palavra-chave de seção, como .SYNOPSIS ou .DESCRIPTION. A palavra-chave real é precedida por um período e o período deve ser o primeiro caractere na linha, com exceção de espaços ou o caractere #. O arquivo de about_comment_based_help lista todas as possíveis palavras-chave, mas as principais são:

  • .SYNOPSIS –a breve explicação do que o script ou a função faz.
  • .DESCRIPTION – uma mais detalhada explicação do que o script ou a função faz.
  • .PARAMETER nome – uma explicação de um parâmetro específico. Substitua nome de pelo nome do parâmetro. Você pode ter um dessas seções para cada parâmetro usa scripts ou função.
  • .EXAMPLE – um exemplo de como usar o script ou a função. Você pode ter várias seções .EXAMPLE se você deseja fornecer mais de um exemplo.
  • .NOTES – diversas anotações usando o script ou função.
  • Ajudar a .LINK – uma referência cruzada para outro tópico; você pode ter mais de um destes procedimentos. Se você incluir uma URL que comece com http:// ou https://, o shell abrirá aquele URL quando –online parâmetro do comando Ajuda é usado.

Cada palavra-chave é ativada uma linha por si mesmo e é seguido por uma ou mais linhas de texto. Eis um exemplo:

<#.SYNOPSISRetrieves service pack and operating system information from one or more remote computers..DESCRIPTIONThe Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. Each computer is contacted sequentially, not in parallel..PARAMETER computerNameAccepts a single computer name or an array of computer names. You mayalso provide IP addresses..PARAMETER pathThe path and file name of a text file. Any computers that cannot be reached will be logged to this file. This is an optional parameter; if it is notincluded, no log file will be generated..EXAMPLERead computer names from Active Directory and retrieve their inventory information.Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.EXAMPLERead computer names from a file (one name per line) and retrieve their inventory informationGet-Content c:\names.txt | Get-Inventory.NOTESYou need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.#>

Figura 2 mostra o que isso como dentro de uma função real.

 

Figura 2 Helpinstructions dentro de uma função.

O comando Ajuda de continuarão a seguir suas regras normais para quais partes da Ajuda para exibir. Por exemplo, você verá somente o .EXAMPLE seção se você usar o parâmetro de –example , enquanto você verá todas as seções se você usar o parâmetro de –full .  Em qualquer caso, você verá (como na Figura 3 de ) que ajuda da função neste parece ser idêntica de um cmdlet nativo.

 

Figura 3 Ajuda da função A que se parece com um cmdlet nativo.

Práticas recomendadas para ajuda com base no comentário

Eu gostaria de incluir pelo menos uma seção .SYNOPSIS e .DESCRIPTION dentro de cada função que escrevo ou script. Se o script ou a função usa um ou mais parâmetros, aqueles com uma seção .PARAMETER eu documento. Dessa forma, qualquer pessoa que vem posteriormente e precisa usar o script ou a função pode facilmente descobrir o que ele faz. Saco, para essa questão, seis meses depois, será provavelmente tenha esquecido que escrevi e vai precisa um atualizador rápido — que convenientemente fornece a Ajuda do comentário.

Mais estruturada e reutilizáveis seu código, mais detalhada deve ser sua ajuda. Por exemplo, eu estruturada minha função de exemplo obter inventário como uma “ função avançada ”, que significa que ele parece e funciona bem como um cmdlet nativo. Que é o mais alto de vida no mundo do shell, para que eu deve fornecer o mesmo nível de obter ajuda detalhada sobre como um cmdlet “ real ” — incluindo documentar exemplos, anotações, referências cruzadas, entradas e saídas e assim por diante.

Utilitários de terceiros mais estão começando a contar com a Ajuda. Por exemplo, ambientes de script integradas de terceiros geralmente analisar o ajudam a fornecer o IntelliSense como dicas de código e - conclusão recursos em seus ambientes de edição; incluindo ajuda completa e formatada corretamente com base em comentário, você está ativando seus scripts e funções para ser usado com mais facilidade de dentro dessas ferramentas de terceiros.

Além disso, ele apenas parece legal ter scripts e funções que aparência como muito como “ reais ” cmdlets possível — incluindo a saída de Ajuda procurando eficientes.

Conteúdo relacionado