A PowerShell Docs stílusútmutatója

Ez a cikk a PowerShell-Docs tartalomra vonatkozó stílus útmutatást nyújt. Az Áttekintésben ismertetett információkra épül.

Formázási parancsszintaxis elemei

Az alábbi szabályokkal formázhatja a PowerShell-nyelv elemeit, amikor az elemeket egy mondatban használják.

  • A parancsmagok és paraméterek teljes nevét mindig a megfelelő Pascal-esetben használja

  • Csak akkor használjon aliast, ha kifejezetten az aliast mutatja be

  • A PowerShell-kulcsszavaknak és operátoroknak kisbetűknek kell lenniük

  • A következő elemeket félkövér szöveg használatával kell formázni:

    • Típusnevek

    • Osztálynevek

    • Tulajdonságnevek

    • Paraméternevek

      • Alapértelmezés szerint használja a paramétert a kötőjel előtagja nélkül.
      • Használja a paraméter nevét a kötőjellel, ha szintaxist szemléltet. Csatolja a paramétert backticks közé.

      Például:

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

  • A következő elemeket backticks (`) használatával kell formázni:

    • Tulajdonság- és paraméterértékek

    • Írja be a zárójeles stílust használó neveket – Például: [System.Io.FileInfo]

    • Név szerint hivatkozik a karakterekre. Például: Használja a csillag karaktert (*) helyettesítő karakterként.

    • Nyelvi kulcsszavak és operátorok

    • Parancsmagok, függvények és szkriptnevek

    • Parancs- és paraméteraliasok

    • Metódusnevek – Például: A ToString() metódus az objektum sztring-ábrázolását adja vissza

    • Változók

    • Natív parancsok

    • Fájl- és könyvtárelérési utak

    • Beágyazott parancsszintaxis-példák – Kódmintákért lásd a Markdownt

      Ez a példa néhány `backtick` példát mutat be:

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

      Ez a példa a parancsszintaxis beágyazott szövegét mutatja be:

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

      A fájlkiterjesztést is beleértve biztosítja, hogy a megfelelő parancs végrehajtása a PowerShell parancselőzményeinek megfelelően legyen végrehajtva.

Markdown kódmintákhoz

A Markdown két különböző kódstílust támogat:

  • Kódszakaszok (soron belül) – egyetlen visszafelé dőlő aposztróffal (`) jelölve. Nem önálló blokkként, hanem bekezdésen belül használható.
  • Kódblokkok – egy többsoros blokk, amelyet háromoldalas (```) sztringek vesznek körül. A kódblokkok a visszafelé mutató ékezetek után lévő nyelvi címkével is rendelkezhetnek. A nyelvi címke lehetővé teszi a kódblokk tartalmának szintaxiskiemelését.

Minden kódblokkot egy kódkerítésben kell tárolni. Soha ne használjon behúzást kódblokkokhoz. Markdown lehetővé teszi ezt a mintát, de lehet, hogy problémás, és el kell kerülni.

A kódblokk egy vagy több kódsort tartalmaz, amelyeket egy tripla-backtick (```) kódkerítés vesz körül. A kódkerítési jelölőknek a kódminta előtt és után a saját sorban kell lenniük. A nyitó jelölő opcionális nyelvi címkével is rendelkezhet. A nyelvi címke lehetővé teszi a szintaxiskiemelést a renderelt weblapon.

A támogatott nyelvi címkék teljes listájáért tekintse meg a központosított közreműködői útmutatóban található elkerített kódblokkokat .

A közzététel egy Másolás gombot is hozzáad, amely átmásolhatja a kódblokk tartalmát a vágólapra. Így beillesztheti a kódot egy szkriptbe a kódminta teszteléséhez. Azonban nem minden példa van arra szánva, hogy pontosan úgy futtassák, ahogyan írva van. Egyes kódblokkok a PowerShell-fogalmak alapvető illusztrációi.

A dokumentációban háromféle kódblokkot használunk:

  1. Szintaxisblokkok
  2. Szemléltető példák
  3. Végrehajtható példák

Szintaxis kódrészletek

A szintaxiskódblokkok a parancsok szintaktikai szerkezetének leírására szolgálnak. Ne használjon nyelvi címkét a kódkerítésen. Ez a példa a parancsmag összes lehetséges paraméterét szemlélteti 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>]
```

Ez a példa az for utasítást általánosítva írja le:

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

Szemléltető példák

Szemléltető példákat használunk a PowerShell-koncepciók magyarázatára. Amennyire csak lehet, kerülje a PowerShell-parancssorok használatát példákban. A szemléltető példákat azonban nem kell másolni és beilleszteni a végrehajtáshoz. Ezeket leggyakrabban egyszerű, könnyen érthető példákhoz használják. A PowerShell-parancssor és a példakimenet is szerepelhet.

Íme egy egyszerű példa, amely a PowerShell-összehasonlító operátorokat szemlélteti. Ebben az esetben nem tervezzük, hogy az olvasó másolja és futtassa ezt a példát. Figyelje meg, hogy ez a példa egyszerűsített parancssori sztringként használja 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
```

Végrehajtható példák

Az összetett példáknak vagy a másolandó és végrehajtható példáknak a következő blokkstílusú korrektúrát kell használniuk:

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

A PowerShell-parancsok által megjelenített kimenetet a szintaxiskiemelés megakadályozása érdekében kimeneti kódblokkba kell zárni. Például:

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

A Output kódcímke nem a szintaxiskiemelő rendszer által támogatott hivatalos nyelv . Ez a címke azonban azért hasznos, mert a közzétételi rendszer hozzáadja a Kimeneti címkét a weblap kóddobozkeretéhez. A Kimeneti kód mező nem emel ki szintaxist.

Kódolási stílusszabályok

A sor folytatásának elkerülése kódmintákban

Ne használjon sorfolytatási karaktereket (`) a PowerShell-kód példákban. A backtick karakterek nehezen láthatók, és problémákat okozhatnak, ha a sor végén extra szóközök vannak.

  • A PowerShell splattinget használja a parancsmagok vonalhosszának csökkentésére, ha több paraméter van megadva.
  • Használja ki a PowerShell természetes vonaltörési lehetőségeit, például a pipa (|) karakterek után, a nyitó zárójelek ({), zárójelek (() és zárójelek ([) után.

Példákban ne használjon PowerShell-utasításokat

A parancssori sztring használata nem ajánlott, és olyan forgatókönyvekre kell korlátozódnia, amelyek a parancssori használat szemléltetésére szolgálnak. A legtöbb ilyen példa esetében a parancssori sztringnek kell lennie PS>. Ez a kérés az operációs rendszerspecifikus mutatóktól független.

A példákban utasításokat kell megadni a parancssort módosító parancsok szemléltetéséhez, vagy ha a megjelenített elérési út jelentős a forgatókönyv szempontjából. Az alábbi példa bemutatja, hogyan változik a kérés a beállításjegyzék-szolgáltató használatakor.

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

Ne használjon aliasokat példákban

Használja az összes parancsmag és paraméter teljes nevét, kivéve, ha kifejezetten az aliast dokumentálja. A parancsmagoknak és a paraméterneveknek a megfelelő Pascal-kisbetűs neveket kell használniuk .

Paraméterek használata példákban

Kerülje a pozícióparaméterek használatát. Az összetévesztés esélyének csökkentése érdekében a paraméter nevét is fel kell venni egy példába, még akkor is, ha a paraméter pozíciós.

A formázási parancsmag hivatkozási cikkei

A parancsmag-referenciacikkek felépítése meghatározott. A PlatyPS ezt a struktúrát határozza meg. A PlatyPS létrehozza a Parancsmag súgóját a Markdown PowerShell-moduljaihoz. A Markdown-fájlok szerkesztése után a PlatyPS létrehozhatja a parancsmag által Get-Help használt MAML-súgófájlokat.

A PlatyPS egy olyan sémával rendelkezik, amely egy adott struktúrát vár a parancsmagok hivatkozásához. A PlatyPS sémadokumentum ezt a struktúrát írja le. A sémasértések olyan összeállítási hibákat okoznak, amelyeket ki kell javítani a hozzájárulás elfogadása előtt.

  • Ne távolítsa el az ATX-fejlécstruktúrákat. A PlatyPS egy adott fejléckészletet vár egy adott sorrendben.
  • A H2 INPUTS és OUTPUTS fejléceknek H3 típusúnak kell lenniük. Ha a parancsmag nem fogad bemenetet, vagy nem ad vissza értéket, használja a H3 értékét None .
  • A sorközi kódrészletek bármely bekezdésben használhatók.
  • A bekerített kódblokkok csak a EXAMPLES szakaszban engedélyezettek .

A PlatyPS sémában az EXAMPLES egy H2 fejléc. Minden példa egy H3 fejléc. Egy példában a séma nem teszi lehetővé a kódblokkok bekezdésekkel való elválasztásához. A séma csak a következő struktúrát engedélyezi:

### Example X - Title sentence

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

Számozza meg az egyes példákat, és adjon hozzá egy rövid címet.

Például:

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

Az About_ fájlok formázása

About_* a fájlok a Markdownban vannak megírva, de egyszerű szöveges fájlként vannak kézbesítve. A Pandoc használatával egyszerű szöveggé alakítjuk a Markdownt. About_* A fájlok a PowerShell minden verziójában és a közzétételi eszközökkel való legjobb kompatibilitás érdekében vannak formázva.

Alapvető formázási irányelvek:

  • Bekezdéssorok korlátozása 80 karakterre

  • Kódblokkok korlátozása 76 karakterre

  • Blokkkvóták és riasztások korlátozása 78 karakterre

  • A speciális metakarakterek \, $, és < használatakor:

    • A fejlécen belül ezeket a karaktereket kezdő \ karakterrel kell megszűrni, vagy kódfedésbe kell őket belefoglalni a háttérjelek használatával (`)

    • Egy bekezdésen belül ezeket a karaktereket kódrészletbe kell helyezni. Például:

      ### The purpose of the \$foo variable

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

  • Markdown-táblák

    • Cikkek esetén About_* a táblázatoknak 76 karakteren belül kell elférniük
      • Ha a tartalom nem fér el a 76 karakteres korláton belül, használjon felsorolást.
    • Nyitó és záró | karakterek használata minden sorban

Következő lépések

Szerkesztői ellenőrzőlista

  • Last updated on