Compartilhar via


about_comment_based_help

TÓPICO
    about_Comment_Based_Help

DESCRIÇÃO RESUMIDA
    Descreve como escrever tópicos da Ajuda baseados em comentários para 
    funções e scripts.

DESCRIÇÃO LONGA
    Você pode escrever tópicos da Ajuda baseados em comentários para 
    funções e scripts, usando palavras-chave especiais de comentário 
    de Ajuda. 

    O cmdlet Get-Help exibe Ajuda baseada em comentários no mesmo 
    formato em que exibe os tópicos da Ajuda do cmdlet que são 
    gerados de arquivos XML. Os usuários podem utilizar todos os 
    parâmetros de Get-Help, como Detailed, Full, Example e Online, 
    para exibir Ajuda de funções e de script.

    Você também pode escrever arquivos de Ajuda baseados em XML para 
    scripts e funções, usando palavras-chave de comentário de Ajuda, 
    e redirecionar os usuários para um arquivo de Ajuda diferente. 

    Este tópico explica como escrever tópicos da Ajuda para funções e 
    scripts. Para obter informações sobre como exibir tópicos da 
    Ajuda para funções e scripts, consulte Get-Help.


 SINTAXE PARA AJUDA BASEADA EM COMENTÁRIOS
    A sintaxe para a Ajuda baseada em comentários é a seguinte:
        #. <palavra-chave de ajuda>
        # <conteúdo da ajuda>
 
    -ou -

        <#
            .<palavra-chave de ajuda>
            <conteúdo da ajuda>
        #>


    A Ajuda baseada em comentários é escrita como uma série de 
    comentários. Você pode digitar um símbolo de comentário (#) antes 
    de cada linha de comentários ou usar os símbolos "<#" e "#>" para 
    criar um bloco de comentários. Todas as linhas dentro do bloco de 
    comentários são interpretadas como comentários.

    Todas as linhas em um tópico da Ajuda baseado em comentários 
    devem ser contíguas. Se um tópico da Ajuda baseado em comentários 
    suceder um comentário que não faz parte do tópico da Ajuda, deve 
    haver pelo menos uma linha em branco entre a última linha de 
    comentário que não seja de Ajuda e o início da Ajuda baseada em 
    comentários.

    As palavras-chave definem cada seção de Ajuda baseada em 
    comentários. Cada palavra-chave de Ajuda baseada em comentários é 
    precedida de um ponto (.). As palavras-chave podem aparecer em 
    qualquer ordem. Os nomes de palavras-chave não diferenciam 
    maiúsculas de minúsculas.

    Por exemplo, a palavra-chave Description precede uma descrição de 
    uma função ou um script.

        <#
        .Description
            Get-Function exibe o nome e a sintaxe de todas as funções 
            na sessão.
        #>

    O bloco de comentários precisa conter pelo menos uma 
    palavra-chave. Algumas palavras-chave, como EXAMPLE, podem 
    aparecer muitas vezes no mesmo bloco de comentários. O conteúdo 
    de Ajuda de cada palavra-chave começa na linha depois da 
    palavra-chave e pode abranger várias linhas. 



 SINTAXE PARA AJUDA BASEADA EM COMENTÁRIOS EM FUNÇÕES

    A Ajuda baseada em comentários para uma função pode aparecer em 
    um dos três seguintes locais:

        -- No começo do corpo da função.

        -- No fim do corpo da função.

        -- Antes da palavra-chave Function. Não pode haver mais de 
           uma linha em branco entre a última linha da Ajuda da 
           função e a palavra-chave Function. 

 

    Por exemplo:

        function MyFunction 
        {
            <#
            .<palavra-chave de ajuda>
            <conteúdo da ajuda>
            #>

            <comandos de função>
        }


    -ou -

        function MyFunction 
        {
            <comandos de função>

            <#
            .<palavra-chave de ajuda>
            <conteúdo da ajuda>
            #>
        }

    -ou -

        <#
        .<palavra-chave de ajuda>
        <conteúdo da ajuda>
        #>
        function MyFunction { }



 SINTAXE PARA AJUDA BASEADA EM COMENTÁRIOS EM SCRIPTS

    A Ajuda baseada em comentários para um script pode aparecer em um 
    dos dois seguintes locais no script.

    -- No começo do arquivo de script. A Ajuda de script só pode ser 
       precedida no script por comentários e linhas em branco. 

    -- Se o primeiro item no corpo do script (depois da Ajuda) for 
       uma declaração de função, deve haver pelo menos duas linhas em 
       branco entre o fim da Ajuda de script e a declaração de 
       função. Caso contrário, a Ajuda será interpretada como sendo 
       para a função, não para o script.

    -- No fim do arquivo de script.



    Por exemplo:

        <#
        .<palavra-chave de ajuda>
        <conteúdo da ajuda>
        #>


        function MyFunction { }

    -or-


        function MyFunction { }

        <#
        .<palavra-chave de ajuda>
        <conteúdo da ajuda>
        #>



 PALAVRAS-CHAVE DE AJUDA BASEADA EM COMENTÁRIOS
    A seguir, são apresentadas palavras-chave válidas de Ajuda 
    baseada em comentários. Elas são listadas na ordem em que aparecem 
    normalmente em um tópico da Ajuda, juntamente com seu uso pretendido.
    Essas palavras-chave aparecem em qualquer ordem na Ajuda baseada 
    em comentários e não diferenciam maiúsculas de minúsculas.


    .SYNOPSIS
        Uma breve descrição da função ou script. Essa palavra-chave 
        pode ser usada apenas uma vez em cada tópico.

    .DESCRIPTION
        Uma descrição detalhada da função ou do script. Essa 
        palavra-chave pode ser usada apenas uma vez em cada tópico.

    .PARAMETER <Nome-Parâmetro>
        A descrição de um parâmetro. Você pode incluir uma 
        palavra-chave Parameter de cada parâmetro na sintaxe da 
        função ou do script.

        As palavras-chave Parameter podem aparecer em qualquer ordem 
        no bloco de comentários, mas a sintaxe da função ou do script 
        determina a ordem na qual os parâmetros (e suas descrições) 
        aparecem no tópico da Ajuda. Para alterar a ordem, altere a 
        sintaxe.
 
        Você também pode especificar uma descrição de parâmetro 
        colocando um comentário na sintaxe da função ou do script, 
        imediatamente antes do nome da variável de parâmetro.
        Se você usar tanto um comentário de sintaxe como uma 
        palavra-chave Parameter, a descrição associada à 
        palavra-chave Parameter será usada e o comentário de sintaxe 
        será ignorado.

    .EXAMPLE
        Um comando de exemplo que usa a função ou o script, 
        opcionalmente seguido por uma saída de exemplo e uma 
        descrição. Repita essa palavra-chave para cada exemplo.

    .INPUTS
        Os tipos Microsoft .NET Framework de objetos que podem ser canalizados para a 
        função ou o script. Você também pode incluir uma descrição 
        dos objetos de entrada.

    .OUTPUTS
        O tipo .NET Framework dos objetos que o cmdlet retorna. Você também 
        pode incluir uma descrição dos objetos retornados.

    .NOTES
        Informações adicionais sobre a função ou o script.

    .LINK
        O nome de um tópico relacionado. Repita essa palavra-chave 
        para cada tópico relacionado.

        Esse conteúdo aparece na seção Links Relacionados do tópico 
        da Ajuda.

        O conteúdo da palavra-chave Link também pode incluir um URI 
        (Uniform Resource Identifier) para uma versão online do mesmo 
        tópico da Ajuda. A versão online abre quando você usa o parâmetro
        Online de Get-Help. O URI deve começar com "http" ou "https".

    .COMPONENT
        A tecnologia ou o recurso que a função ou o script usa ou com 
        que se relaciona. Esse conteúdo aparece quando o comando 
        Get-Help inclui o parâmetro Component de Get-Help.

    .ROLE
        A função de usuário para o tópico da Ajuda. Esse conteúdo é 
        exibido quando o comando Get-Help inclui o parâmetro Role de 
        Get-Help.

    .FUNCTIONALITY
        O uso planejado da função. Esse conteúdo aparece quando o 
        comando Get-Help inclui o parâmetro Functionality de Get-Help.

    .FORWARDHELPTARGETNAME <Nome-Comando>
        Redireciona para o tópico da Ajuda do comando especificado. 
        Você pode redirecionar os usuários para qualquer tópico da 
        Ajuda, inclusive tópicos da Ajuda de uma função, um script, 
        um cmdlet ou um provedor. 

    .FORWARDHELPCATEGORY <Categoria>
        Especifica a categoria da Ajuda do item em ForwardHelpTargetName.
        Os valores válidos são Alias, Cmdlet, HelpFile, Function, 
        Provider, General, FAQ, Glossary, ScriptCommand, 
        ExternalScript, Filter ou All. Use essa palavra-chave para 
        evitar conflitos quando houver comandos com o mesmo nome.

    .REMOTEHELPRUNSPACE <variável-PSSession>
        Especifica uma sessão que contém o tópico da Ajuda. Insira 
        uma variável que contém uma PSSession. Essa palavra-chave é 
        usada pelo cmdlet Export-PSSession para localizar os tópicos 
        da Ajuda para comandos exportados.

    .EXTERNALHELP <Caminho do arquivo de ajuda XML>
        Especifica o caminho de um arquivo de Ajuda baseado em XML 
        para o script ou a função. 

        No Windows Vista e em versões posteriores do Windows, se o 
        caminho especificado do arquivo XML contiver subdiretórios 
        específicos da cultura de interface do usuário, o Get-Help 
        pesquisará um arquivo XML com o nome do script ou da função 
        nos subdiretórios recursivamente, de acordo com padrões de 
        fallback de idioma estabelecidos para o Windows Vista, da 
        mesma maneira que é feito com todos os tópicos da Ajuda 
        baseados em XML. 

        Para obter mais informações sobre o formato de arquivo de 
        Ajuda baseada em XML do cmdlet, consulte "How to Create 
        Cmdlet Help" (em inglês) na biblioteca do MSDN (Microsoft 
        Developer Network) em https://go.microsoft.com/fwlink/?LinkID=123415
        (site em inglês).


 CONTEÚDO GERADO AUTOMATICAMENTE
    O nome, a sintaxe, a lista de parâmetros, a tabela de atributos 
    do parâmetro, os parâmetros comuns e os comentários são gerados 
    automaticamente pelo cmdlet Get-Help.

        Nome: 
            A seção Nome do tópico da Ajuda de uma função é obtida do 
            nome da função na sintaxe de função. O Nome do tópico da 
            Ajuda de um script é obtido do nome de arquivo do script. 
            Para alterar o nome ou sua capitalização, altere a 
            sintaxe da função ou o nome de arquivo do script.
 
        Sintaxe: 
            A seção Sintaxe do tópico da Ajuda é gerada pela sintaxe 
            da função ou do script. Para adicionar detalhes à sintaxe 
            do tópico da Ajuda, como o tipo .NET Framework de um parâmetro, 
            adicione os detalhes à sintaxe. Se você não especificar 
            um tipo de parâmetro, o tipo "Object" será inserido como 
            valor padrão.

        Lista de parâmetros: 
            A Lista de parâmetros no tópico da Ajuda é gerada pela 
            sintaxe da função ou do script e pelas descrições que 
            você adiciona usando a palavra-chave Parameters. Os 
            parâmetros de função são mostrados na seção "Parâmetros" do 
            tópico da Ajuda na mesma ordem que aparecem na sintaxe da 
            função ou do script. A ortografia e a capitalização de 
            nomes de parâmetros também são obtidas da sintaxe; elas 
            não são afetadas pelo nome do parâmetro especificado pela 
            palavra-chave Parameter. 

        Parâmetros comuns: 
            Os parâmetros comuns são adicionados à sintaxe e à lista 
            de parâmetros do tópico da Ajuda, mesmo que não tenham 
            efeito. Para obter mais informações sobre os parâmetros 
            comuns, consulte about_CommonParameters.

        Tabela de atributos de parâmetro: 
            Get-Help gera a tabela de atributos de parâmetro que é 
            exibida quando você usa os parâmetros Full ou Parameter 
            de Get-Help. O valor dos atributos de valor Required, 
            Position e Default são obtidos da sintaxe da função ou do 
            script. 

        Comentários: 
            A seção Comentários do tópico da Ajuda é automaticamente 
            gerada pelo nome da função ou do script. Você não pode 
            alterar ou afetar seu conteúdo.



 EXEMPLOS

    Exemplo 1: Ajuda baseada em comentários de uma função

        O exemplo de função a seguir inclui Ajuda baseada em comentários:

            function Add-Extension 
            {
                param ([string]$Name,[string]$Extension = "txt") 
                $name = $name + "." + $extension 
        $name

            <#
            .SYNOPSIS 
            Adiciona uma extensão de nome de arquivo a um nome fornecido.

            .DESCRIPTION
            Adiciona uma extensão de nome de arquivo a um nome 
            fornecido. Obtém qualquer cadeia de caracteres para o 
            nome ou a extensão do arquivo.

            .PARAMETER Name
            Especifica o nome do arquivo.

            .PARAMETER Extension
            Especifica a extensão. "Txt" é o padrão.

            .INPUTS
            Nenhum. Não é possível canalizar objetos para Add-Extension.

            .OUTPUTS
            System.String. Add-Extension retorna uma cadeia de 
            caracteres com a extensão ou o nome de arquivo.

            .EXAMPLE
            C:\PS> extension -name "Arquivo"
            Arquivo.txt

            .EXAMPLE
            C:\PS> extension -name "Arquivo" -extension "doc"
            Arquivo.doc

            .EXAMPLE
            C:\PS> extension "Arquivo" "doc"
            Arquivo.doc

            .LINK
            Versão online: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
            }



        Os resultados são os seguintes:

        C:\PS> get-help add-extension -full

        NOME
            Add-Extension
    
        SINOPSE
            Adiciona uma extensão de nome de arquivo a um nome fornecido.
    
        SINTAXE
            Add-Extension [[-Name] <Cadeia de caracteres>] 
            [[-Extension] <Cadeia de caracteres>] [<CommonParameters>] 

        DESCRIÇÃO
            Adiciona uma extensão de nome de arquivo a um nome 
            fornecido. Obtém qualquer cadeia de caracteres para o 
            nome ou a extensão do arquivo.
    
        PARÂMETROS
           -Name
               Especifica o nome do arquivo.
        
               Necessário?                    false
               Posição?                       0
               Valor padrão                
               Aceitar entrada do pipeline?   false
               Aceitar caracteres curinga?  
        
           -Extension
               Especifica a extensão. "Txt" é o padrão.
        
               Necessário?                    false
               Posição?                       1
               Valor padrão                
               Aceitar entrada do pipeline?   false
               Aceitar caracteres curinga?  
        
            <CommonParameters>
               Esse cmdlet oferece suporte aos parâmetros comuns: 
               -Verbose, -Debug, -ErrorAction, -ErrorVariable, 
               -WarningAction, -WarningVariable, -OutBuffer e 
               -OutVariable. Para obter mais informações, digite 
               "get-help about_commonparameters".
    

        ENTRADAS
            Nenhum. Não é possível canalizar objetos para Add-Extension.
    
        SAÍDAS
            System.String. Add-Extension retorna uma cadeia de 
            caracteres com a extensão ou o nome de arquivo.
        
            -------------------------- EXEMPLO 1 -------------------------- 

            C:\PS> extension -name "Arquivo"
            Arquivo.txt
    
            -------------------------- EXEMPLO 2 -------------------------- 

            C:\PS> extension -name "Arquivo" -extension "doc"
            Arquivo.doc
    
            -------------------------- EXEMPLO 3 -------------------------- 

            C:\PS> extension "Arquivo" "doc"
            Arquivo.doc
    
        LINKS RELACIONADOS
            Versão online: http://www.fabrikam.com/extension.html Set-Item



    Exemplo 2: Descrições de parâmetro na sintaxe de função

        Este exemplo é igual ao anterior, a não ser pelo fato de que 
        as descrições de parâmetro são inseridas na sintaxe de 
        função. Este formato é mais útil quando as descrições são breves. 


        function Add-Extension 
        {
            param 
            (
                [string]
                # Especifica o nome do arquivo.
                $name,

                [string]
                # Especifica a extensão do nome do arquivo. \\"Txt\\" é o padrão.
                $extension = "txt"
            )
            $name = $name + "." + $extension
            $name
      
            <#
            .SYNOPSIS 
            Adiciona uma extensão de nome de arquivo a um nome fornecido.

            .DESCRIPTION
            Adiciona uma extensão de nome de arquivo a um nome 
            fornecido. Obtém qualquer cadeia de caracteres para o 
            nome ou a extensão do arquivo.

            .INPUTS
            Nenhum. Não é possível canalizar objetos para Add-Extension.

            .OUTPUTS
            System.String. Add-Extension retorna uma cadeia de 
            caracteres com a extensão ou o nome de arquivo.

            .EXAMPLE
            C:\PS> extension -name "Arquivo"
            Arquivo.txt

            .EXAMPLE
            C:\PS> extension -name "Arquivo" -extension "doc"
            Arquivo.doc

            .EXAMPLE
            C:\PS> extension "Arquivo" "doc"
            Arquivo.doc
 
            .LINK
            Versão online: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
        }




    Exemplo 3: Ajuda baseada em comentários de um script

        O exemplo de script a seguir inclui Ajuda baseada em comentários. 

        Observe as linhas em branco entre o "#>" de fechamento e a 
        instrução Param. Em um script que não tem uma instrução 
        Param, precisa haver pelo menos duas linhas em branco entre o 
        comentário final no tópico da Ajuda e a primeira declaração 
        de função. Sem essas linhas em branco, Get-Help associa o 
        tópico da Ajuda à função, não ao script.

           <#
           .SYNOPSIS 
           Executa atualizações de dados mensais.

           .DESCRIPTION
           O script Update-Month.ps1 atualiza o Registro com novos 
           dados gerados durante o mês passado e gera um relatório.
    
           .PARAMETER InputPath
           Especifica o caminho para o arquivo de entrada baseado em CSV.

           .PARAMETER OutputPath
           Especifica o nome e o caminho do arquivo de saída baseado 
           em CSV. Por padrão, MonthlyUpdates.ps1 gera um nome com 
           base na data e na hora em que é executado e salva a saída 
           no diretório local.

           .INPUTS
           Nenhum. Você não pode canalizar objetos para Update-Month.ps1.

           .OUTPUTS
           Nenhum. Update-Month.ps1 não gera saída.

           .EXAMPLE
           C:\PS> .\Update-Month.ps1

           .EXAMPLE
           C:\PS> .\Update-Month.ps1 -inputpath C:\Dados\Janeiro.csv

           .EXAMPLE
           C:\PS> .\Update-Month.ps1 -inputpath C:\Dados\Janeiro.csv 
           -outputPath C:\Relatórios\2009\Janeiro.csv
           #>

           param ([string]$InputPath, [string]$OutPutPath)

           function Get-Data { }
           ...


        O comando a seguir obtém a Ajuda de script. Como o script não 
        está em um diretório listado na variável de ambiente Path, o 
        comando Get-Help que obtém a Ajuda de script precisa 
        especificar o caminho do script.


            PS C:\ps-test> get-help .\update-month.ps1 -full

            NOME
                C:\ps-test\Update-Month.ps1
    
            SINOPSE
                Executa atualizações de dados mensais.
    
            SINTAXE
                C:\ps-test\Update-Month.ps1 [-InputPath] <Cadeia de 
                caracteres> [[-OutputPath] ]<Cadeia de caracteres>] 
                [<CommonParameters>]
    
            DESCRIÇÃO
                O script Update-Month.ps1 atualiza o Registro com 
                novos dados gerados durante o mês passado e gera um 
                relatório.
    
            PARÂMETROS
        -InputPath
                   Especifica o caminho para o arquivo de entrada 
                   baseado em CSV.
        
                   Necessário?                    verdadeiro
                   Posição?                       0
                   Valor padrão                
                   Aceitar entrada do pipeline?   false
                   Aceitar caracteres curinga?  
        
               -OutputPath
                   Especifica o nome e o caminho do arquivo de saída 
                   baseado em CSV. Por padrão, MonthlyUpdates.ps1 
                   gera um nome com base na data e na hora em que é 
                   executado e salva a saída no diretório local.
        
                   Necessário?                    false
                   Posição?                       1
                   Valor padrão                
                   Aceitar entrada do pipeline?   false
                   Aceitar caracteres curinga?  

               <CommonParameters>
                   Esse cmdlet oferece suporte aos parâmetros comuns: 
                   -Verbose, -Debug, -ErrorAction, -ErrorVariable, 
                   -WarningAction, -WarningVariable, -OutBuffer e 
                   -OutVariable. Para obter mais informações, 
                   digite "get-help about_commonparameters".
    
            ENTRADAS
                   Nenhum. Você não pode canalizar objetos para 
                   Update-Month.ps1.
    
            SAÍDAS
                   Nenhum. Update-Month.ps1 não gera saída.
    
    
            -------------------------- EXEMPLO 1 -------------------------- 

            C:\PS> .\Update-Month.ps1
    
            -------------------------- EXEMPLO 2 --------------------------
 
            C:\PS> .\Update-Month.ps1 -inputpath C:\Dados\Janeiro.csv
    
            -------------------------- EXEMPLO 3 -------------------------- 

            C:\PS> .\Update-Month.ps1 -inputpath C:\Dados\Janeiro.csv -outputPath 
            C:\Relatórios\2009\Janeiro.csv
        
            LINKS RELACIONADOS



    Exemplo 4: redirecionando para um arquivo XML

        Você pode escrever tópicos da Ajuda baseados em XML para 
        funções e scripts. Embora a Ajuda baseada em comentários seja 
        mais fácil de implementar, a Ajuda baseada em XML é 
        necessária se você deseja um controle mais preciso sobre o 
        conteúdo de Ajuda ou se você está traduzindo tópicos da 
        Ajuda em vários idiomas. 

        O exemplo a seguir mostra as primeiras poucas linhas do 
        script Update-Month.ps1. O script usa a palavra-chave 
        ExternalHelp para especificar o caminho de um tópico da Ajuda 
        baseado em XML para o script.


            # .ExternalHelp C:\MyScripts\Update-Month-Help.xml


            param ([string]$InputPath, [string]$OutPutPath)

            function Get-Data { }
            ...



       O exemplo a seguir mostra o uso da palavra-chave ExternalHelp 
       em uma função.


            function Add-Extension 
            {
                param ([string] $name, [string]$extension = "txt") 
                $name = $name + "." + $extension $name
      
                # .ExternalHelp C:\ps-test\Add-Extension.xml 
        }


    Exemplo 5: redirecionando para um tópico da Ajuda diferente

        O código a seguir é um trecho do início da função Help 
        interna no Windows PowerShell, que exibe uma tela de texto de 
        Ajuda de cada vez. Como o tópico da Ajuda para o cmdlet 
        Get-Help descreve a função Help, a função Help usa as 
        palavras-chave ForwardHelpTargetName e ForwardHelpCategory 
        para redirecionar o usuário para o tópico da Ajuda do cmdlet 
        Get-Help.

            function help 
            {

            <#
            .FORWARDHELPTARGETNAME Get-Help
            .FORWARDHELPCATEGORY Cmdlet
            #>
            [CmdletBinding (DefaultParameterSetName='AllUsersView)] 
            param (
                [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
                [System.String]
                ${Name},
                   ...


        O comando a seguir usa este recurso:

            C:\PS> get-help help

            NOME
                Get-Help

            SINOPSE
                Exibe informações sobre cmdlets e conceitos do 
                Windows PowerShell.
            ...


CONSULTE TAMBÉM
    about_Functions
    about_Functions_Advanced_Parameters
    about_Scripts
    "Como escrever ajuda de cmdlet"  (https://go.microsoft.com/fwlink/?LinkID=123415)