Freigeben über

Styleguide für die PowerShell-Dokumentation

Dieser Artikel liefert stilistische Richtlinien, die speziell auf den PowerShell-Docs-Inhalt zugeschnitten sind. Sie baut auf den Informationen auf, die in der Übersicht beschrieben sind.

Elemente der Formatierungsbefehlssyntax

Verwenden Sie die folgenden Regeln, um Elemente der PowerShell-Sprache zu formatieren, wenn die Elemente in einem Satz verwendet werden.

  • Verwenden Sie immer den vollständigen Namen für Cmdlets und Parameter im richtigen Pascal-Fall.

  • Verwenden Sie nur einen Alias, wenn Sie den Alias explizit demonstrieren.

  • PowerShell-Schlüsselwörter und -Operatoren sollten alle Kleinbuchstaben sein

  • Die folgenden Elemente sollten mit fett formatiertem Text formatiert werden:

    • Namenstypen

    • Klassennamen

    • Eigenschaftennamen

    • Parameternamen

      • Verwenden Sie standardmäßig den Parameter ohne das Bindestrichpräfix.
      • Verwenden Sie den Parameternamen mit dem Bindestrich, wenn Sie die Syntax veranschaulichen. Umschließen Sie den Parameter in Backticks.

      Beispiel:

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

  • Die folgenden Elemente sollten mithilfe von Backticks formatiert werden (`):

    • Eigenschafts- und Parameterwerte

    • Geben Sie Namen im Stil von eckigen Klammern ein – Beispiel: [System.Io.FileInfo]

    • Bezugnahme auf Charaktere mit ihren Namen. Beispiel: Verwenden Sie das Sternchen (*) als Wildcard.

    • Sprachstichwörter und -operatoren

    • Cmdlet-, Funktions- und Skriptnamen

    • Befehls- und Parameter-Aliase

    • Methodennamen - Beispiel: Die ToString() Methode gibt eine Zeichenfolgendarstellung des Objekts zurück.

    • Variablen

    • Systemeigene Befehle

    • Datei- und Verzeichnispfade

    • Beispiele für Inlinebefehlssyntax – Siehe Markdown für Codebeispiele

      Dieses Beispiel zeigt einige Backtick-Beispiele:

      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
```

      In diesem Beispiel wird die Befehlssyntax inline veranschaulicht:

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

      Durch einschließen der Dateierweiterung wird sichergestellt, dass der richtige Befehl gemäß der Befehlsrangfolge von PowerShell ausgeführt wird.

Markdown für Codebeispiele

Markdown unterstützt zwei verschiedene Codeformatvorlagen:

  • Code spans (inline) - markiert durch ein einzelnes Backtick (`) Zeichen. Wird in einem Absatz anstelle als eigenständiger Block verwendet.
  • Codeblöcke – ein mehrzeiliges Block, umgeben von dreifachen Backtick-Zeichenfolgen (```). Codeblöcke können auch über eine Sprachbezeichnung verfügen, die den Backticks folgt. Die Sprachbeschriftung ermöglicht die Syntaxmarkierung für den Inhalt des Codeblocks.

Alle Codeblöcke sollten in einem Codezaun enthalten sein. Verwenden Sie nie den Einzug für Codeblöcke. Markdown lässt dieses Muster zu, kann aber problematisch sein und sollte vermieden werden.

Ein Codeblock ist eine oder mehrere Codezeilen, die von einem dreiseitigen Codezaun (```) umgeben sind. Die Codezaunmarkierungen müssen vor und nach dem Codebeispiel in einer eigenen Zeile stehen. Die Öffnende Markierung kann eine optionale Sprachbezeichnung aufweisen. Die Sprachbezeichnung ermöglicht die Syntaxmarkierung auf der gerenderten Webseite.

Eine vollständige Liste der unterstützten Sprachtags finden Sie unter "Eingezäunte Codeblöcke " im zentralen Mitwirkendenhandbuch.

Die Veröffentlichung fügt auch eine Schaltfläche "Kopieren " hinzu, mit der der Inhalt des Codeblocks in die Zwischenablage kopiert werden kann. Auf diese Weise können Sie den Code in ein Skript einfügen, um das Codebeispiel zu testen. Nicht alle Beispiele sollen jedoch wie geschrieben ausgeführt werden. Einige Codeblöcke sind grundlegende Abbildungen von PowerShell-Konzepten.

Es gibt drei Typen von Codeblöcken, die in unserer Dokumentation verwendet werden:

  1. Syntaxblöcke
  2. Illustrative Beispiele
  3. Ausführbare Beispiele

Syntaxcodeblöcke

Syntaxcodeblöcke werden verwendet, um die syntaktische Struktur eines Befehls zu beschreiben. Verwenden Sie keinen Sprachkennzeichnung im Codeblock. In diesem Beispiel werden alle möglichen Parameter des Get-Command Cmdlets veranschaulicht.

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

In diesem Beispiel wird die for Anweisung in generalisierten Ausdrücken beschrieben:

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

Illustrative Beispiele

Illustrative Beispiele werden verwendet, um ein PowerShell-Konzept zu erläutern. Yo'u sollte nach Möglichkeit keine PowerShell-Eingabeaufforderungen in Beispielen verwenden . Illustrative Beispiele sollen jedoch nicht für die Ausführung kopiert und eingefügt werden. Sie werden am häufigsten für einfache Beispiele verwendet, die leicht verständlich sind. Sie können die PowerShell-Eingabeaufforderung und die Beispielausgabe einschließen.

Hier ist ein einfaches Beispiel, das die PowerShell-Vergleichsoperatoren veranschaulicht. In diesem Fall beabsichtigen wir nicht, dass der Leser dieses Beispiel kopieren und ausführen kann. Beachten Sie, dass in diesem Beispiel eine vereinfachte Eingabeaufforderungszeichenfolge verwendet wird PS> .

```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
```

Ausführbare Beispiele

Komplexe Beispiele oder Beispiele, die kopiert und ausgeführt werden sollen, sollten das folgende Blockformat-Markup verwenden:

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

Die von PowerShell-Befehlen angezeigte Ausgabe sollte in einen Ausgabecodeblock eingeschlossen werden, um die Syntaxmarkierung zu verhindern. Beispiel:

```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
```

Die Output Codebezeichnung ist keine offizielle Sprache , die vom Syntaxhervorhebungssystem unterstützt wird. Diese Bezeichnung ist jedoch nützlich, da unser Veröffentlichungssystem das Output-Label zur Codefeld-Umrandung auf der Webseite hinzufügt. Das Codefeld " Ausgabe " weist keine Syntaxmarkierung auf.

Regeln für Codierungsstile

Vermeiden der Zeilenfortsetzung in Codebeispielen

Vermeiden Sie die Verwendung von Zeilenfortsetzungszeichen (`) in PowerShell-Codebeispielen. Backtick-Zeichen sind schwer zu erkennen und können Probleme verursachen, wenn am Ende der Zeile zusätzliche Leerzeichen vorhanden sind.

  • Verwenden Sie PowerShell-Splatting, um die Zeilenlänge für Cmdlets zu reduzieren, die mehrere Parameter haben.
  • Nutzen Sie die natürlichen Möglichkeiten zum Zeilenumbruch in PowerShell, z. B. nach Pipe-Zeichen (|), öffnenden geschweiften Klammern ({), runden Klammern (() und eckigen Klammern ([).

Vermeiden der Verwendung von PowerShell-Eingabeaufforderungen in Beispielen

Die Verwendung der Eingabeaufforderungszeichenfolge wird abgeraten und sollte auf Szenarien beschränkt sein, die die Befehlszeilenverwendung veranschaulichen sollen. Für die meisten dieser Beispiele sollte die Eingabeaufforderungszeichenfolge sein PS>. Diese Aufforderung ist unabhängig von betriebssystemspezifischen Indikatoren.

Eingabeaufforderungen sind in Beispielen erforderlich, um Befehle zu veranschaulichen, die die Eingabeaufforderung ändern oder wenn der angezeigte Pfad für das Szenario von Bedeutung ist. Im folgenden Beispiel wird veranschaulicht, wie sich die Eingabeaufforderung bei Verwendung des Registrierungsanbieters ändert.

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

Verwenden Sie in Beispielen keine Aliase

Verwenden Sie den vollständigen Namen aller Cmdlets und Parameter, es sei denn, Sie dokumentieren den Alias ausdrücklich. Cmdlet- und Parameternamen müssen die richtige Pascal-Schreibweise verwenden.

Verwenden von Parametern in Beispielen

Vermeiden Sie die Verwendung von Positionsparametern. Um die Wahrscheinlichkeit von Verwirrung zu verringern, sollten Sie den Parameternamen in ein Beispiel einschließen, auch wenn der Parameter positional ist.

Referenzartikel über Formatierungs-Cmdlets

Cmdlet-Referenzartikel weisen eine bestimmte Struktur auf. PlatyPS definiert diese Struktur. PlatyPS generiert die Cmdlet-Hilfe für PowerShell-Module in Markdown. Nachdem Sie die Markdown-Dateien bearbeitet haben, kann PlatyPS die MAML-Hilfedateien erstellen, die vom Cmdlet Get-Help verwendet werden.

PlatyPS verfügt über ein Schema, das eine bestimmte Struktur für die Cmdlet-Referenz erwartet. Das PlatyPS-Schemadokument beschreibt diese Struktur. Schemaverletzungen verursachen Buildfehler, die behoben werden müssen, bevor wir Ihren Beitrag akzeptieren können.

  • Entfernen Sie keine der ATX-Headerstrukturen. PlatyPS erwartet einen bestimmten Satz von Kopfzeilen in einer bestimmten Reihenfolge.
  • Die H2 INPUTS- und OUTPUTS-Header müssen den Typ H3 haben. Wenn das Cmdlet keine Eingaben übernimmt oder einen Wert zurückgibt, verwenden Sie den Wert None für H3.
  • Inlinecodespannen können in jedem Absatz verwendet werden.
  • Eingezäunte Codeblöcke sind nur im Abschnitt BEISPIELE zulässig.

Im PlatyPS-Schema ist EXAMPLES ein H2-Header. Jedes Beispiel ist eine H3-Kopfzeile. Innerhalb eines Beispiels lässt das Schema nicht zu, dass Codeblöcke durch Absätze getrennt werden. Das Schema lässt nur die folgende Struktur zu:

### Example X - Title sentence

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

Nummerieren Sie jedes Beispiel, und fügen Sie einen kurzen Titel hinzu.

Beispiel:

### 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
```

Formatierung von About_-Dateien

About_* Dateien werden in Markdown geschrieben, werden aber als Nur-Text-Dateien ausgeliefert. Wir verwenden Pandoc , um markdown in Nur-Text zu konvertieren. About_* Dateien sind für die beste Kompatibilität in allen Versionen von PowerShell und mit den Veröffentlichungstools formatiert.

Grundlegende Formatierungsrichtlinien:

  • Beschränken von Absatzzeilen auf 80 Zeichen

  • Beschränken von Codeblöcken auf 76 Zeichen

  • Beschränken von Blockquotes und Warnungen auf 78 Zeichen

  • Bei Verwendung dieser Speziellen Metazeichen \$und <:

    • Innerhalb einer Kopfzeile müssen diese Zeichen mit einem führenden \ Zeichen oder in Code eingeschlossenen Zeichen mithilfe von Backticks` () escapet werden.

    • Innerhalb eines Absatzes sollten diese Zeichen in Codespannen eingefügt werden. Beispiel:

      ### The purpose of the \$foo variable

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

  • Markdowntabellen

    • Für About_* Artikel müssen Tabellen innerhalb von 76 Zeichen passen.
      • Wenn der Inhalt nicht in den Grenzwert von 76 Zeichen passt, verwenden Sie stattdessen Aufzählungen.
    • Verwenden von öffnenden und schließenden | Zeichen in jeder Zeile

Nächste Schritte

Redaktionelle Checkliste

  • Last updated on