Partilhar via

Escrevendo a Ajuda para Módulos do PowerShell

Os módulos do PowerShell podem incluir tópicos da 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 em 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 fornecedor. 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 da função. Os tópicos da Ajuda que descrevem funções em um módulo podem ser arquivos XML que usam o esquema de ajuda do comando ou tópicos da Ajuda baseados em comentários dentro da função, ou o script ou 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 da Ajuda baseados em comentários no script ou módulo de script.
    • A $PSHOME\Schemas\PSMaml pasta contém os arquivos de esquema que definem o formato XML.

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

    Você pode usar um tópico da 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 da Ajuda Sobre. 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 começar 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 sufixo .help.txt . 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 dos tópicos conceituais da Ajuda é arbitrária. Os restantes títulos de secção podem ser o que for apropriado para o 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 que desejar, mas o PowerShell vê isso como texto sem formatação e não há 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 (multibyte) sejam exibidos corretamente.
    • Sublinhe cabeçalhos de seção ou use todas as letras maiúsculas para destacá-los. Isso torna o conteúdo mais fácil de verificar.
    • Limite o comprimento de cada linha a 80 caracteres.
    • Recue blocos de código e saída de exemplo para separá-los da prosa ao redor.

Colocação da Ajuda do Módulo

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

Por exemplo, o diagrama de estrutura de diretórios 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 espaço reservado <ModulePath> representa um dos caminhos na PSModulePath variável de ambiente, como $HOME\Documents\Modules, $PSHOME\Modulesou um caminho personalizado especificado pelo usuário.

Obter ajuda do módulo

Quando um usuário importa um módulo para uma sessão, os tópicos da Ajuda desse 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 Export-ModuleMember Ajuda não são afetados pelo 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 procura os tópicos da Ajuda em subdiretórios específicos do idioma do diretório do módulo de acordo com os padrões de fallback de idioma estabelecidos para o Windows.

A partir do PowerShell 3.0, a execução de um Get-Help comando para um cmdlet ou função aciona 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 do comando, parâmetros e tipos de entrada e saída, mas não inclui nenhuma descrição. A ajuda gerada automaticamente inclui texto que direciona o usuário a tentar usar o cmdlet para baixar a Update-Help ajuda para o comando da Internet ou de um compartilhamento de arquivos. Ele também recomenda o uso do parâmetro Online do Get-Help cmdlet para obter a versão online do tópico da Ajuda.

Suportando a 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 Save-Help ocultam os detalhes de gerenciamento do usuário. Os usuários executam o Update-Help cmdlet e, em seguida, usam o Get-Help cmdlet para ler os arquivos de ajuda mais recentes para o módulo no prompt de comando do PowerShell. Os usuários não precisam reiniciar o Windows ou o PowerShell.

Os usuários atrá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 confiam na versão online dos tópicos de ajuda do módulo. O parâmetro Online do 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 Get-Help 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 da ajuda.

A partir do PowerShell 3.0, você pode ajudar os usuários a encontrar a versão online dos tópicos de ajuda do cmdlet e da função definindo o atributo HelpUri na classe do cmdlet ou a 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 on-line.

Ver também

  • Last updated on