Partilhar via

Tipos de ajuda no PowerShell

O sistema de ajuda do PowerShell oferece suporte a dois tipos de ajuda.

  • Artigos de ajuda conceitual que descrevem conceitos e cenários de casos de uso.
  • Artigos de ajuda de comando que descrevem a sintaxe e o uso de cmdlets, funções e scripts.

O módulo PlatyPS ajuda você a criar e empacotar arquivos de ajuda do PowerShell para seus módulos.

Arquivos de texto de ajuda conceitual ("sobre")

Artigos de Ajuda conceituais ("sobre") descrevem o módulo, seus membros (como comandos e variáveis) e explica como os membros podem ser usados juntos para executar tarefas. Os artigos de ajuda Sobre são arquivos de texto sem formatação. O módulo PlatyPS não ajuda você a criar esses arquivos, mas pode empacotá-los com os arquivos de ajuda de comando para módulos que suportam ajuda atualizável.

Para obter mais informações sobre como criar artigos de ajuda conceitual, consulte Escrevendo ajuda para módulos do PowerShell.

Artigos de ajuda do Command

Os artigos de ajuda de comando descrevem a sintaxe e o uso de cmdlets, funções e scripts. A ajuda de comando pode ser implementada de duas maneiras:

  • Ajuda baseada em comentários incorporada no script ou função.
  • Ajuda baseada em XML armazenada em um arquivo XML externo.

Ajuda do comando baseado em comentários

Para scripts e funções do PowerShell, você pode escrever ajuda baseada em comentários diretamente no arquivo de origem do script ou função. A ajuda baseada em comentários usa palavras-chave de comentários especiais que o PowerShell reconhece. O PowerShell extrai a ajuda baseada em comentários do script ou função para apresentação pelo Get-Help cmdlet. Para obter mais informações sobre como escrever artigos de ajuda baseados em comentários, consulte os seguintes artigos:

Ajuda de comandos baseados em XML

O sistema de ajuda do PowerShell também suporta os arquivos de ajuda escritos no formato MAML (Microsoft Assistance Markup Language). MAML é um esquema baseado em XML usado para criar documentação de ajuda. MAML é a única maneira de criar ajuda para cmdlets que são implementados em módulos binários. Além disso, este é o formato necessário para módulos que suportam ajuda atualizável.

Você pode usar MAML para criar ajuda para scripts e funções. No entanto, a ajuda baseada em comentários tem precedência sobre a ajuda baseada em XML quando ambos os tipos de ajuda estão presentes, a menos que você use a .EXTERNALHELP palavra-chave de comentário. Quando a palavra-chave comment está presente, ela tem precedência sobre a .EXTERNALHELPGet-Help ajuda baseada em comentários, mesmo quando .EXTERNALHELP não é possível encontrar um arquivo de ajuda especificado no comentário. Para obter mais informações sobre como escrever artigos de ajuda baseados em XML, consulte Como criar o arquivo de ajuda do cmdlet.

A caligrafia MAML é tediosa e propensa a erros. O módulo PlatyPS permite que você escreva sua documentação de comando no Markdown e, em seguida, compile-a no formato MAML. Para obter informações sobre como usar o PlatyPS, consulte Criar nova ajuda de Markdown usando o PlatyPS.

  • Last updated on