Compartilhar via

Escrevendo ajuda para módulos do PowerShell

Os módulos do PowerShell podem incluir tópicos de Ajuda sobre o módulo e sobre os membros do módulo, como cmdlets, provedores, funções e scripts. O Get-Help cmdlet exibe os tópicos da Ajuda do módulo no mesmo formato que exibe a Ajuda para outros itens do PowerShell e os usuários usam comandos padrão Get-Help para obter os tópicos da Ajuda.

Este documento explica o formato e o posicionamento correto dos tópicos da Ajuda do módulo e sugere diretrizes para o conteúdo da Ajuda do módulo.

Tipos de Ajuda do Módulo

Um módulo pode incluir os seguintes tipos de Ajuda.

  • Ajuda baseada em XML

    • Ajuda do cmdlet. Os tópicos da Ajuda que descrevem cmdlets em um módulo são arquivos XML que usam o esquema de ajuda de comando
    • Ajuda do provedor. Os tópicos da Ajuda que descrevem provedores em um módulo são arquivos XML que usam o esquema de ajuda do provedor.
    • Ajuda de função. Os tópicos da Ajuda que descrevem as funções em um módulo podem ser arquivos XML que usam o esquema de ajuda de comando ou tópicos de Ajuda baseados em comentários dentro da função, ou o script ou o módulo de script
    • Ajuda de script. Os tópicos da Ajuda que descrevem scripts em um módulo podem ser arquivos XML que usam o esquema de ajuda de comando ou tópicos de Ajuda baseados em comentários no módulo de script ou script.
    • A $PSHOME\Schemas\PSMaml pasta contém os arquivos de esquema que definem o formato XML.

  • Arquivos de texto de ajuda conceituais ("Sobre")

    Você pode usar um tópico de Ajuda conceitual ("sobre") para descrever o módulo e seus membros e explicar como os membros podem ser usados juntos para executar tarefas. Por padrão, o PowerShell inclui mais de 100 desses tópicos conceituais sobre a Ajuda. O nome do arquivo deve usar o about_<name>.help.txt formato, como about_MyModule.help.txt.

    Observação

    O TOPIC cabeçalho da seção deve ser iniciado na primeira coluna da primeira linha do arquivo. O conteúdo da seção na segunda linha deve corresponder ao nome do arquivo, sem o .help.txt sufixo. Você deve recuar o conteúdo exatamente 4 espaços. A terceira linha deve estar em branco. O SYNOPSIS cabeçalho da seção deve começar na primeira coluna da quarta linha. Você deve recuar o conteúdo na quinta linha exatamente 4 espaços. Esses requisitos são necessários para que o Get-Help cmdlet reconheça o conteúdo corretamente.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    Você pode usar o modelo de exemplo a seguir como ponto de partida para escrever tópicos conceituais da Ajuda. Com exceção das duas primeiras seções, a estrutura de tópicos conceituais da Ajuda é arbitrária. Os títulos de seção restantes podem ser o que for apropriado para seu conteúdo.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    Você pode usar qualquer estilo e marcação desejados, mas o PowerShell o vê como texto sem formatação e não há nenhuma renderização especial do texto no console do PowerShell. As sugestões a seguir garantem os melhores resultados de exibição e legibilidade.

    • Use UTF-8 com codificação BOM para garantir que todos os caracteres especiais (vários bytes) são exibidos corretamente.
    • Sublinhar cabeçalhos de seção ou usar todas as letras maiúsculas para que elas se destaquem. Isso facilita a verificação do conteúdo.
    • Limite o comprimento de cada linha para 80 caracteres.
    • Recuo de blocos de código e saída de exemplo para separá-los da prosa ao redor.

Posicionamento da Ajuda do Módulo

O Get-Help cmdlet procura arquivos de tópico da Ajuda do módulo em subdiretórios específicos da linguagem do diretório do módulo.

Por exemplo, o diagrama de estrutura de diretório a seguir mostra o local dos tópicos da Ajuda para o módulo SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Observação

No exemplo, o <ModulePath> espaço reservado representa um dos caminhos na variável de PSModulePath ambiente, como $HOME\Documents\Modules, $PSHOME\Modulesou um caminho personalizado especificado pelo usuário.

Obtendo ajuda do módulo

Quando um usuário importa um módulo para uma sessão, os tópicos da Ajuda para esse módulo são importados para a sessão junto com o módulo. Você pode listar os arquivos de tópico da Ajuda no valor da chave FileList no manifesto do módulo, mas os tópicos da Ajuda não são afetados pelo Export-ModuleMember cmdlet.

Você pode fornecer tópicos de Ajuda do módulo em diferentes idiomas. O Get-Help cmdlet exibe automaticamente os tópicos da Ajuda do módulo no idioma especificado para o usuário atual no item Opções Regionais e de Idioma no Painel de Controle. No Windows Vista e versões posteriores do Windows, Get-Help pesquisa os tópicos da Ajuda em subdiretórios específicos de linguagem do diretório do módulo de acordo com os padrões de fallback de linguagem estabelecidos para o Windows.

A partir do PowerShell 3.0, a execução de um Get-Help comando para um cmdlet ou de função dispara a importação automática do módulo. O Get-Help cmdlet exibe imediatamente o conteúdo dos tópicos de ajuda no módulo.

Se o módulo não contiver tópicos de ajuda e não houver tópicos de ajuda para os comandos no módulo no computador do usuário, Get-Help exibirá a ajuda gerada automaticamente. A ajuda gerada automaticamente inclui a sintaxe de comando, os parâmetros e os tipos de entrada e saída, mas não inclui nenhuma descrição. A ajuda gerada automaticamente inclui texto que orienta o usuário a tentar usar o Update-Help cmdlet para baixar a ajuda para o comando da Internet ou de um compartilhamento de arquivos. Também recomenda usar o parâmetro Online do Get-Help cmdlet para obter a versão online do tópico de ajuda.

Suporte à Ajuda Atualizável

Os usuários do PowerShell 3.0 e versões posteriores do PowerShell podem baixar e instalar arquivos de ajuda atualizados para um módulo da Internet ou de um compartilhamento de arquivos local. Os Update-Help cmdlets e os Save-Help cmdlets ocultam os detalhes de gerenciamento do usuário. Os usuários executam o Update-Help cmdlet e usam o Get-Help cmdlet para ler os arquivos de ajuda mais recentes do módulo no prompt de comando do PowerShell. Os usuários não precisam reiniciar o Windows ou o PowerShell.

Os usuários por trás de firewalls e aqueles sem acesso à Internet também podem usar a Ajuda Atualizável. Os administradores com acesso à Internet usam o Save-Help cmdlet para baixar e instalar os arquivos de ajuda mais recentes em um compartilhamento de arquivos. Em seguida, os usuários usam o parâmetro Path do Update-Help cmdlet para obter os arquivos de ajuda mais recentes do compartilhamento de arquivos.

Os autores do módulo podem incluir arquivos de ajuda no módulo e usar a Ajuda Atualizável para atualizar os arquivos de ajuda ou omitir arquivos de ajuda do módulo e usar a Ajuda Atualizável para instalá-los e atualizá-los.

Para obter mais informações sobre a Ajuda Atualizável, consulte suporte à ajuda atualizável.

Suporte à Ajuda Online

Os usuários que não podem ou não instalam arquivos de ajuda atualizados em seus computadores geralmente dependem da versão online dos tópicos de ajuda do módulo. O parâmetro Online do Get-Help cmdlet abre a versão online de um cmdlet ou tópico de ajuda de função avançada para o usuário em seu navegador de Internet padrão.

O Get-Help cmdlet usa o valor da propriedade HelpUri do cmdlet ou função para localizar a versão online do tópico de ajuda.

A partir do PowerShell 3.0, você pode ajudar os usuários a encontrar a versão online dos tópicos de ajuda de cmdlet e função definindo o atributo HelpUri na classe cmdlet ou na propriedade HelpUri do atributo CmdletBinding . O valor do atributo é o valor da propriedade HelpUri do cmdlet ou função.

Para obter mais informações, consulte Suporte à Ajuda Online.

Consulte Também

  • Last updated on