Sdílet prostřednictvím

PowerShell – průvodce stylem dokumentace

Tento článek obsahuje pokyny ke stylu specifické pro obsah PowerShell-Docs. Vychází z informací uvedených v přehledu.

Formátování elementů syntaxe příkazů

Pomocí následujících pravidel můžete formátovat prvky jazyka PowerShellu, když se prvky použijí ve větě.

  • Vždy používejte úplný název pro cmdlety a parametry ve správném typu zápisu Pascal Case.

  • Alias použijte jen tehdy, když ukazujete, jak ho používat.

  • Klíčová slova a operátory PowerShellu by měly být malými písmeny.

  • Následující položky by měly být formátované tučným písmem:

    • Názvy typů

    • Názvy tříd

    • Názvy vlastností

    • Názvy parametrů

      • Ve výchozím nastavení použijte parametr bez předpony spojovníku.
      • Pokud znázorníte syntaxi, použijte název parametru se spojovníkem. Zabalte parametr do zpětných uvozovek.

      Například:

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

  • Následující položky by měly být formátovány pomocí zpětných apostrofů (`):

    • Hodnoty vlastností a parametrů

    • Zadejte názvy, které používají styl závorek – například: [System.Io.FileInfo]

    • Odkaz na postavy podle jména. Příklad: Jako zástupný znak použijte hvězdičku (*).

    • Klíčová slova a operátory jazyka

    • Názvy cmdlet, funkcí a skriptů

    • Aliasy příkazů a parametrů

    • Názvy metod – Například: Metoda ToString() vrátí řetězcovou reprezentaci objektu.

    • Proměnné

    • Nativní příkazy

    • Cesty k souborům a adresářům

    • Příklady syntaxe vložených příkazů – Podívejte se na Markdown pro ukázky kódu

      Tento příklad ukazuje několik příkladů zpětného zadku:

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

      Tento příklad ukazuje syntaxi příkazu přímo v textu:

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

      Zahrnutím přípony souboru zajistíte, že se spustí správný příkaz podle priority příkazů PowerShellu.

Markdown pro ukázky kódu

Markdown podporuje dva různé styly kódu:

  • Kódové úseky (vložené) – označené jedním znakem zpětného apostrofu (`). Používá se v odstavci místo jako samostatný blok.
  • Bloky kódu – víceřádkový blok obklopený trojitými backtickovými (```) řetězci. Bloky kódu mohou mít také popisek jazyka za zpětnými apostrofy. Popisek jazyka umožňuje zvýrazňování syntaxe pro obsah bloku kódu.

Všechny bloky kódu by měly být obsaženy v plotu kódu. Nikdy nepoužívejte odsazení pro bloky kódu. Markdown umožňuje tento způsob, ale může být problematický a mělo by se mu vyhnout.

Blok kódu je složený z jednoho nebo více řádků kódu obklopeného kódovým plotem z trojitých zpětných apostrofů (```). Značky oddělovače kódu musí být na samostatném řádku před a za vzorovým kódem. Úvodní značka může mít volitelný jazykový popisek. Popisek jazyka umožňuje zvýraznění syntaxe na vykreslené webové stránce.

Úplný seznam podporovaných značek jazyka najdete v části Ohraničené bloky kódu v centralizované příručce pro přispěvatele.

Publikování také přidá tlačítko Kopírovat , které může zkopírovat obsah bloku kódu do schránky. To vám umožní vložit kód do skriptu pro otestování ukázky kódu. Ne všechny příklady však mají být spouštěné jako napsané. Některé bloky kódu jsou základní ilustrace konceptů PowerShellu.

V naší dokumentaci se používají tři typy bloků kódu:

  1. Bloky syntaxe
  2. Ilustrativní příklady
  3. Spustitelné příklady

Bloky kódu syntaxe

Bloky kódu syntaxe slouží k popisu syntaktické struktury příkazu. Nepoužívejte značku jazyka v bloku kódu. Tento příklad ukazuje všechny možné parametry rutiny Get-Command .

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

Tento příklad popisuje for příkaz v generalizovaných termínech:

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

Ilustrativní příklady

Ilustrativní příklady slouží k vysvětlení konceptu PowerShellu. Yo'u by se mělo vyhnout použití výzev PowerShellu v příkladech , kdykoli je to možné. Ilustrativní příklady ale nejsou určené ke zkopírování a vložení ke spuštění. Nejčastěji se používají pro jednoduché příklady, které jsou snadno pochopitelné. Můžete zahrnout příkazový řádek PowerShellu a ukázkový výstup.

Tady je jednoduchý příklad znázorňující operátory porovnání PowerShellu. V tomto případě nemáme v úmyslu, aby čtenář tento příklad zkopíroval a spustil. Všimněte si, že tento příklad používá PS> jako zjednodušený řetězec výzvy.

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

Spustitelné příklady

Složité příklady nebo příklady, které mají být zkopírovány a spouštěné, by měly používat následující značky ve stylu bloku:

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

Výstup zobrazený příkazy PowerShellu by se měl uzavřít do bloku výstupního kódu, aby se zabránilo zvýraznění syntaxe. Například:

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

Popisek Output kódu není oficiálním jazykem podporovaným systémem zvýrazňování syntaxe. Tento popisek je ale užitečný, protože náš systém publikování přidá popisek Výstup do rámečku pole kódu na webové stránce. Pole Výstupní kód neobsahuje žádné zvýraznění syntaxe.

Pravidla stylu kódování

Vyhněte se pokračování řádku v ukázkách kódu

V příkladech kódu PowerShellu nepoužívejte znaky pokračování řádku (`). Znaky zpětného apostrofu jsou obtížně viditelné a mohou způsobit problémy, pokud jsou na konci řádky nadbytečné mezery.

  • Použijte PowerShell "splatting" ke zkrácení délky řádků při používání rutin PowerShellu, které mají několik parametrů.
  • Využijte přirozené možnosti přerušení řádku v PowerShellu, jako jsou znaky pipe (|), levé složené závorky ({), kulaté závorky (() a hranaté závorky ([).

Vyhněte se používání výzev PowerShellu v příkladech

Použití řetězce výzvy se nedoporučuje a mělo by být omezeno pouze na scénáře, které mají ilustrovat použití příkazového řádku. Pro většinu těchto příkladů by řetězec výzvy měl být PS>. Tato výzva je nezávislá na indikátorech specifických pro operační systém.

Výzvy jsou vyžadovány v příkladech k ilustraci příkazů, které mění výzvu nebo kdy zobrazená cesta je pro daný scénář významná. Následující příklad ukazuje, jak se výzva změní při použití poskytovatele služby registru.

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

Nepoužívejte aliasy v příkladech

Používejte úplné názvy všech rutin a parametrů, pokud nezdokumentováváte specifický alias. Názvy rutin a parametrů musí používat správné Pascal-cased názvy.

Použití parametrů v příkladech

Nepoužívejte poziční parametry. Pokud chcete snížit pravděpodobnost nejasnosti, měli byste do příkladu zahrnout název parametru, i když je parametr poziční.

Referenční články cmdletů o formátování

Články s referencemi na cmdlety mají specifickou strukturu. PlatyPS definuje tuto strukturu. PlatyPS generuje nápovědu příkazů pro moduly PowerShellu v Markdownu. Po úpravě souborů Markdown může PlatyPS vytvořit soubory nápovědy MAML používané rutinou Get-Help .

PlatyPS má schéma, které očekává konkrétní strukturu pro odkazy na cmdlety. Dokument schématu PlatyPS popisuje tuto strukturu. Porušení schématu způsobují chyby sestavení, které je nutné opravit, než budeme moct váš příspěvek přijmout.

  • Neodebíjejte žádné struktury záhlaví ATX. PlatyPS očekává konkrétní sadu hlaviček v určitém pořadí.
  • Hlavičky INPUTS a OUTPUTS typu H2 musí být typu H3. Pokud rutina nepřebere vstup nebo nevrací hodnotu, použijte hodnotu None pro H3.
  • Vložený kód lze použít v libovolném odstavci.
  • Ohraničené bloky kódu jsou povoleny pouze v části PŘÍKLADY .

Ve schématu PlatyPS je příklady hlavička H2. Každý příklad je hlavička H3. V rámci příkladu schéma neumožňuje, aby byly bloky kódu odděleny odstavcem. Schéma umožňuje pouze následující strukturu:

### Example X - Title sentence

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

Očíslujte každý příklad a přidejte stručný název.

Například:

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

Formátování souborů About_

About_* soubory jsou napsané v Markdownu, ale jsou dodávány jako soubory ve formátu prostého textu. K převodu Markdownu na prostý text používáme Pandoc . About_* soubory jsou formátované tak, aby byly co nejsnáze kompatibilní ve všech verzích PowerShellu a s nástroji pro publikování.

Základní pokyny k formátování:

  • Omezení řádků odstavce na 80 znaků

  • Omezení bloků kódu na 76 znaků

  • Omezení blokových citací a upozornění na 78 znaků

  • Při použití těchto speciálních metaznaků \, $ a <:

    • V záhlaví musí být tyto znaky uvozené pomocí úvodního \ znaku nebo uzavřené do kódových úseků pomocí backticků (`).

    • V odstavci by tyto znaky měly být vloženy do rozsahů kódu. Například:

      ### The purpose of the \$foo variable

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

  • Tabulky Markdownu

    • U About_* článků musí tabulky odpovídat 76 znakům.
      • Pokud se obsah nevejde do limitu 76 znaků, použijte místo toho seznamy odrážek.
    • Použijte otevírací a uzavírací | znaky na každém řádku.

Další kroky

Redakční kontrolní seznam