Udostępnij za pomocą

PowerShell-Docs — przewodnik dotyczący stylu

Ten artykuł zawiera wskazówki dotyczące stylu specyficzne dla zawartości PowerShell-Docs. Opiera się na informacjach opisanych w przeglądzie.

Formatowanie elementów składni poleceń

Użyj następujących reguł, aby sformatować elementy języka programu PowerShell, gdy elementy są używane w zdaniu.

  • Zawsze używaj pełnej nazwy poleceń „cmdlet” i parametrów zgodnie z konwencją Pascal.

  • Używaj aliasu tylko wtedy, gdy konkretnie go demonstrujesz

  • Słowa kluczowe i operatory programu PowerShell powinny mieć małe litery

  • Następujące elementy powinny być sformatowane przy użyciu pogrubionego tekstu:

    • Nazwy typów

    • Nazwy klas

    • Nazwy właściwości

    • Nazwy parametrów

      • Zaleca się, aby domyślnie używać parametru bez prefiksu kreski.
      • Użyj nazwy parametru z łącznikiem, jeśli ilustrujesz składnię. Owiń parametr w apostrofy tylne.

      Na przykład:

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

  • Następujące elementy powinny być sformatowane przy użyciu backticks (`):

    • Wartości właściwości i parametrów

    • Nazwy typów używające stylu nawiasów — na przykład: [System.Io.FileInfo]

    • Odwoływanie się do postaci po imieniu. Na przykład: użyj znaku gwiazdki (*) jako symbolu wieloznacznego.

    • Słowa kluczowe i operatory języka

    • Nazwy poleceń cmdlet, funkcji i skryptów

    • Aliasy poleceń i parametrów

    • Nazwy metod — na przykład: ToString() metoda zwraca reprezentację ciągu obiektu

    • Zmienne

    • Polecenia natywne

    • Ścieżki plików i katalogów

    • Przykłady składni poleceń wbudowanych — zobacz Markdown, aby zapoznać się z przykładami kodu

      W tym przykładzie przedstawiono kilka przykładów 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
```

      W tym przykładzie pokazano składnię polecenia w tekście:

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

      Dołączenie rozszerzenia pliku gwarantuje, że prawidłowe polecenie jest wykonywane zgodnie z pierwszeństwem polecenia programu PowerShell.

Kod Markdown dla przykładów kodu

Język Markdown obsługuje dwa różne style kodu:

  • Zakresy kodu (wbudowane) — oznaczone pojedynczym znakiem backtick (`). Używany w akapicie, a nie jako autonomiczny blok.
  • Bloki kodu — blok wielowierszowy otoczony potrójnymi ciągami backtick (```). Bloki kodu mogą również mieć etykietę języka po backticksach. Etykieta języka umożliwia wyróżnianie składni dla zawartości bloku kodu.

Wszystkie bloki kodu powinny być zawarte w ogrodzeniu kodu. Nigdy nie używaj wcięcia dla bloków kodu. Markdown umożliwia stosowanie tego schematu, ale może być problematyczne i należy go unikać.

Blok kodu to jeden lub więcej wierszy kodu otoczonych potrójnymi znakami cudzysłowu (```). Znaczniki ogrodzenia kodu muszą znajdować się w osobnym wierszu przed i po przykładzie kodu. Znacznik otwarcia może mieć opcjonalną etykietę języka. Etykieta języka umożliwia wyróżnianie składni na renderowanej stronie internetowej.

Aby uzyskać pełną listę obsługiwanych tagów językowych, zobacz Ogrodzone bloki kodu w scentralizowanym przewodniku współautora.

Publikowanie dodaje również przycisk Kopiuj , który może skopiować zawartość bloku kodu do schowka. Dzięki temu możesz wkleić kod do skryptu, aby przetestować przykładowy kod. Jednak nie wszystkie przykłady mają być uruchamiane zgodnie z zapisem. Niektóre bloki kodu to podstawowe ilustracje pojęć programu PowerShell.

W naszej dokumentacji są używane trzy typy bloków kodu:

  1. Bloki składni
  2. Przykłady ilustracyjne
  3. Przykłady plików wykonywalnych

Bloki kodu składniowego

Bloki kodu składniowego służą do opisywania struktury składni polecenia. Nie używaj tagu języka na bloku kodu. W tym przykładzie przedstawiono wszystkie możliwe parametry polecenia cmdlet 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>]
```

W tym przykładzie opisano instrukcję for w uogólnionych terminach:

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

Przykłady ilustracyjne

Ilustracyjne przykłady służą do wyjaśnienia koncepcji programu PowerShell. Yo'u powinien unikać używania monitów programu PowerShell w przykładach, gdy jest to możliwe. Jednak ilustracyjne przykłady nie mają być kopiowane i wklejane do wykonania. Są one najczęściej używane w przypadku prostych przykładów, które są łatwe do zrozumienia. Możesz dołączyć wiersz polecenia programu PowerShell i przykładowe dane wyjściowe.

Oto prosty przykład ilustrujący operatory porównania programu PowerShell. W tym przypadku nie zamierzamy, aby czytelnik kopiował i uruchamiał tego przykładu. Zwróć uwagę, że w tym przykładzie użyto PS> jako uproszczonego ciągu monitu.

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

Przykłady plików wykonywalnych

Złożone przykłady lub przykłady, które mają zostać skopiowane i wykonane, powinny używać następującego znacznika stylu blokowego:

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

Dane wyjściowe wyświetlane przez polecenia programu PowerShell powinny być ujęte w bloku kodu wyjściowego , aby zapobiec wyróżnianiu składni. Na przykład:

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

Etykieta Output kodu nie jest językiem oficjalnym obsługiwanym przez system wyróżniania składni. Jednak ta etykieta jest przydatna, ponieważ nasz system publikowania dodaje etykietę Dane wyjściowe do ramki pola kodu na stronie internetowej. Pole Kod wyjściowy nie ma wyróżniania składni.

Reguły stylu kodowania

Unikaj kontynuacji wiersza w przykładach kodu

Unikaj używania znaków kontynuacji wiersza (`) w przykładach kodu programu PowerShell. Znaki backtick są trudne do dostrzeżenia i mogą powodować problemy, jeśli na końcu linii występują dodatkowe spacje.

  • Użyj splattingu programu PowerShell, aby zmniejszyć długość wiersza poleceń cmdlet, które mają kilka parametrów.
  • Skorzystaj z możliwości naturalnego podziału wiersza programu PowerShell, takich jak znaki kreski kreskowej (|), otwierające nawiasy klamrowe ({), nawiasy (() i nawiasy[ ().

Unikaj używania monitów programu PowerShell w przykładach

Nie zaleca się używania ciągu wiersza polecenia i powinno być ograniczone do scenariuszy, które mają na celu zilustrowanie użycia wiersza polecenia. W większości tych przykładów ciąg monitu powinien mieć wartość PS>. Ten monit jest niezależny od wskaźników specyficznych dla systemu operacyjnego.

Monity są wymagane w przykładach, aby zilustrować polecenia, które zmieniają wiersz polecenia, lub gdy wyświetlana ścieżka jest znacząca dla scenariusza. W poniższym przykładzie pokazano, jak komunikat zmienia się podczas korzystania z dostawcy rejestru.

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

Nie używaj aliasów w przykładach

Używaj pełnej nazwy wszystkich poleceń cmdlet i parametrów, chyba że dokumentujesz alias. Nazwy poleceń cmdlet i parametrów muszą używać odpowiednich nazw z literami Pascal .

Używanie parametrów w przykładach

Unikaj używania parametrów pozycyjnych. Aby zmniejszyć prawdopodobieństwo nieporozumień, należy uwzględnić nazwę parametru w przykładzie, nawet jeśli parametr jest pozycyjny.

Artykuły referencyjne dotyczące formatowania poleceń cmdlet

Artykuły referencyjne cmdletów mają określoną strukturę. PlatyPS definiuje tę strukturę. Narzędzie PlatyPS generuje dokumentację poleceń cmdlet dla modułów programu PowerShell w formacie Markdown. Po edytowaniu tych plików języka Markdown, narzędzie PlatyPS może utworzyć pliki pomocy MAML używane przez Get-Help cmdlet.

PlatyPS ma schemat, który oczekuje określonej struktury odniesienia do cmdlet. Dokument schematu PlatyPS opisuje tę strukturę. Naruszenia schematu powodują błędy kompilacji, które należy naprawić, zanim zaakceptujemy Twój wkład.

  • Nie usuwaj żadnej struktury nagłówka ATX. PlatyPS oczekuje określonego zestawu nagłówków w określonej kolejności.
  • Nagłówki H2 INPUTS i OUTPUTS muszą mieć typ H3. Jeśli polecenie cmdlet nie pobiera danych wejściowych ani nie zwraca wartości, użyj wartości None dla H3.
  • Wbudowane zakresy kodu mogą być używane w dowolnym akapicie.
  • Ogrodzone bloki kodu są dozwolone tylko w sekcji PRZYKŁADY .

W schemacie PlatyPS PRZYKŁADY to nagłówek H2. Każdy przykład to nagłówek H3. W przykładzie schemat nie zezwala na oddzielanie bloków kodu akapitami. Schemat umożliwia tylko następującą strukturę:

### Example X - Title sentence

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

Numeruj każdy przykład i dodaj krótki tytuł.

Na przykład:

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

Formatowanie plików About_

About_* pliki są zapisywane w języku Markdown, ale są dostarczane jako pliki zwykłego tekstu. Używamy narzędzia Pandoc do konwertowania języka Markdown na zwykły tekst. About_* pliki są formatowane w celu zapewnienia najlepszej zgodności we wszystkich wersjach programu PowerShell i przy użyciu narzędzi do publikowania.

Podstawowe wytyczne dotyczące formatowania:

  • Ogranicz wiersze akapitu do 80 znaków

  • Ogranicz bloki kodu do 76 znaków

  • Ogranicz cytaty blokowe i alerty do 78 znaków

  • W przypadku używania tych specjalnych meta-znaków \, $, i <:

    • W nagłówku te znaki muszą być poprzedzone znakiem \ lub ujęte w zakresy kodu za pomocą znaków `backticks` (`).

    • W akapicie te znaki powinny być umieszczane w blokach kodu. Na przykład:

      ### The purpose of the \$foo variable

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

  • Tabele języka Markdown

    • W przypadku About_* artykułów tabele muszą mieścić się w ciągu 76 znaków
      • Jeśli zawartość nie mieści się w limicie 76 znaków, użyj listy wypunktowanej.
    • Używanie znaków otwierających i zamykających | w każdym wierszu

Następne kroki

lista kontrolna redakcyjna

  • Last updated on