about_Aiuto_Basato_su_Commenti

Breve descrizione

Descrive come scrivere contenuto di aiuto basato su commenti per funzioni e script.

Descrizione lunga

È possibile scrivere contenuto della Guida basato 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 visualizza il contenuto della Guida del cmdlet generato dai file XML. Gli utenti possono usare tutti i parametri di Get-Help, ad esempio Detailed, Full, Examplese 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 cmdlet Get-Help per trovare il file della Guida basato su XML per una funzione o uno script, usare la parola chiave .EXTERNALHELP. Senza questa parola chiave, Get-Help non può trovare contenuti di aiuto basati su XML per funzioni o script.

Questo argomento illustra come scrivere contenuto della Guida per funzioni e script. Per informazioni su come visualizzare il contenuto 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 i contenuti basati su commenti.

Sintassi per la guida basata su commenti

Per creare contenuti della guida basati su commenti, è possibile utilizzare entrambi gli stili di commenti: commenti a riga singola o commenti a blocco.

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

# .<help keyword>
# <help content>

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

Guida basata sui 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 parola chiave .DESCRIPTION precede una descrizione di una funzione o 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 parola chiave function. Non può essere presente più di una riga vuota tra l'ultima riga della Guida della funzione e la parola chiave function.

Per esempio:

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

    # function logic
}

function Get-Function {
    # function logic

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

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

Sintassi per la Guida basata su commenti negli script

L'aiuto basato su commenti per uno script può apparire in una delle due posizioni seguenti nello script.

All'inizio del file di script. L'assistenza script può essere preceduta nello script 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, l'aiuto viene interpretato come aiuto per la funzione e non per lo script.
Alla fine del file di script. Tuttavia, se lo script è firmato, inserisci la guida basata su commenti all'inizio del file di script. La fine dello script è occupata dal blocco di firma.

Per esempio:

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

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

Parole chiave di aiuto basate su commenti

Di seguito sono riportate parole chiave della Guida basate su commenti valide. Queste parole chiave possono apparire in qualsiasi ordine nella guida basata su commenti e non sono sensibili alle maiuscole e minuscole. Le parole chiave sono elencate in questo articolo nell'ordine in cui vengono in genere visualizzate in un argomento della Guida.

.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 parola chiave .PARAMETER per ogni parametro nella sintassi della funzione o dello script.

Digitare il nome del parametro nella stessa riga della parola chiave .PARAMETER. Digitare la descrizione del parametro nelle righe che seguono la parola chiave .PARAMETER. Windows PowerShell interpreta tutto il testo tra la riga .PARAMETER e la parola chiave next o la fine del blocco di commento 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 parola chiave .PARAMETER, viene usata la descrizione associata alla parola chiave .PARAMETER 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. Ripetere questa parola chiave per ogni tipo di input.

`.OUTPUTS`

Tipo .NET degli oggetti restituiti dal cmdlet. È anche possibile includere una descrizione degli oggetti restituiti. Ripetere questa parola chiave per ogni tipo di output.

`.NOTES`

Informazioni aggiuntive sulla funzione o sullo script.

`.LINK`

Nome di un argomento correlato. Ripetere questa parola chiave per ogni argomento correlato. Questo contenuto viene visualizzato nella sezione Collegamenti correlati dell'argomento della Guida.

Il contenuto della parola chiave .LINK 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 componente di usa questo valore per filtrare i risultati della ricerca restituiti da .

`.ROLE`

Nome del ruolo dell'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 funzionalità di usa questo valore per filtrare i risultati della ricerca restituiti da .

`.FORWARDHELPTARGETNAME <Command-Name>`

Reindirizza all'argomento della Guida per il comando specificato. È possibile reindirizzare gli utenti a qualsiasi argomento della Guida, incluso il contenuto 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, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filtero All. Usare questa parola chiave per evitare conflitti quando sono presenti comandi con lo stesso nome.

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

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 i contenuti della guida per i comandi esportati.

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

Specifica un file di aiuto basato su XML per lo script o la funzione.

# .EXTERNALHELP <XML Help File>

La parola chiave .EXTERNALHELP è necessaria quando una funzione o uno script è documentato nei file XML. Senza questa keyword, Get-Help non riesce a trovare il file di aiuto basato su XML per la funzione o lo script.

La parola chiave .EXTERNALHELP 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 parola chiave .EXTERNALHELP.

Se la funzione viene esportata da un modulo, impostare il valore della parola chiave .EXTERNALHELP 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 basato su XML per una funzione. A partire da PowerShell 5.0, le funzioni esportate da un modulo possono essere documentate in un file della Guida denominato per il modulo. Non è necessario usare la .EXTERNALHELP parola chiave comment. Ad esempio, se la Test-Function funzione viene esportata dal MyModule modulo, è possibile denominare il file MyModule-help.xmldella Guida . Il Get-Help cmdlet cerca la Guida per la Test-Function funzione nel MyModule-help.xml file nella directory del modulo.

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

Per ulteriori informazioni sul formato di file della Guida del cmdlet basata su XML, vedere Come scrivere la Guida del Cmdlet.

Contenuto generato automaticamente

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

Nome

La sezione Nome di un argomento della guida alla funzione deriva dal nome della funzione nella sintassi della funzione. Il nome di un argomento della guida di script viene ricavato dal nome dello 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 di un argomento della Guida, come ad esempio il tipo .NET di un parametro, includerli nella sintassi. Se non si specifica un tipo di parametro, il tipo Object viene inserito come valore predefinito.

Elenco di parametri

L'elenco dei parametri nell'argomento della Guida viene generato dalla sintassi della funzione o dello script e dalle descrizioni che aggiungi utilizzando la parola chiave .PARAMETER. 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 è influenzato dal nome del parametro specificato dalla parola chiave .PARAMETER.

Parametri comuni

I parametri comuni vengono aggiunti alla sintassi e all'elenco di parametri dell'argomento dell'aiuto, 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 che appare quando si utilizza il parametro Full o il parametro Parameter di Get-Help. Il valore degli attributi Required, Positione Valore predefinito 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 l'aiuto basato 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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 can't pipe objects to Add-Extension.

OUTPUTS

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

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

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

.LINK

Set-Item
#>
}

Guida basata sui commenti per uno script

Lo script di esempio seguente include la guida basata su commenti. Si notino le righe vuote tra la #> di 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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't 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 variabile di ambiente $Env:PATH, il comando Get-Help 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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't 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 contenuti di aiuto basati su XML per funzioni e script. Anche se la Guida basata su commenti è più semplice da implementare, la Guida basata su XML è necessaria per la Guida aggiornabile e per fornire contenuto della Guida in più lingue.

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

Si noti che il valore della parola chiave .EXTERNALHELP 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 parola chiave .EXTERNALHELP 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 Guida predefinita in PowerShell, che visualizza il testo di aiuto una schermata alla volta. Poiché l'argomento della Guida per il cmdlet Get-Help descrive la funzione della Guida, la funzione della Guida usa le parole chiave .FORWARDHELPTARGETNAME e .FORWARDHELPCATEGORY per reindirizzare l'utente all'argomento della Guida del cmdlet Get-Help.

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

Vedere anche

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-05-21