about_Comment_Based_Help

  • Articolo

Descrizione breve

Viene descritto come scrivere argomenti della Guida basati su commenti per funzioni e script.

Descrizione lunga

È possibile scrivere argomenti della Guida basati su commenti per funzioni e script usando parole chiave speciali per i commenti della Guida.

Il cmdlet Get-Help visualizza la Guida basata su commenti nello stesso formato in cui vengono visualizzati gli argomenti della Guida dei cmdlet generati dai file XML. Gli utenti possono usare tutti i parametri di Get-Help, ad esempio Detailed, Full, Examples e Online, per visualizzare il contenuto della Guida basata su commenti.

È anche possibile scrivere file della Guida basati su XML per funzioni e script. Per abilitare il Get-Help cmdlet per trovare il file della Guida basato su XML per una funzione o uno script, usare la .ExternalHelp parola chiave . Senza questa parola chiave, Get-Help non è possibile trovare argomenti della Guida basati su XML per funzioni o script.

Questo argomento illustra come scrivere argomenti della Guida per funzioni e script. Per informazioni su come visualizzare gli argomenti della Guida per funzioni e script, vedere Get-Help.

I cmdlet Update-Help e Save-Help funzionano solo nei file XML. La Guida aggiornabile non supporta gli argomenti della Guida basata su commenti.

Sintassi per la Guida basata su commenti

La sintassi per la Guida basata su commenti è la seguente:

# .<help keyword>
# <help content>

or

<#
.<help keyword>
<help content>
#>

La Guida basata su commenti viene scritta come una serie di commenti. È possibile digitare un simbolo # di commento prima di ogni riga di commenti oppure utilizzare i <# simboli e #> per creare un blocco di commenti. Tutte le righe all'interno del blocco di commenti vengono interpretate come commenti.

Tutte le righe di un argomento della Guida basata su commenti devono essere contigue. Se un argomento della Guida basata su commenti segue un commento che non fa parte dell'argomento della Guida, deve essere presente almeno una riga vuota tra l'ultima riga di commento non della Guida e l'inizio della Guida basata su commenti.

Le parole chiave definiscono ogni sezione della Guida basata su commenti. Ogni parola chiave della Guida basata su commenti è preceduta da un punto .. Le parole chiave possono essere visualizzate in qualsiasi ordine. I nomi delle parole chiave non fanno distinzione tra maiuscole e minuscole.

Ad esempio, la .Description parola chiave precede una descrizione di una funzione o di uno script.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

Il blocco di commenti deve contenere almeno una parola chiave. Alcune parole chiave, ad esempio .EXAMPLE, possono essere visualizzate più volte nello stesso blocco di commenti. Il contenuto della Guida per ogni parola chiave inizia sulla riga dopo la parola chiave e può estendersi su più righe.

Sintassi per la Guida basata su commenti nelle funzioni

La Guida basata su commenti per una funzione può essere visualizzata in una delle tre posizioni seguenti:

  • All'inizio del corpo della funzione.
  • Alla fine del corpo della funzione.
  • Prima della function parola chiave . Non può essere presente più di una riga vuota tra l'ultima riga della Guida della funzione e la function parola chiave .

Ad esempio:

function Get-Function
{
<#
.<help keyword>
<help content>
#>

  # function logic
}

or

function Get-Function
{
   # function logic

<#
.<help keyword>
<help content>
#>
}

or

<#
.<help keyword>
<help content>
#>
function Get-Function { }

Sintassi per la Guida basata su commenti negli script

La Guida basata su commenti per uno script può essere visualizzata in una delle due posizioni seguenti nello script.

  • All'inizio del file di script. La Guida allo script può essere preceduta solo da commenti e righe vuote.

    Se il primo elemento nel corpo dello script (dopo la Guida) è una dichiarazione di funzione, devono essere presenti almeno due righe vuote tra la fine della Guida dello script e la dichiarazione di funzione. In caso contrario, la Guida viene interpretata come guida per la funzione, non come guida per lo script.

  • Alla fine del file di script. Tuttavia, se lo script è firmato, inserire la Guida basata su commento all'inizio del file di script. La fine dello script è occupata dal blocco di firma.

Ad esempio:

<#
.<help keyword>
<help content>
#>


function Get-Function { }

or

function Get-Function { }

<#
.<help keyword>
<help content>
#>

Sintassi per la Guida basata su commenti nei moduli di script

In un modulo .psm1script la Guida basata su commenti usa la sintassi per le funzioni, non la sintassi per gli script. Non è possibile usare la sintassi dello script per fornire informazioni su tutte le funzioni definite in un modulo script.

Ad esempio, se si usa la .ExternalHelp parola chiave per identificare i file della Guida basati su XML per le funzioni in un modulo script, è necessario aggiungere un .ExternalHelp commento a ogni funzione.

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

Parole chiave della Guida basata su commenti

Di seguito sono riportate parole chiave della Guida basate su commenti valide. Vengono elencati nell'ordine in cui vengono in genere visualizzati in un argomento della Guida insieme all'uso previsto. Queste parole chiave possono essere visualizzate in qualsiasi ordine nella Guida basata su commenti e non fanno distinzione tra maiuscole e minuscole.

.SYNOPSIS

Breve descrizione della funzione o dello script. Questa parola chiave può essere usata una sola volta in ogni argomento.

.DESCRIPTION

Descrizione dettagliata della funzione o dello script. Questa parola chiave può essere usata una sola volta in ogni argomento.

.PARAMETER

Descrizione di un parametro. Aggiungere una .PARAMETER parola chiave per ogni parametro nella sintassi della funzione o dello script.

Digitare il nome del parametro nella stessa riga della .PARAMETER parola chiave . Digitare la descrizione del parametro nelle righe che seguono la .PARAMETER parola chiave . Windows PowerShell interpreta tutto il testo tra la .PARAMETER riga e la parola chiave next o la fine del blocco di commenti come parte della descrizione del parametro. La descrizione può includere interruzioni di paragrafo.

.PARAMETER  <Parameter-Name>

Le parole chiave Parameter possono essere visualizzate in qualsiasi ordine nel blocco di commenti, ma la sintassi della funzione o dello script determina l'ordine in cui i parametri (e le relative descrizioni) vengono visualizzati nell'argomento della Guida. Per modificare l'ordine, modificare la sintassi.

È anche possibile specificare una descrizione del parametro inserendo un commento nella sintassi della funzione o dello script immediatamente prima del nome della variabile del parametro. Per il funzionamento di questa operazione, è necessario avere anche un blocco di commenti con almeno una parola chiave.

Se si usano sia un commento di sintassi che una .PARAMETER parola chiave, viene usata la .PARAMETER descrizione associata alla parola chiave e il commento della sintassi viene ignorato.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

Comando di esempio che usa la funzione o lo script, seguito facoltativamente dall'output di esempio e da una descrizione. Ripetere questa parola chiave per ogni esempio.

.INPUTS

Tipi .NET di oggetti che possono essere inviati tramite pipe alla funzione o allo script. È anche possibile includere una descrizione degli oggetti di input.

.OUTPUTS

Tipo .NET degli oggetti restituiti dal cmdlet. È anche possibile includere una descrizione degli oggetti restituiti.

.NOTES

Informazioni aggiuntive sulla funzione o sullo script.

Nome di un argomento correlato. Il valore viene visualizzato nella riga sotto la parola chiave ".LINK" e deve essere preceduto da un simbolo # di commento o incluso nel blocco di commento.

Ripetere la .LINK parola chiave per ogni argomento correlato.

Questo contenuto viene visualizzato nella sezione Collegamenti correlati dell'argomento della Guida.

Il contenuto della .Link parola chiave può includere anche un URI (Uniform Resource Identifier) in una versione online dello stesso argomento della Guida. La versione online viene aperta quando si usa il parametro Online di Get-Help. L'URI deve iniziare con "http" o "https".

.COMPONENT

Nome della tecnologia o della funzionalità usata dalla funzione o dallo script o da cui è correlata. Il parametro Component di Get-Help usa questo valore per filtrare i risultati della ricerca restituiti da Get-Help.

.ROLE

Nome del ruolo utente per l'argomento della Guida. Il parametro Role di Get-Help usa questo valore per filtrare i risultati della ricerca restituiti da Get-Help.

.FUNCTIONALITY

Parole chiave che descrivono l'uso previsto della funzione. Il parametro Functionality di Get-Help usa questo valore per filtrare i risultati della ricerca restituiti da Get-Help.

.FORWARDHELPTARGETNAME

Reindirizza all'argomento della Guida per il comando specificato. È possibile reindirizzare gli utenti a qualsiasi argomento della Guida, inclusi gli argomenti della Guida per una funzione, uno script, un cmdlet o un provider.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Specifica la categoria della Guida dell'elemento in .ForwardHelpTargetName. I valori validi sono Alias, Cmdlet, FunctionHelpFile, Provider, General, FAQ, Glossary, ScriptCommandExternalScriptFilter, , , o All. Usare questa parola chiave per evitare conflitti quando sono presenti comandi con lo stesso nome.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Specifica una sessione contenente l'argomento della Guida. Immettere una variabile contenente un oggetto PSSession . Questa parola chiave viene usata dal cmdlet Export-PSSession per trovare gli argomenti della Guida per i comandi esportati.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Specifica un file della Guida basato su XML per lo script o la funzione.

# .EXTERNALHELP <XML Help File>

La .ExternalHelp parola chiave è obbligatoria quando una funzione o uno script è documentato nei file XML. Senza questa parola chiave, Get-Help non è possibile trovare il file della Guida basato su XML per la funzione o lo script.

La .ExternalHelp parola chiave ha la precedenza su altre parole chiave della Guida basate su commenti. Se .ExternalHelp è presente, Get-Help non visualizza la Guida basata su commenti, anche se non riesce a trovare un argomento della Guida corrispondente al valore della .ExternalHelp parola chiave.

Se la funzione viene esportata da un modulo, impostare il valore della .ExternalHelp parola chiave su un nome file senza un percorso. Get-Help cerca il nome file specificato in una sottodirectory specifica della lingua della directory del modulo. Non sono previsti requisiti per il nome del file della Guida basata su XML per una funzione, ma è consigliabile usare il formato seguente:

<ScriptModule.psm1>-help.xml

Se la funzione non è inclusa in un modulo, includere un percorso al file della Guida basato su XML. Se il valore include un percorso e il percorso contiene sottodirectory specifiche delle impostazioni cultura dell'interfaccia utente, Get-Help cerca in modo ricorsivo un file XML con il nome dello script o della funzione in base agli standard di fallback del linguaggio stabiliti per Windows, proprio come avviene in una directory di moduli.

Per altre informazioni sul formato di file della Guida basata su XML del cmdlet, vedere How to Write Cmdlet Help.

Contenuto generato automaticamente

Il nome, la sintassi, l'elenco dei parametri, la tabella degli attributi dei parametri, i parametri comuni e le osservazioni vengono generati automaticamente dal Get-Help cmdlet .

Nome

La sezione Name di un argomento della Guida per le funzioni viene ricavata dal nome della funzione nella sintassi della funzione. Il nome di un argomento della Guida di script viene tratto dal nome del file di script. Per modificare il nome o la relativa maiuscola, modificare la sintassi della funzione o il nome file dello script.

Sintassi

La sezione Sintassi dell'argomento della Guida viene generata dalla sintassi della funzione o dello script. Per aggiungere dettagli alla sintassi dell'argomento della Guida, ad esempio il tipo .NET di un parametro, aggiungere i dettagli alla sintassi. Se non si specifica un tipo di parametro, il tipo Object viene inserito come valore predefinito.

Elenco parametri

L'elenco dei parametri nell'argomento della Guida viene generato dalla sintassi della funzione o dello script e dalle descrizioni aggiunte usando la .Parameter parola chiave . I parametri della funzione vengono visualizzati nella sezione Parametri dell'argomento della Guida nello stesso ordine in cui vengono visualizzati nella sintassi della funzione o dello script. Anche l'ortografia e la maiuscola dei nomi dei parametri vengono ricavati dalla sintassi. Non è interessato dal nome del parametro specificato dalla .Parameter parola chiave .

Parametri comuni

I parametri comuni vengono aggiunti all'elenco di parametri e sintassi dell'argomento della Guida, anche se non hanno alcun effetto. Per altre informazioni sui parametri comuni, vedere about_CommonParameters.

Tabella degli attributi dei parametri

Get-Help genera la tabella degli attributi dei parametri visualizzati quando si usa il parametro Full o Parameter di Get-Help. Il valore degli attributi Required, Position e Default viene ricavato dalla sintassi della funzione o dello script.

I valori predefiniti e un valore per Accetta caratteri jolly non vengono visualizzati nella tabella degli attributi dei parametri anche quando sono definiti nella funzione o nello script. Per aiutare gli utenti, fornire queste informazioni nella descrizione del parametro.

Osservazioni:

La sezione Osservazioni dell'argomento della Guida viene generata automaticamente dal nome della funzione o dello script. Non è possibile modificare o influire sul relativo contenuto.

Esempi

Guida basata su commenti per una funzione

La funzione di esempio seguente include la Guida basata su commenti:

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

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

I risultati sono i seguenti:

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You cannot pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Descrizioni dei parametri nella sintassi della funzione

Questo esempio è uguale a quello precedente, ad eccezione del fatto che le descrizioni dei parametri vengono inserite nella sintassi della funzione. Questo formato è più utile quando le descrizioni sono brevi.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Guida basata su commenti per uno script

Lo script di esempio seguente include la Guida basata su commenti. Si notino le righe vuote tra la chiusura #> e l'istruzione Param . In uno script che non dispone di un'istruzione Param , devono essere presenti almeno due righe vuote tra il commento finale nell'argomento della Guida e la prima dichiarazione di funzione. Senza queste righe vuote, Get-Help associa l'argomento della Guida alla funzione, non allo script.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

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

function Get-Data { }
...

Il comando seguente ottiene la Guida dello script. Poiché lo script non si trova in una directory elencata nella $env:Path variabile di ambiente, il Get-Help comando che ottiene la Guida dello script deve specificare il percorso dello script.

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

Reindirizzamento a un file XML

È possibile scrivere argomenti della Guida basati su XML per funzioni e script. Anche se la Guida basata su commenti è più semplice da implementare, è necessaria la Guida basata su XML per la Guida aggiornabile e fornire argomenti della Guida in più lingue.

L'esempio seguente mostra le prime righe dello script Update-Month.ps1. Lo script usa la .ExternalHelp parola chiave per specificare il percorso di un argomento della Guida basato su XML per lo script.

Si noti che il valore della .ExternalHelp parola chiave viene visualizzato nella stessa riga della parola chiave . Qualsiasi altro posizionamento è inefficace.

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

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

Gli esempi seguenti mostrano tre posizionamenti validi della .ExternalHelp parola chiave in una funzione.

function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml

param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

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

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

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

Reindirizzamento a un argomento della Guida diverso

Il codice seguente è un estratto dall'inizio della funzione della Guida predefinita in PowerShell, che visualizza una schermata di testo della Guida alla volta. Poiché l'argomento della Guida per il Get-Help cmdlet descrive la funzione della Guida, la funzione della Guida usa le .ForwardHelpTargetName parole chiave e .ForwardHelpCategory per reindirizzare l'utente all'argomento della Guida del Get-Help cmdlet.

function help
{

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

Il comando seguente usa questa funzionalità:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Vedi anche