Compartilhar via

Suporte à ajuda online

  • Artigo

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 exibe 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 do Community e documentos baseados em Get-Help wiki. O mais importante é que, antes do advento da Ajuda Atualizável, a ajuda online forneceu a versão mais atualizada 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 do usuário flexível, a ajuda online fornece ajuda para 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 tem um parâmetro Online que abre a versão online do tópico de ajuda para um comando no navegador da Get-Help Internet padrão do usuário.

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

Get-Help Invoke-Command -Online

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

  • O primeiro link na seção Links Relacionados do tópico de ajuda para o comando. O tópico de 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 é 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-Helpprocura um URI na primeira entrada na seção Links Relacionados 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 qualquer comando adicionando um URI válido à primeira entrada na seção Links Relacionados do tópico de ajuda baseado em Get-Help -Online XML para o comando. Essa opção só é válida em tópicos de ajuda baseados em XML e funciona somente quando o tópico de ajuda é instalado no computador do usuário. Quando o tópico de ajuda é instalado e o URI é populado, esse valor tem precedência sobre a propriedade HelpUri do comando.

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

O XML a seguir mostra o posicionamento correto do URI. O Online version: texto no elemento é uma melhor maml:linkText prática, 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 tipos diferentes.

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 Get-History classe de 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 New-Calendar função

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 Start-Debug comando 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 do PowerShell, adicione um . Diretiva de comentário ExternalHelp para o código de fluxo de trabalho. O valor da diretiva 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 o . Diretiva ExternalHelp em um arquivo de fluxo de trabalho.

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