Suporte à ajuda online

2025-03-25

Observação

A criação manual de ajuda baseada em XML é muito difícil. O módulo PlatyPS permite que você escreva ajuda no Markdown e converta-a em ajuda baseada em XML. Isso facilita muito a gravação e a manutenção da ajuda. PlatyPS também pode criar os pacotes de Ajuda Atualizáveis para você. Para obter mais informações, consulte Criar ajuda baseada em XML usando o PlatyPS.

A partir do PowerShell 3.0, há duas maneiras de dar suporte ao recurso Get-Help Online para comandos do PowerShell. Este tópico explica como implementar esse recurso para diferentes tipos de comando.

Sobre a Ajuda Online

A ajuda online sempre foi uma parte vital do PowerShell. Embora o cmdlet Get-Help exiba tópicos de ajuda no prompt de comando, muitos usuários preferem a experiência de ler online, incluindo codificação de cores, hiperlinks e compartilhamento de ideias em Conteúdo da Comunidade e documentos baseados em wiki. Mais importante, antes do advento da Ajuda Atualizável, a ajuda online forneceu a versão mais up-todata dos arquivos de ajuda.

Com o advento da Ajuda Atualizável no PowerShell 3.0, a ajuda online ainda desempenha um papel vital. Além da experiência flexível do usuário, a ajuda online fornece ajuda aos usuários que não usam ou não podem usar a Ajuda Atualizável para baixar tópicos de ajuda.

Como Get-Help -Online funciona

Para ajudar os usuários a encontrar os tópicos de ajuda online para comandos, o comando Get-Help tem um parâmetro Online que abre a versão online do tópico de ajuda para um comando no navegador da Internet padrão do usuário.

Por exemplo, o comando a seguir abre o tópico de ajuda online do cmdlet Invoke-Command.

Get-Help Invoke-Command -Online

Para implementar Get-Help -Online, o cmdlet Get-Help procura um URI (Uniform Resource Identifier) para o tópico de ajuda de versão online nos locais a seguir.

O primeiro link na seção Links Relacionados do tópico de ajuda do comando. O tópico da ajuda deve ser instalado no computador do usuário. Esse recurso foi introduzido no PowerShell 2.0.
A propriedade HelpUri de qualquer comando. A propriedade HelpUri fica acessível mesmo quando o tópico de ajuda do comando não está instalado no computador do usuário. Esse recurso foi introduzido no PowerShell 3.0.

Get-Help procura um URI na primeira entrada na seção links relacionados do antes de obter o valor da propriedade HelpUri. Se o valor da propriedade estiver incorreto ou tiver sido alterado, você poderá substituí-lo inserindo um valor diferente no primeiro link relacionado. No entanto, o primeiro link relacionado funciona somente quando os tópicos de ajuda são instalados no computador do usuário.

Você pode dar suporte a Get-Help -Online para qualquer comando adicionando um URI válido à primeira entrada na seção links relacionados do tópico de ajuda baseado em XML para o comando. Essa opção é válida somente em tópicos de ajuda baseados em XML e funciona somente quando o tópico da ajuda é instalado no computador do usuário. Quando o tópico de ajuda é instalado e o URI é preenchido, esse valor tem precedência sobre a propriedade HelpUri do comando.

Para dar suporte a esse recurso, o URI deve aparecer no elemento maml:uri no primeiro elemento maml:relatedLinks/maml:navigationLink no elemento maml:relatedLinks.

O XML a seguir mostra o posicionamento correto do URI. O Online version: texto no elemento maml:linkText é uma prática recomendada, mas não é necessário.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Adicionando a propriedade HelpUri a um comando

Esta seção mostra como adicionar a propriedade HelpUri a comandos de diferentes tipos.

Adicionando uma propriedade HelpUri a um cmdlet

Para cmdlets escritos em C#, adicione um atributo HelpUri à classe cmdlet. O valor do atributo deve ser um URI que começa com http ou https.

O código a seguir mostra o atributo HelpUri da classe de cmdlet Get-History.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Adicionando uma propriedade HelpUri a uma função avançada

Para funções avançadas, adicione uma propriedade HelpUri ao atributo CmdletBinding. O valor da propriedade deve ser um URI que começa com "http" ou "https".

O código a seguir mostra o atributo HelpUri da função New-Calendar

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

Adicionando um atributo HelpUri a um comando cim

Para comandos CIM, adicione um atributo HelpUri ao elemento CmdletMetadata no arquivo CDXML. O valor do atributo deve ser um URI que começa com http ou https.

O código a seguir mostra o atributo HelpUri do comando CIM Start-Debug

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Adicionando um atributo HelpUri a um fluxo de trabalho

Para fluxos de trabalho escritos no idioma do PowerShell, adicione uma palavra-chave de comentário .EXTERNALHELP ao código do fluxo de trabalho. O valor da palavra-chave deve ser um URI que começa com http ou https.

Observação

A propriedade HelpUri não tem suporte para fluxos de trabalho baseados em XAML no PowerShell.

O código a seguir mostra a palavra-chave .EXTERNALHELP em um arquivo de fluxo de trabalho.

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"

Compartilhar via