Windows PowerShell. Commenti personalizzati nelle guide
È possibile aggiungere commenti personalizzati agli script e creare una guida in linea e un sistema di esercitazione personalizzati.
Don Jones
Una delle cose più grazioso di Windows PowerShell è il suo sistema di aiuto. L'aiuto file includono sintassi descrizioni, spiegazioni dettagliate, esempi e così via.
Dato che una shell da riga di comando non può offrire funzionalità di individuazione come menu, barre degli strumenti, nastri e così via, il file della guida si erge sulla propria come un'individuazione caratteristica. È possibile utilizzare e con caratteri jolly, ad esempio, alla scoperta di nuovi comandi. Quindi è possibile leggere il loro aiuto per imparare a usarli.
Come si producono i propri comandi come funzioni e script, farebbe bene a mantenere il vostro lavoro come lucido come i cmdlet di Windows PowerShell nativi. Si dovrebbe sempre endeavor rendere il vostro lavoro più coerente possibile con il resto del guscio. Parte di tale coerenza e polacco è nel modo di preparare e fornire aiuto.
Si potrebbe produrre lo stesso tipo esatto del file della Guida basata su XML che utilizza Windows PowerShell stesso. Non c'è più discussione su questo argomento nel mio libro autoprodotto, "Windows PowerShell Scripting e utensili. Tuttavia, la maggior parte di voi non avrete bisogno della flessibilità quelle file di aiuto di offrire, come la possibilità di fornire un aiuto in più lingue.
Si può prendere un percorso molto più facile. È possibile utilizzare semplicemente una guida basata su commento.
Regole di guida basata su commenti
Ci sono alcune regole per una guida basata su commento che devo coprire destra anteriore:
- In genere, sarà necessario racchiudere i blocchi di commento speciale nella < blocco # commento #> marcatori. È anche legale semplicemente commentare ogni linea da a partire con il carattere di commento #.
- Guida basata su commento dovrebbe essere la prima cosa nel file di script. È preferibile includere l'aiuto all'interno della funzione, piuttosto che appena prima. Che aiuta a mantenere il commento "parte" della funzione e assicura che Windows PowerShell non confonderlo per qualcos'altro. Inoltre è legale mettere una guida basata su commento dello script alla fine del file, ma non mi piace farlo perché sminuisce alcuni degli altri vantaggi dell'utilizzo di una guida basata su commento.
- Se si sta fornendo aiuto per una funzione, il blocco basato su commento aiuto può venire immediatamente prima o immediatamente dopo il nome della funzione e la parentesi graffa di apertura.
- Quando metti le funzioni multiple in uno script, ad esempio un modulo di script, è possibile fornire aiuto per il file mettendo il blocco di commento in alto. Assicurarsi di aggiungere almeno un paio righe vuote dopo quel blocco di commento, in modo che qualsiasi aiuto specifiche funzioni successive will stand apart correttamente.
- Se è errato delle parole chiave della Guida basata su commenti, Windows PowerShell potrebbe semplicemente ignorare l'intero blocco. Quindi state attenti dell'ortografia, perché conta.
Sintassi basata su commenti aiuto
Guida basata su commento è costituito da una o più sezioni. Ogni sezione inizia con una parola chiave con punti, seguita da una o più righe di testo. Di seguito è riportato un esempio di utilizzo di questo attributo.
<# .SYNOPSIS The synopsis goes here. This can be one line, or many. .DESCRIPTION The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need. .PARAMETER computername Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter: .PARAMETER filePath Provide a PARAMETER section for each parameter that your script or function accepts. .EXAMPLE There's no need to number your examples. .EXAMPLE PowerShell will number them for you when it displays your help text to a user. #>
Quell'esempio comprende le quattro parole chiave punteggiate più comunemente utilizzate. Si noterà che questi iniziano con un punto o un periodo. Windows PowerShell non è case-sensitive su quelli, anche se la documentazione li elenca in tutto maiuscolo (quindi tendono a fare lo stesso). Utilizzando tutto maiuscolo rende anche le sezioni stare fuori un po' di più quando stai leggendo il codice in un editor di script.
Un'altra sezione pulita che è possibile utilizzare è il LINK. Con questo, è possibile includere un URL, a partire con l'indirizzo http:// per una versione online del vostro aiuto. Per esempio, postando il vostro aiuto su un sito intranet, lascia qualcuno più in dettaglio, possibilmente più esempi, trovare il modo per contattarti e così via.
Windows PowerShell auto-genera ulteriore aiuto contenuto guardando il tuo script o funzione. Esso deriva il nome, la sintassi di base (compresi i tipi di dati e i nomi di parametro) e altre informazioni. Esso non rileva eventuali valori predefiniti che possono avere codificato in un parametro:
Param($computername = 'localhost')
Pertanto, è necessario prestare attenzione a documentare eventuali inadempienze nella guida per il parametro stesso, o anche nella descrizione.
Suggestione basata su commenti
Un altro vantaggio della Guida basata su commento è che esso fornisce due tipi di aiuto. Uno è per la gente che VSL contro il vostro script e funzioni. L'altro è per qualcuno leggendo il tuo script.
In altre parole, una guida basata su commento ben scritta anche può raddoppiarsi come documentazione in linea che probabilmente si preferisce mettere in qualsiasi tipo di script.
.jpg)
Don Jones è un Microsoft MVP Award destinatario e autore di "Imparare Windows PowerShell in un mese di pranzi" (Manning Publications, 2011), un libro progettato per aiutare qualsiasi amministratore diventano efficaci con Windows PowerShell. Jones offre anche formazione Windows PowerShell pubblica e in loco. È possibile contattarlo attraverso ConcentratedTech.com o bit.ly/AskDon.