Condividi tramite

Scrittura della Guida per i moduli di PowerShell

I moduli di PowerShell possono includere argomenti della Guida sul modulo e sui membri del modulo, ad esempio cmdlet, provider, funzioni e script. Il Get-Help cmdlet visualizza gli argomenti della Guida del modulo nello stesso formato visualizzato nella Guida per altri elementi di PowerShell e gli utenti usano comandi standard Get-Help per ottenere gli argomenti della Guida.

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

Tipi di Guida del modulo

Un modulo può includere i tipi seguenti di Guida.

  • Guida basata su XML

    • Guida dei cmdlet. Gli argomenti della Guida che descrivono i cmdlet in un modulo sono file XML che usano lo schema della Guida dei comandi
    • Guida del provider. Gli argomenti della Guida che descrivono i provider in un modulo sono file XML che usano lo schema della Guida del provider.
    • Guida della funzione. Gli argomenti della Guida che descrivono le funzioni in un modulo possono essere file XML che usano lo schema della Guida del comando o gli argomenti della Guida basata su commenti all'interno della funzione, oppure lo script o il modulo script
    • Guida script. Gli argomenti della Guida che descrivono gli script in un modulo possono essere file XML che usano lo schema della Guida dei comandi o gli argomenti della Guida basata su commenti nel modulo script o script.
    • La $PSHOME\Schemas\PSMaml cartella contiene i file di schema che definiscono il formato XML.

  • File di testo della Guida concettuali ("About")

    È possibile usare un argomento della Guida concettuale ("about") per descrivere il modulo e i relativi membri e spiegare in che modo i membri possono essere usati insieme per eseguire attività. Per impostazione predefinita, PowerShell include più di 100 di questi argomenti concettuali sulla Guida. Il nome file deve usare il about_<name>.help.txt formato , ad esempio about_MyModule.help.txt.

    Annotazioni

    L'intestazione TOPIC della sezione deve iniziare nella prima colonna della prima riga del file. Il contenuto della sezione nella seconda riga deve corrispondere al nome del file, senza il .help.txt suffisso . È necessario impostare un rientro del contenuto esattamente 4 spazi. La terza riga deve essere vuota. L'intestazione SYNOPSIS di sezione deve iniziare nella prima colonna della quarta riga. È necessario impostare un rientro del contenuto sulla quinta riga esattamente 4 spazi. Questi requisiti sono necessari per il Get-Help cmdlet per riconoscere correttamente il contenuto.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    È possibile usare il modello di esempio seguente come punto di partenza per la scrittura di argomenti della Guida concettuale. Ad eccezione delle prime due sezioni, la struttura degli argomenti della Guida concettuale è arbitraria. I titoli delle sezioni rimanenti possono essere appropriati per il contenuto.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    È possibile usare qualsiasi stile e markup desiderato, ma PowerShell lo vede come testo normale e non è disponibile alcun rendering speciale del testo nella console di PowerShell. I suggerimenti seguenti garantiscono i risultati e la leggibilità migliori per la visualizzazione.

    • Usare UTF-8 con la codifica BOM per garantire che tutti i caratteri speciali (multibyte) vengano visualizzati correttamente.
    • Sottolinea le intestazioni di sezione o usa tutte le lettere maiuscole per distinguerle. In questo modo il contenuto risulta più semplice da analizzare.
    • Limitare la lunghezza di ogni riga a 80 caratteri.
    • Suddividere i blocchi di codice e l'output di esempio per separarli dalla prosa circostante.

Posizionamento della Guida del modulo

Il Get-Help cmdlet cerca i file dell'argomento della Guida del modulo nelle sottodirectory specifiche della lingua della directory del modulo.

Ad esempio, il diagramma della struttura di directory seguente mostra il percorso degli argomenti della Guida per il modulo SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Annotazioni

Nell'esempio il <ModulePath> segnaposto rappresenta uno dei percorsi nella PSModulePath variabile di ambiente, ad esempio $HOME\Documents\Modules, $PSHOME\Moduleso un percorso personalizzato specificato dall'utente.

Guida al modulo

Quando un utente importa un modulo in una sessione, gli argomenti della Guida per tale modulo vengono importati nella sessione insieme al modulo. È possibile elencare i file degli argomenti della Guida nel valore della chiave FileList nel manifesto del modulo, ma gli argomenti della Guida non sono interessati dal Export-ModuleMember cmdlet.

È possibile fornire argomenti della Guida del modulo in lingue diverse. Il Get-Help cmdlet visualizza automaticamente gli argomenti della Guida del modulo nella lingua specificata per l'utente corrente nell'elemento Opzioni internazionali e linguistiche nel Pannello di controllo. In Windows Vista e versioni successive di Windows, Get-Help cerca gli argomenti della Guida nelle sottodirectory specifiche della lingua della directory dei moduli in conformità agli standard di fallback della lingua stabiliti per Windows.

A partire da PowerShell 3.0, l'esecuzione di un Get-Help comando per un cmdlet o una funzione attiva l'importazione automatica del modulo. Il Get-Help cmdlet visualizza immediatamente il contenuto degli argomenti della Guida nel modulo.

Se il modulo non contiene argomenti della Guida e non sono disponibili argomenti della Guida per i comandi del modulo nel computer dell'utente, Get-Help visualizza la Guida generata automaticamente. La Guida generata automaticamente include la sintassi del comando, i parametri e i tipi di input e output, ma non include descrizioni. La Guida generata automaticamente include testo che indirizza l'utente a provare a usare il Update-Help cmdlet per scaricare la Guida per il comando da Internet o da una condivisione file. Consiglia inoltre di usare il parametro Online del Get-Help cmdlet per ottenere la versione online dell'argomento della Guida.

Supporto della Guida aggiornabile

Gli utenti di PowerShell 3.0 e versioni successive di PowerShell possono scaricare e installare i file della Guida aggiornati per un modulo da Internet o da una condivisione file locale. I Update-Help cmdlet e Save-Help nascondono i dettagli di gestione all'utente. Gli utenti eseguono il Update-Help cmdlet e quindi usano il Get-Help cmdlet per leggere i file della Guida più recenti per il modulo al prompt dei comandi di PowerShell. Gli utenti non devono riavviare Windows o PowerShell.

Gli utenti protetti da firewall e quelli senza accesso a Internet possono usare anche la Guida aggiornabile. Gli amministratori con accesso a Internet usano il Save-Help cmdlet per scaricare e installare i file della Guida più recenti in una condivisione file. Gli utenti usano quindi il parametro Path del Update-Help cmdlet per ottenere i file della Guida più recenti dalla condivisione file.

Gli autori di moduli possono includere file della Guida del modulo e usare la Guida aggiornabile per aggiornare i file della Guida oppure omettere i file della Guida dal modulo e usare la Guida aggiornabile per installarli e aggiornarli.

Per altre informazioni sulla Guida aggiornabile, vedere Supporto della Guida aggiornabile.

Supporto della Guida online

Gli utenti che non possono o non installano i file della Guida aggiornati nei computer spesso si basano sulla versione online degli argomenti della Guida del modulo. Il parametro Online del Get-Help cmdlet apre la versione online di un argomento della Guida di un cmdlet o di una funzione avanzata per l'utente nel browser Internet predefinito.

Il Get-Help cmdlet usa il valore della proprietà HelpUri del cmdlet o della funzione per trovare la versione online dell'argomento della Guida.

A partire da PowerShell 3.0, è possibile aiutare gli utenti a trovare la versione online dei cmdlet e degli argomenti della Guida per le funzioni definendo l'attributo HelpUri nella classe cmdlet o la proprietà HelpUri dell'attributo CmdletBinding . Il valore dell'attributo è il valore della proprietà HelpUri del cmdlet o della funzione.

Per altre informazioni, vedere Supporto della Guida online.

Vedere anche

  • Last updated on