Come aggiungere una descrizione del cmdlet

Note

La creazione manuale della Guida basata su XML è molto difficile. Il modulo PlatyPS consente di scrivere aiuto in Markdown e quindi convertirlo nella Guida basata su XML. In questo modo è molto più semplice scrivere e gestire la Guida. PlatyPS può anche creare automaticamente i pacchetti della Guida aggiornabili. Per altre informazioni, vedere Creare una Guida basata su XML con PlatyPS.

Questa sezione descrive come aggiungere contenuto visualizzato nella sezione DESCRIPTION della Guida del cmdlet. Nel file della Guida questo contenuto viene aggiunto al nodo Comando per ogni cmdlet.

Note

Per una visualizzazione completa di un file della Guida, aprire uno dei dll-Help.xml file presenti nella directory di installazione di PowerShell. Ad esempio, il Microsoft.PowerShell.Commands.Management.dll-Help.xml file contiene contenuto per diversi cmdlet di PowerShell.

Per aggiungere una descrizione

Il <maml:description> nodo contiene la descrizione dettagliata del cmdlet. Questo elemento contiene uno o più <maml:para> elementi. La descrizione è racchiusa in un <maml:para> elemento . Nell'esempio seguente viene illustrata la struttura del codice XML:

<maml:description>
  <maml:para>...</maml:para>
</maml:description>

Suggerimenti per la scrittura

  • Iniziare spiegando in modo più dettagliato le funzionalità di base del cmdlet. In molti casi, è possibile spiegare i termini usati nel nome del cmdlet e illustrare i concetti non familiari con un esempio. Ad esempio, se il cmdlet aggiunge dati a un file, spiegare che aggiunge dati alla fine di un file esistente.

  • Per trovare tutte le funzionalità del cmdlet, esaminare l'elenco dei parametri. Descrivere la funzione primaria del cmdlet e quindi includere altre funzioni e funzionalità. Ad esempio, se la funzione principale del cmdlet consiste nel modificare una proprietà, ma il cmdlet può modificare tutte le proprietà, ad esempio nella descrizione dettagliata. Se i parametri del cmdlet consentono agli utenti di richiedere informazioni in modi diversi, spiegarlo.

  • Includere informazioni sui modi in cui gli utenti possono usare il cmdlet, oltre agli usi ovvi. Ad esempio, è possibile usare l'oggetto recuperato dal Get-Host cmdlet per modificare il colore del testo nella finestra di comando di Windows PowerShell.

    Esempio: "Il Get-Acl cmdlet ottiene oggetti che rappresentano il descrittore di sicurezza di un file o di una risorsa. Il descrittore di sicurezza contiene gli elenchi di controllo di accesso (ACL) della risorsa. L'elenco di controllo di accesso specifica le autorizzazioni che gli utenti e i gruppi di utenti devono accedere alla risorsa".

  • La descrizione dettagliata deve descrivere il cmdlet, ma non deve descrivere i concetti usati dal cmdlet. Inserire le definizioni dei concetti in Note aggiuntive.

Vedere anche

Windows PowerShell SDK

  • Last updated on