Partilhar via

Apoio Ajuda Online

Observação

A criação manual de ajuda baseada em XML é muito difícil. O módulo PlatyPS permite escrever ajuda em Markdown e, em seguida, convertê-la em ajuda baseada em XML. Isso torna muito mais fácil escrever e manter a ajuda. PlatyPS também pode criar os pacotes de Ajuda atualizáveis para você. Para obter mais informações, consulte Ajuda para criar base 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 leitura online, incluindo codificação de cores, hiperlinks e compartilhamento de ideias em Conteúdo da Comunidade e documentos baseados em wiki. Mais importante ainda, antes do advento da Ajuda Atualizável, a ajuda on-line fornecia a versão mais up-todos 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 on-line 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 funciona Get-Help -Online

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 de internet padrão do usuário.

Por exemplo, o comando a seguir abre o tópico da Ajuda online para o 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 da versão online nos seguintes locais.

  • 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.

  • O HelpUri propriedade de qualquer comando. A propriedade HelpUri é acessível mesmo quando o tópico de ajuda para o 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 antes de obter o HelpUri valor da propriedade. 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 apenas quando os tópicos de ajuda estão instalados no computador do usuário.

Você pode oferecer 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. Esta opção é válida apenas em tópicos de ajuda baseados em XML e funciona apenas quando o tópico de ajuda está instalado no computador do utilizador. Quando o tópico da Ajuda é instalado e o URI é preenchido, esse valor tem precedência sobre a propriedade HelpUri do comando.

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

O XML a seguir mostra o posicionamento correto do URI. O texto Online version: no elemento maml:linkText é uma prática recomendada, mas não é obrigató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 Get-History cmdlet.

[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 Start-Debug CIM

<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 na linguagem PowerShell, adicione uma palavra-chave .EXTERNALHELP comment 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 é suportada 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"
  • Last updated on