Condividi tramite

Guida di stile per la documentazione di PowerShell

Questo articolo fornisce indicazioni sullo stile specifiche del contenuto PowerShell-Docs. Si basa sulle informazioni descritte in Panoramica.

Formattazione degli elementi della sintassi dei comandi

Usare le regole seguenti per formattare gli elementi del linguaggio di PowerShell quando gli elementi vengono usati in una frase.

  • Usare sempre il nome completo per i cmdlet e i parametri nel caso Pascal appropriato

  • Usare un alias solo quando si sta specificamente dimostrando l'alias

  • Le parole chiave e gli operatori di PowerShell devono essere tutti minuscoli

  • Gli elementi seguenti devono essere formattati usando il testo grassetto :

    • Nomi dei tipi

    • Nomi di classe

    • Nomi delle proprietà

    • Nomi dei parametri

      • Per impostazione predefinita, usare il parametro senza il prefisso trattino.
      • Usare il nome del parametro con il trattino quando si illustra la sintassi. Racchiudere il parametro nei backtick.

      Per esempio:

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

  • Gli elementi seguenti devono essere formattati usando i backtick (`):

    • Valori di proprietà e parametri

    • Nomi di tipo che usano lo stile tra parentesi quadre, ad esempio: [System.Io.FileInfo]

    • Riferimento ai personaggi per nome. Ad esempio: Usare il carattere asterisco (*) come carattere jolly.

    • Parole chiave e operatori del linguaggio

    • Cmdlet, funzione e nomi di script

    • Alias di comandi e parametri

    • Nomi dei metodi: ad esempio: il ToString() metodo restituisce una rappresentazione di stringa dell'oggetto

    • Variabili

    • Comandi nativi

    • Percorsi di file e directory

    • Esempi di sintassi dei comandi inline - Vedere Markdown per esempi di codice

      Questo esempio mostra alcuni esempi di backtick:

      The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

      Questo esempio mostra la sintassi dei comandi inline:

      To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.

      L'inclusione dell'estensione di file garantisce che il comando corretto venga eseguito in base alla precedenza del comando di PowerShell.

Markdown per esempi di codice

Markdown supporta due stili di codice diversi:

  • L'intervallo di codice (inline) è contrassegnato da un singolo carattere di backtick (`). Utilizzato all'interno di un paragrafo anziché come blocco autonomo.
  • Blocchi di codice - un blocco a più righe racchiuso da stringhe a triplo backtick (```). I blocchi di codice possono anche avere un'etichetta del linguaggio che segue i backtick. L'etichetta del linguaggio abilita l'evidenziazione della sintassi per il contenuto del blocco di codice.

Tutti i blocchi di codice devono essere contenuti in un recinto di codice. Non usare mai il rientro per i blocchi di codice. Markdown consente questo modello, ma può essere problematico e deve essere evitato.

Un blocco di codice è costituito da una o più righe di codice racchiuse da una delimitazione di codice a tre backtick (```). I marcatori di delimitazione del codice devono essere su una linea propria prima e dopo il campione di codice. L'indicatore di apertura può avere un'etichetta di lingua facoltativa. L'etichetta del linguaggio abilita l'evidenziazione della sintassi nella pagina Web sottoposta a rendering.

Per un elenco completo dei tag di lingua supportati, vedere Blocchi di codice delimitati nella guida per i collaboratori centralizzati.

La pubblicazione aggiunge anche un pulsante Copia che può copiare il contenuto del blocco di codice negli appunti. In questo modo è possibile incollare il codice in uno script per testare l'esempio di codice. Tuttavia, non tutti gli esempi devono essere eseguiti come scritti. Alcuni blocchi di codice sono illustrazioni di base dei concetti di PowerShell.

Nella nostra documentazione si utilizzano tre tipi di blocchi di codice:

  1. Blocchi di sintassi
  2. Esempi illustrativi
  3. Esempi eseguibili

Blocchi di codice della sintassi

I blocchi di codice di sintassi vengono usati per descrivere la struttura sintattica di un comando. Non usare un tag di lingua nella recinzione del codice. In questo esempio vengono illustrati tutti i possibili parametri del Get-Command cmdlet .

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

In questo esempio viene descritta l'istruzione for in termini generalizzati:

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Esempi illustrativi

Esempi illustrativi vengono usati per spiegare un concetto di PowerShell. Yo'u dovrebbe evitare di usare i prompt di PowerShell in esempi quando possibile. Tuttavia, gli esempi illustrativi non devono essere copiati e incollati per l'esecuzione. Vengono usati più comunemente per semplici esempi facili da comprendere. È possibile includere il prompt di PowerShell e l'output di esempio.

Ecco un semplice esempio che illustra gli operatori di confronto di PowerShell. In questo caso, il lettore non intende copiare ed eseguire questo esempio. Si noti che questo esempio usa PS> come stringa di richiesta semplificata.

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Esempi eseguibili

Esempi complessi, o esempi che devono essere copiati ed eseguiti, devono usare il markup in stile blocco seguente:

```powershell
<Your PowerShell code goes here>
```

L'output visualizzato dai comandi di PowerShell deve essere racchiuso in un blocco di codice di output per impedire l'evidenziazione della sintassi. Per esempio:

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

L'etichetta Output di codice non è un linguaggio ufficiale supportato dal sistema di evidenziazione della sintassi. Tuttavia, questa etichetta è utile perché il sistema di pubblicazione aggiunge l'etichetta Output al frame della casella di codice nella pagina Web. La casella Codice di output non include l'evidenziazione della sintassi.

Regole di stile di scrittura del codice

Evitare la continuazione di riga negli esempi di codice

Evitare di usare i caratteri di continuazione riga (`) negli esempi di codice di PowerShell. I caratteri di backtick sono difficili da vedere e possono causare problemi se ci sono spazi aggiuntivi alla fine della riga.

  • Usare splatting di PowerShell per ridurre la lunghezza della riga per i cmdlet con diversi parametri.
  • Sfrutta le opportunità di interruzione di riga naturali di PowerShell, come dopo i caratteri pipe (|), le parentesi graffe di apertura ({), le parentesi tonde (() e le parentesi quadre ([).

Evitare di usare i prompt di PowerShell negli esempi

L'uso della stringa del prompt è sconsigliato e deve essere limitato a scenari destinati a illustrare l'utilizzo della riga di comando. Per la maggior parte di questi esempi, la stringa di richiesta deve essere PS>. Questa richiesta è indipendente da indicatori specifici del sistema operativo.

I prompt sono necessari negli esempi per illustrare i comandi che modificano il prompt o quando il percorso visualizzato è significativo per lo scenario. Nel seguente esempio viene illustrato come cambia il prompt quando si usa il provider del Registro di sistema.

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Non usare alias negli esempi

Usare il nome completo di tutti i cmdlet e i parametri, a meno che non si stia documentando specificamente l'alias. I nomi dei cmdlet e dei parametri devono usare i nomi con maiuscole e minuscole Pascal appropriati.

Uso dei parametri negli esempi

Evitare di usare parametri posizionali. Per ridurre la probabilità di confusione, è necessario includere il nome del parametro in un esempio, anche se il parametro è posizionale.

Articoli di riferimento sui cmdlet di formattazione

Gli articoli di riferimento sui cmdlet hanno una struttura specifica. PlatyPS definisce questa struttura. PlatyPS genera la documentazione di aiuto dei cmdlet per i moduli PowerShell in Markdown. Dopo aver modificato i file Markdown, PlatyPS può creare i file di guida MAML utilizzati dal Get-Help cmdlet.

PlatyPS ha uno schema che prevede una struttura specifica per riferimento ai cmdlet. Il documento dello schema PlatyPS descrive questa struttura. Le violazioni dello schema causano errori di compilazione che devono essere corretti prima di poter accettare il contributo.

  • Non rimuovere alcuna delle strutture di intestazione ATX. PlatyPS richiede un set specifico di intestazioni in un ordine specifico.
  • Le intestazioni H2 INPUTS e OUTPUTS devono essere di tipo H3. Se il cmdlet non accetta input o restituisce un valore, usare il valore None per H3.
  • Gli intervalli di codice inline possono essere usati in qualsiasi paragrafo.
  • I blocchi di codice delimitati sono consentiti solo nella sezione EXAMPLES .

Nello schema PlatyPS , EXAMPLES è un'intestazione H2. Ogni esempio è un'intestazione H3. All'interno di un esempio, lo schema non consente la separazione dei blocchi di codice in base ai paragrafi. Lo schema consente solo la struttura seguente:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Numerare ogni esempio e aggiungere un breve titolo.

Per esempio:

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

Formattazione dei file About_

About_* i file vengono scritti in Markdown, ma vengono spediti come file di testo normale. Usiamo Pandoc per convertire markdown in testo normale. About_* i file vengono formattati per garantire la migliore compatibilità tra tutte le versioni di PowerShell e con gli strumenti di pubblicazione.

Linee guida per la formattazione di base:

  • Limitare le righe di paragrafo a 80 caratteri

  • Limitare i blocchi di codice a 76 caratteri

  • Limitare le virgolette e gli avvisi a 78 caratteri

  • Quando si usano questi meta-caratteri \speciali,$ e <:

    • All'interno di un'intestazione, questi caratteri devono essere preceduti con un carattere \ o racchiusi in segmenti di codice tramite backticks (`).

    • All'interno di un paragrafo, questi caratteri devono essere inseriti in intervalli di codice. Per esempio:

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Tabelle Markdown

    • Per About_* gli articoli, le tabelle devono contenere entro 76 caratteri
      • Se il contenuto non rientra nel limite di 76 caratteri, usa invece un elenco puntato.
    • Usare caratteri di apertura e chiusura | in ogni riga

Passaggi successivi

Elenco di controllo editoriale

  • Last updated on