about_Comment_Based

ARGOMENTO
about_Comment_Based_Help

DESCRIZIONE BREVE
Viene descritta la modalità di scrittura della Guida basata su commenti relativa a
funzioni e script.

DESCRIZIONE DETTAGLIATA
È possibile scrivere una Guida basata su commenti relativa a
funzioni e script mediante parole chiave commento speciali.

Il cmdlet Get-Help visualizza la Guida basata su commenti nello
stesso formato nel quale visualizza la Guida del cmdlet generata
da file XML. Gli utenti possono utilizzare tutti i parametri di
Get-Help, ad esempio Detailed, Full, Example e Online, per
visualizzare la Guida relativa a funzioni e script.

È inoltre possibile scrivere file della Guida basati su XML per
script e funzioni mediante parole chiave commento e reindirizzare
gli utenti a un file della Guida diverso.

In questo argomento viene illustrato come scrivere la Guida per
funzioni e script. Per informazioni su come visualizzare la Guida
per funzioni e script, vedere Get-Help.

SINTASSI PER LA GUIDA BASATA SU COMMENTI
La sintassi per la Guida basata su commenti è la seguente:
# .< parola chiave guida>
# <contenuto guida>

-oppure

<#
.< parola chiave guida>
< contenuto guida>
#>

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 commento. Tutte le righe all'interno del
blocco di commento 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, deve
essere presente almeno una riga vuota tra l'ultima riga di
commento non appartenente alla 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
disposte in qualsiasi ordine e i relativi nomi non fanno
distinzione tra maiuscole e minuscole.

La parola chiave Description, ad esempio, precede una descrizione
di una funzione o di uno script.

<#
.Description
Get-Function visualizza il nome e la sintassi di tutte le
funzioni nella sessione.
#>

Il blocco di commento deve contenere almeno una parola chiave.
Alcune delle parole chiave, ad esempio EXAMPLE, possono comparire
molte volte nello stesso blocco di commento. Il contenuto della
Guida per ogni parola chiave inizia dalla 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 relativa a una funzione può essere
visualizzata in una di tre diverse posizioni:

-- All'inizio del corpo della funzione.

-- Alla fine del corpo della funzione.

-- Prima della parola chiave Function. Tra l'ultima riga
della Guida relativa alla funzione e la parola chiave
Function non può essere presente più di una riga vuota.

Ad esempio:

function MyFunction
{
<#
.< parola chiave guida>
< contenuto guida>
#>

<comandi funzione>
}

-oppure

function MyFunction
{
<comandi funzione>

<#
.< parola chiave guida>
< contenuto guida>
#>
}

-oppure

<#
.< parola chiave guida>
< contenuto guida>
#>
function MyFunction { }

SINTASSI PER LA GUIDA BASATA SU COMMENTI NEGLI SCRIPT

La Guida basata su commenti relativa a uno script può essere
visualizzata in una delle due posizioni seguenti all'interno
dello script.

-- All'inizio del file di script. Nello script la Guida relativa
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 relativa allo script e
la dichiarazione di funzione. In caso contrario, la Guida
verrà interpretata come Guida relativa alla funzione, non allo
script.

-- Alla fine del file di script.

Ad esempio:

<#
.< parola chiave guida>
< contenuto guida>
#>

function MyFunction { }

-oppure-

function MyFunction { }

<#
.< parola chiave guida>
< contenuto guida>
#>

PAROLE CHIAVE DELLA GUIDA BASATA SU COMMENTI
Di seguito sono elencate le parole chiave della Guida basata su
commenti valide. Queste sono disposte nell'ordine in cui vengono visualizzate
in un argomento della Guida, insieme alla descrizione del loro
utilizzo 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 utilizzata una sola volta in ogni
argomento.

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

.PARAMETER <Nome-Parametro>
Descrizione di un parametro. È possibile includere una parola
chiave Parameter per ogni parametro nella sintassi della
funzione o dello script.

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

È inoltre possibile specificare una descrizione di parametro
posizionando un commento nella sintassi della funzione o
dello script immediatamente prima del nome della variabile
del parametro.
Se si utilizza un commento di sintassi e una parola chiave
Parameter, viene utilizzata la descrizione associata alla
parola chiave Parameter e il commento di sintassi viene ignorato.

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

.INPUTS
Tipi Microsoft .NET Framework di oggetti che è possibile reindirizzare alla
funzione o allo script. È inoltre possibile includere una
descrizione degli oggetti di input.

.OUTPUTS
Tipo .NET Framework degli oggetti restituiti dal cmdlet. È inoltre
possibile includere una descrizione degli oggetti restituiti.

.NOTES
Informazioni aggiuntive sulla funzione o sullo script.

.LINK
Nome di un argomento correlato. Ripetere questa parola chiave
per ogni argomento correlato.

Contenuto che viene visualizzato nella sezione Collegamenti
correlati dell'argomento della Guida.

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

.COMPONENT
Tecnologia o funzionalità utilizzata dalla funzione o dallo
script o a cui è correlato. Contenuto che viene visualizzato
quando il comando Get-Help include il parametro Component di
Get-Help.

.ROLE
Ruolo utente per l'argomento della Guida. Contenuto che viene
visualizzato quando il comando Get-Help include il parametro
Role di Get-Help.

.FUNCTIONALITY
Utilizzo previsto della funzione. Contenuto che viene
visualizzato quando il comando Get-Help include il parametro
Functionality di Get-Help.

.FORWARDHELPTARGETNAME <Command-Name>
Reindirizza l'utente all'argomento della Guida relativo al
comando specificato. È possibile reindirizzare gli utenti a
qualsiasi argomento della Guida, inclusi gli argomenti
relativi a una funzione, script, cmdlet o provider.

.FORWARDHELPCATEGORY <Categoria>
Specifica la categoria della Guida dell'elemento in
ForwardHelpTargetName.
I valori validi sono Alias, Cmdlet, HelpFile, Function,
Provider, General, FAQ, Glossary, ScriptCommand,
ExternalScript, Filter o All. Utilizzare questa parola chiave
per evitare conflitti in presenza di comandi con lo stesso nome.

.REMOTEHELPRUNSPACE <variabile-PSSession>
Specifica una sessione che contiene l'argomento della Guida.
Immettere una variabile che contiene PSSession. Questa parola
chiave viene utilizzata dal cmdlet Export-PSSession per
trovare gli argomenti della Guida relativi ai comandi esportati.

.EXTERNALHELP <Percorso file della Guida XML>
Specifica il percorso del file della Guida basato su XML
relativo allo script o alla funzione.

In Windows Vista e nelle versioni successive di Windows, se
il percorso specificato del file XML contiene sottodirectory
specifiche di impostazioni cultura relative all'interfaccia
utente, le sottodirectory ricercano in modo ricorsivo un file
XML con il nome dello script o della funzione in base agli
standard del fallback della lingua stabiliti per Windows
Vista, allo stesso modo in cui ricercano gli argomenti della
Guida basata su XML.

Per ulteriori informazioni sul formato del file della Guida basata su XML
del cmdlet, vedere l'argomento relativo alla creazione della Guida dei cmdlet
in MSDN (Microsoft Developer Network) Library all'indirizzo https://go.microsoft.com/fwlink/?LinkID=123415 (le informazioni potrebbero
essere in lingua inglese).

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

Nome:
La sezione nome di un argomento della Guida relativo a
una funzione deriva dal nome della funzione specificato
nella sintassi relativa. Il nome di un argomento della
Guida relativo a uno script deriva dal nome del file di
script. Per modificare il nome o la relativa distinzione
tra maiuscole e minuscole, modificare la sintassi della
funzione o il nome del file di script.

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

Elenco dei parametri:
L'elenco dei parametri nell'argomento della Guida viene
generato dalla sintassi della funzione o dello script e
dalle descrizioni aggiunte mediante la parola chiave
Parameters. I parametri della funzione sono contenuti
nella sezione "Parametri" dell'argomento della Guida
nello stesso ordine in cui vengono visualizzati nella
sintassi dello script o della funzione. Anche
l'ortografia e la distinzione tra maiuscole e minuscole
dei nomi dei parametri derivano dalla sintassi e non
dipendono dal nome del parametro specificato dalla parola
chiave Parameter.

Parametri comuni:
I parametri comuni vengono aggiunti alla sintassi e
all'elenco dei parametri dell'argomento della Guida,
anche se non producono alcun effetto. Per ulteriori informazioni
sui parametri comuni, vedere about_CommonParameters.

Tabella degli attributi dei parametri:
Get-Help genera la tabella degli attributi dei parametri
che viene visualizzata quando si utilizza il parametro
Full o Parameter di Get-Help. Il valore degli attributi
Required, Position e Default deriva dalla sintassi
della funzione o dello script.

Commenti:
La sezione commenti dell'argomento della Guida viene
generata automaticamente dal nome dello script o della
funzione. Non è possibile modificare il contenuto di
questa sezione.

ESEMPI

Esempio 1: Guida basata su commenti relativa a una funzione

Nella funzione di esempio seguente è inclusa una Guida basata
su commenti:

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

<#
.SYNOPSIS
Aggiunge un'estensione di file a un nome fornito.

.DESCRIPTION
Aggiunge un'estensione di file a un nome fornito. Accetta
qualsiasi stringa per il nome o l'estensione di file.

.PARAMETER Name
Specifica il nome del file.

.PARAMETER Extension
Specifica l'estensione di file. "Txt" è l'estensione predefinita.

.INPUTS
Nessuno. Non è possibile reindirizzare oggetti a
Add-Extension.

.OUTPUTS
System.String. Add-Extension restituisce una stringa con
il nome o l'estensione di file.

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

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

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

.LINK
Versione online: http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Di seguito sono illustrati i risultati:

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

NOME
Add-Extension

SYNOPSIS
Aggiunge un'estensione di file a un nome fornito.

SINTASSI
Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]
DESCRIZIONE
Aggiunge un'estensione di file a un nome fornito. Accetta
qualsiasi stringa per il nome o l'estensione di file.

PARAMETRI
-Name
Specifica il nome del file.

Required? false
Position? 0
Valore predefinito
Accept pipeline input? false
Accept wildcard characters?

-Extension
Specifica l'estensione. "Txt" è l'estensione predefinita.

Required? false
Position? 1
Valore predefinito
Accept pipeline input? false
Accept wildcard characters?

<CommonParameters>
Questo cmdlet supporta i parametri comuni -Verbose,
-Debug, ErrorAction, -ErrorVariable, -WarningAction,
-WarningVariable, OutBuffer e -OutVariable. Per
ulteriori informazioni, digitare "get-help
about_commonparameters".

INPUTS
Nessuno. Non è possibile reindirizzare oggetti a
Add-Extension.

OUTPUTS
System.String. Add-Extension restituisce una stringa con
il nome o l'estensione di file.

-------------------------- ESEMPIO 1 --------------------------
C:\PS> extension -name "File"
File.txt

-------------------------- ESEMPIO 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc

-------------------------- ESEMPIO 3 --------------------------
C:\PS> extension "File" "doc"
File.doc

COLLEGAMENTI CORRELATI
Versione online: http://www.fabrikam.com/extension.html
Set-Item

Esempio 2: Descrizioni dei parametri nella sintassi della funzione

Questo esempio corrisponde al precedente, ad eccezione del
fatto che le descrizioni dei parametri sono inserite nella
sintassi della funzione. Questo formato è soprattutto utile
quando le descrizioni sono brevi.

function Add-Extension
{
param
(
[string]
# Specifica il nome file.
$name,

[string]
# Specifica l'estensione. "Txt" è l'estensione
predefinita.
$extension = "txt"
)
$name = $name + "." + $extension
$name

<#
.SYNOPSIS
Aggiunge un'estensione di file a un nome fornito.

.DESCRIPTION
Aggiunge un'estensione di file a un nome fornito. Accetta
qualsiasi stringa per il nome o l'estensione di file.

.INPUTS
Nessuno. Non è possibile reindirizzare oggetti a
Add-Extension.

.OUTPUTS
System.String. Add-Extension restituisce una stringa con
il nome o l'estensione di file.

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

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

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

.LINK
Versione online: http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Esempio 3: Guida basata su commenti relativa a uno script

Nello script di esempio seguente è inclusa una Guida basata
su commenti.

Si notino le righe vuote tra il simbolo di chiusura "#>" e
l'istruzione Param. In uno script privo di 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
Esegue aggiornamenti mensili dei dati.

.DESCRIPTION
Lo script Update-Month.ps1 aggiorna il Registro di sistema
con i nuovi dati generati lo scorso mese e genera un report.

.PARAMETER InputPath
Specifica il percorso del file di input basato su CSV.

.PARAMETER OutputPath
Specifica il nome e il percorso del file di output basato
su CSV. Per impostazione predefinita, MonthlyUpdates.ps1
genera un nome in base alla data e all'ora in cui viene
eseguito e salva l'output nella directory locale.

.INPUTS
Nessuno. Non è possibile reindirizzare oggetti a
Update-Month.ps1.

.OUTPUTS
Nessuno. Update-Month.ps1 non genera alcun output.

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

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

.EXAMPLE
C:\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 Path, nel comando Get-Help che ottiene la Guida
dello script deve essere specificato il percorso dello script.

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

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

SYNOPSIS
Esegue aggiornamenti mensili dei dati.

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

DESCRIZIONE
Lo script Update-Month.ps1 aggiorna il Registro di
sistema con i nuovi dati generati lo scorso mese e
genera un report.

PARAMETRI
-InputPath
Specifica il percorso del file di input basato su CSV.

Required? true
Position? 0
Valore predefinito
Accept pipeline input? false
Accept wildcard characters?

-OutputPath
Specifica il nome e il percorso del file di output
basato su CSV. Per impostazione predefinita,
MonthlyUpdates.ps1 genera un nome in base alla
data e all'ora in cui viene eseguito e salva
l'output nella directory locale.

Required? false
Position? 1
Valore predefinito
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
Questo cmdlet supporta i parametri comuni
-Verbose, -Debug, ErrorAction, -ErrorVariable,
-WarningAction, -WarningVariable, OutBuffer e
-OutVariable. Per ulteriori informazioni,
digitare "get-help about_commonparameters".

INPUT
Nessuno. Non è possibile reindirizzare oggetti a
Update-Month.ps1.

OUTPUT
Nessuno. Update-Month.ps1 non genera alcun output.

-------------------------- ESEMPIO 1 --------------------------
C:\PS> .\Update-Month.ps1

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

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

COLLEGAMENTI CORRELATI

Esempio 4: Reindirizzamento a un File XML

È possibile scrivere argomenti della Guida basati su XML
relativi a funzioni e script. Anche se la Guida basata su
commenti risulta essere di più facile implementazione, la
Guida basata su XML è necessaria qualora si desideri
esercitare un controllo più preciso sul contenuto della Guida
o si intenda tradurre gli argomenti della Guida in più lingue.

Nell'esempio seguente vengono illustrate le prime righe dello
script Update-Month.ps1. Nello script viene utilizzata la
parola chiave ExternalHelp per specificare il percorso di un
argomento della Guida basato su XML relativo allo script.

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

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

function Get-Data { }
...

Nell'esempio seguente viene illustrato l'utilizzo della parola
chiave ExternalHelp in una funzione.

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

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

Esempio 5: Reindirizzamento a un argomento della Guida diverso

Il codice seguente è tratto dall'inizio della funzione Help
incorporata in Windows PowerShell che consente di
visualizzare una schermata alla volta di testo della Guida.
Poiché l'argomento della Guida relativo al cmdlet Get-Help
descrive la funzione Help, quest'ultima utilizza le parole chiave
ForwardHelpTargetName e ForwardHelpCategory per reindirizzare
l'utente all'argomento della Guida relativo al 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 utilizza questa funzionalità:

C:\PS> get-help help

NOME
Get-Help

SYNOPSIS
Visualizza informazioni sui cmdlet e i concetti
relativi a Windows PowerShell.
...

VEDERE ANCHE
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Modalità di scrittura della Guida dei cmdlet" (https://go.microsoft.com/fwlink/?LinkID=123415)
(le informazioni potrebbero essere in lingua inglese)

about_Comment_Based_Help

Argomenti della Guida