Come Scrivere Aiuto Basato su Commenti per Script PowerShell

1. Aiuto Basato su Commenti in PowerShell
2. Parole Chiave Basate su Commenti in PowerShell

Questo articolo dimostra come possiamo scrivere argomenti di aiuto basati su commenti per script e funzioni. Useremo parole chiave speciali per i commenti di aiuto per creare gli argomenti.

Utilizziamo il cmdlet Get-Help per visualizzare argomenti di aiuto basati su commenti simili a quelli generati dai file XML.

Aiuto Basato su Commenti in PowerShell

Di seguito è illustrata la sintassi per l’aiuto basato su commenti.

# .<help keyword>
# <help content>

o

<#
.<help keyword>
<help content>
#>

Scriviamo argomenti di aiuto basati su commenti come una serie di commenti. Per contrassegnare i commenti, possiamo aggiungere il simbolo # all’inizio di ogni riga di commento oppure usare <# e #> per creare un blocco di commento.

La console registrerà le righe all’interno del blocco di commento come commenti.

Usiamo parole chiave speciali per definire ciascuna sezione di un argomento di aiuto basato su commenti. Le parole chiave iniziano con un . e non sono sensibili al caso.

Ecco un esempio:

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

Nell’esempio sopra, la parola chiave .Description contrassegna il commento come la descrizione della nostra funzione.

Un blocco di commento deve contenere almeno una parola chiave. Alcune parole chiave compaiono solo una volta, mentre altre non hanno un limite.

Il contenuto per una parola chiave dovrebbe iniziare sulla riga immediatamente dopo la parola chiave e non ha un limite.

Quando si aggiunge aiuto basato su commenti per funzioni, è possibile aggiungerli in una delle tre posizioni discusse di seguito.

1. All’inizio del corpo della funzione.
2. Alla fine del corpo della funzione.
3. Prima della parola chiave function. Separata da non più di una riga vuota.

Esempi:

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

o

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

o

<#
.<help keyword>
<content>
#>
function Get-Function { }

L’aiuto basato su commenti per gli script può apparire all’inizio dello script o alla fine. Ecco alcuni esempi:

<#
.<help keyword>
<content>
#>

function Get-Function { }

o

function Get-Function { }

<#
.<help keyword>
<content>
#>

Parole Chiave Basate su Commenti in PowerShell

Di seguito sono elencate le parole chiave valide per l’aiuto basato su commenti. Possono apparire in qualsiasi ordine e non sono sensibili al caso.

.SYNOPSIS

Questa è una breve descrizione della funzione o dello script. La parola chiave dovrebbe apparire solo una volta in ciascun argomento.

.DESCRIPTION

Questa è una descrizione dettagliata di una funzione o di uno script. La usiamo solo una volta in ciascun argomento.

.PARAMETER

Questo descrive i parametri nel tuo script o funzione. Aggiungiamo una parola chiave .PARAMETER per ogni parametro nei nostri script o funzioni.

.PARAMETER <Parameter-Name>

Le parole chiave per i parametri non seguono un ordine rigoroso nel blocco di commento. La sintassi dei parametri nello script o nella funzione determinerà l’ordine nell’argomento di aiuto.

Puoi cambiare l’ordine modificando la sintassi.

Possiamo specificare il contenuto della parola chiave del parametro aggiungendo un commento nella funzione o nello script. Questo commento dovrebbe precedere il nome della variabile del parametro.

PowerShell dà priorità alla descrizione associata alla parola chiave del parametro rispetto al commento di sintassi dove entrambi sono utilizzati.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

Includi un comando di esempio che utilizza lo script o la funzione. Possiamo includere questa parola chiave per tutti gli esempi nel nostro script o funzione.

.INPUTS

Questi sono gli oggetti .NET che possiamo inviare al nostro script o funzione. Possiamo aggiungere una descrizione per gli oggetti di input.

.OUTPUTS

Questi sono gli oggetti .NET che il nostro cmdlet restituisce. Possiamo aggiungere una descrizione per gli oggetti restituiti.

.NOTES

Queste sono informazione aggiuntive sulla funzione o lo script. Le informazioni possono includere la data in cui è stato scritto, il nome della funzione o il nome dell’autore.

.LINK

Questi sono gli argomenti correlati.

Ecco un esempio di aiuto basato su commenti per una funzione:

In conclusione, possiamo aggiungere aiuto basato su commenti nelle funzioni o negli script posizionandoli in un blocco di commento. Quando si aggiungono argomenti di aiuto, utilizzare la parola chiave di cui abbiamo parlato sopra e ricordare dove posizionare i blocchi di commento per script e funzioni.