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)