Scrittura della Guida per script e funzioni di PowerShell

Gli script e le funzioni di PowerShell devono essere documentati completamente ogni volta che vengono condivisi con altri utenti. Il cmdlet Get-Help visualizza gli argomenti della Guida per script e funzioni nello stesso formato visualizzato nella Guida per i cmdlet e tutti i parametri Get-Help funzionano sugli argomenti della Guida su script e funzioni.

Gli script di PowerShell possono includere un argomento della Guida sullo script e argomenti della Guida su ogni funzione nello script. Le funzioni condivise indipendentemente da script possono includere argomenti della Guida specifici.

Questo documento illustra il formato e la corretta posizione degli argomenti della Guida e suggerisce linee guida per il contenuto.

Tipi di script e guida per le funzioni

Guida di Comment-Based

L'argomento della Guida che descrive uno script o una funzione può essere implementato come set di commenti all'interno dello script o della funzione. Quando si scrive una Guida basata su commenti per uno script e per le funzioni in uno script, prestare attenzione alle regole per inserire la Guida basata su commenti. Il posizionamento determina se il cmdlet Get-Help associa l'argomento della Guida allo script o a una funzione. Per altre informazioni sulla scrittura di argomenti della Guida basata su commenti, vedere about_Comment_Based_Help.

Guida ai comandi di XML-Based

L'argomento della Guida che descrive uno script o una funzione può essere implementato in un file XML che usa lo schema della Guida dei comandi. Per associare lo script o la funzione al file XML, utilizzare la parola chiave di commento .EXTERNALHELP seguita dal percorso e dal nome del file XML.

Quando la parola chiave comment .EXTERNALHELP è presente, ha la precedenza sulla Guida basata su commenti, anche quando Get-Help non riesce a trovare un file della Guida corrispondente al valore della parola chiave .EXTERNALHELP.

Guida online

È possibile pubblicare gli argomenti della Guida su Internet e quindi indirizzare Get-Help per aprire gli argomenti. Per altre informazioni sulla scrittura di argomenti della Guida basata su commenti, vedere Supporto della Guida online.

Non esiste alcun metodo stabilito per la scrittura di argomenti concettuali ("About") per script e funzioni. Tuttavia, è possibile pubblicare argomenti concettuali su Internet elencare gli argomenti e i relativi URL nella sezione Collegamenti correlati di un argomento della Guida dei comandi.

Considerazioni sul contenuto per la Guida di script e funzioni

Se si scrive un argomento della Guida molto breve con solo alcune delle sezioni della Guida ai comandi disponibili, assicurarsi di includere descrizioni chiare dei parametri dello script o della funzione. Includere anche uno o due comandi di esempio nella sezione degli esempi, anche se si decide di omettere descrizioni di esempio.
In tutte le descrizioni fare riferimento al comando come script o funzione. Queste informazioni consentono all'utente di comprendere e gestire il comando.

Ad esempio, la descrizione dettagliata seguente indica che il comando New-Topic è uno script. Questo ricorda agli utenti che devono specificare il percorso e il nome completo quando lo eseguono.

"Lo script New-Topic crea un argomento concettuale vuoto per ogni nome di argomento nel file di input..."

La descrizione dettagliata seguente indica che Disable-PSRemoting è una funzione. Queste informazioni sono particolarmente utili per gli utenti quando la sessione include più comandi con lo stesso nome, alcuni dei quali potrebbero essere nascosti da un comando con precedenza superiore.

La funzione Disable-PSRemoting disabilita tutte le configurazioni di sessione nel computer locale...
In un argomento della Guida di script spiegare come usare lo script nel suo complesso. Se si scrivono anche argomenti della Guida per le funzioni nello script, menzionare le funzioni nell'argomento della Guida dello script e includere riferimenti agli argomenti della Guida per le funzioni nella sezione Collegamenti correlati dell'argomento della Guida per gli script. Viceversa, quando una funzione fa parte di uno script, spiegare nell'argomento della Guida della funzione il ruolo svolto dalla funzione nello script e come può essere usato in modo indipendente. Elencare quindi l'argomento della Guida per gli script nella sezione Collegamenti correlati dell'argomento della Guida per le funzioni.
Quando si scrivono esempi per un argomento della Guida di script, assicurarsi di includere il percorso del file di script nel comando di esempio. Questo ricorda agli utenti che devono specificare il percorso in modo esplicito, anche quando lo script si trova nella directory corrente.
In un argomento della Guida per le funzioni ricordare agli utenti che la funzione esiste solo nella sessione corrente e, per usarla in altre sessioni, è necessario aggiungerla o aggiungerla un profilo di PowerShell.
Get-Help visualizza l'argomento della Guida per uno script o una funzione solo quando il file di script e i file degli argomenti della Guida vengono salvati nei percorsi corretti. Pertanto, non è utile includere istruzioni per l'installazione di PowerShell o il salvataggio o l'installazione dello script o della funzione in un argomento della Guida di script o funzioni. Includere invece tutte le istruzioni di installazione nel documento usato per distribuire lo script o la funzione.