Share via

Windows PowerShell

  • Articolo

WTFM: Writing the Fabulous Manual

Don Jones

“ RTFM ” è uno degli acronimi Preferiti del settore IT (almeno parte di tale lingua inglese). Sia stato digitato in modo diverso da persone diverse, ma in genere viene accettato da un elemento come “ Read the favolosi manuale ” e viene in genere espresso in risposta a una domanda probabilmente Impossibile sono stata completata più rapidamente e completamente, se il asker era semplicemente leggere le istruzioni. Mentre si lavora con Windows PowerShell, tuttavia e avviare la creazione di script e ad altri utenti di utilizzare le funzioni, effettuano che vi sia effettivamente una serie di istruzioni per poter leggere? Si è, in altre parole, scrittura manuale favolosi (WTFM)?

‘ Nessun commento ’ È Nessuna risposta a destra

Se si dispone riscontrare alcun modo con computer programmazione o creazione di script, si ha familiarità con l'utilizzo dei commenti di codice inline per documentare la funzione di una particolare porzione di codice. Naturalmente, Windows PowerShell fornisce supporto per i commenti: La shell ignora qualsiasi riga che inizia con #, che consente di inserire eventuali commenti è quello desiderato.

Purtroppo, per leggere questi commenti, è necessario aprire lo script nel blocco note o in un altro editor e che è un comportamento diverso da che cosa si probabilmente utilizzerà un cmdlet di shell, che integra la Guida in linea incorporata della shell. Uno dei concetti di base in Windows PowerShell è che è sufficiente solo per informazioni su un singolo insieme di competenze e i comportamenti per qualsiasi attività specificato; se si è appreso già utilizzare il comando di Get-Help per ottenere istruzioni per un cmdlet nativo, perché dovrebbero funzionare esistente in modo diverso per uno script o una funzione cose?

Nella versione 2 della shell, le cose Don ’t hanno per lavorare in modo diverso. Windows PowerShell v2 viene introdotto un nuovo modulo della documentazione chiamato della Guida basati su commento. In sostanza, la shell è in grado di ricercare commenti all'interno di una funzione o di script appositamente predisposto e analizza tali commenti per creare lo stesso tipo di visualizzazione della Guida visualizzata con un cmdlet nativo è. Guida cmdlet è effettivamente scritto in formato XML; Guida in linea basati sul commento non solo più semplice creare manualmente, ma anche trasmessi con qualsiasi script o la funzione è associato, che effettua la funzione o di script indipendente e facile da distribuire.

Impostare Let’s un obiettivo di produzione di uno script o una funzione in grado di visualizzare la Guida tramite il comando di incorporato Get-Help , formattazione che consentono di esattamente come quello di un cmdlet nativo, come illustrato in Figura 1.

 

Figura 1 Guida formattato come un cmdlet nativo in Windows PowerShell.

Per WTFM RTFM

Windows PowerShell include una Guida incorporata completa per la Guida in base commento: Eseguire semplicemente consentire about_comment_based_help . Fondamentalmente, le regole per la Guida in linea basati sul commento sono semplici:

  • I commenti devono essere innanzitutto all'interno di script (se la Guida si applica all'intero script) o di una funzione (se la Guida in linea è specifico di una funzione).
  • I commenti devono utilizzare formattazione e le parole chiave specifiche in modo da analizzare correttamente da funzionalità della Guida della shell.

È possibile utilizzare uno dei due commenti a riga singola, precedono ogni riga # oppure è possibile utilizzare i nuovi commenti di blocco. Questi sono più facili da digitare, poiché non è più necessario utilizzare una direttiva # all'inizio di ogni riga. Avvia un blocco di commento digitando < # su una riga di per sé e terminano con n > in una riga di per sé. Qualsiasi elemento tra le due righe verrà considerato parte del commento.

Le istruzioni della Guida in linea verranno create come una serie di blocchi. Ogni blocco inizia con una parola chiave sezione, ad esempio .SYNOPSIS o .DESCRIPTION. La parola chiave effettiva è preceduta da un punto e il periodo deve essere il primo carattere della riga excepting spazi o il carattere #. Il file di about_comment_based_help Elenca tutte le parole chiave possibili, ma quelli principali sono:

  • .SYNOPSIS –a breve spiegazione di cosa è lo script o una funzione.
  • .DESCRIPTION – più dettagliate spiegazione di cosa è lo script o una funzione.
  • .Parameter name – una spiegazione di un parametro specifico. Sostituire il nome con il nome del parametro. È possibile una di queste sezioni per ogni parametro viene utilizzato uno script o funzione.
  • .EXAMPLE: un esempio di come utilizzare la funzione o script. È possibile avere più sezioni .EXAMPLE se si desidera fornire più di un esempio.
  • .NOTES – varie note sull'utilizzo di script o funzione.
  • .LINK – consentono di un riferimento incrociato a un altro argomento, può avere più di uno di questi. Se si include un URL che inizia con http:// o https://, la shell di aprire tale URL quando viene utilizzato –online parametro del comando Help.

Ogni parola chiave va in una riga di per sé e seguita da uno o più righe di testo. Ecco un esempio:

<#.SYNOPSISRetrieves service pack and operating system information from one or more remote computers..DESCRIPTIONThe Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. Each computer is contacted sequentially, not in parallel..PARAMETER computerNameAccepts a single computer name or an array of computer names. You mayalso provide IP addresses..PARAMETER pathThe path and file name of a text file. Any computers that cannot be reached will be logged to this file. This is an optional parameter; if it is notincluded, no log file will be generated..EXAMPLERead computer names from Active Directory and retrieve their inventory information.Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.EXAMPLERead computer names from a file (one name per line) and retrieve their inventory informationGet-Content c:\names.txt | Get-Inventory.NOTESYou need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.#>

Nella figura 2 viene illustrato questo aspetto all'interno di una funzione effettiva.

 

Nella figura 2 Helpinstructions all'interno di una funzione.

Comando Guida continua a seguire le relative regole normale per quali parti di Guida in linea da visualizzare. Ad esempio, si vedrà solo il .EXAMPLE sezione se si utilizza il parametro di –example , mentre tutte le sezioni verrà visualizzato se si utilizza il parametro di –full .  In ogni caso, si vedrà (come nella Figura 3 ) che aspetto identico a un cmdlet nativo della Guida in linea della funzione.

 

Nella figura 3 della Guida in linea della funzione che è simile a un cmdlet nativo.

Procedure consigliate per le informazioni della Guida basati su commenti

Mi piace includere almeno una sezione .SYNOPSIS e .DESCRIPTION all'interno di ogni script o di una funzione di che scrittura. Se lo script o la funzione viene utilizzato uno o più parametri, documenti con una sezione .Parameter. In questo modo, chiunque subentra in un secondo momento ed è necessario utilizzare la funzione o script può facilmente scoprire cosa. Caspita, parimenti, sei mesi dopo verrà probabilmente hanno dimenticato ho scritto e verrà necessario un aggiornamento rapido, che fornisce Parameter della Guida basati su commento.

Più strutturato e riutilizzabile più dettagliata, il codice dovrebbe essere Guida in linea. Ad esempio, la funzione di esempio Get Inventory è strutturato come una “ funzione avanzata ”, vale a dire aspetto e funziona sostanzialmente come un cmdlet nativo. Che è il più alto di vita nel mondo della shell, in modo che è necessario fornire lo stesso livello di informazioni della Guida dettagliate un cmdlet “ reale ”, tra cui documentazione esempi, le note, i riferimenti incrociati, ingressi e uscite e così via.

Avvia le utilità di terze più fare affidamento sulla Guida di. Ad esempio ambienti di script integrati di terze parti spesso analizzare la Guida per fornire IntelliSense simile a funzionalità di hint codice - completamento e funzionalità all'interno di ambienti di modifiche; includendo Guida commento-completa e formattata correttamente, si sta attivando gli script e le funzioni per essere utilizzato con maggiore facilità dall'interno di tali strumenti di terze parti.

Inoltre, solo aspetto interessante per gli script e tale aspetto come come cmdlet “ reale ” possibili funzioni, tra cui l'output di informazioni della Guida alla ricerca slick.

Contenuto correlato