Dela via

PowerShell-Docs stilguide

Den här artikeln innehåller stilvägledning som är specifik för PowerShell-Docs innehåll. Den bygger på den information som beskrivs i översikten.

Formatering av kommandosyntaxelement

Använd följande regler för att formatera element i PowerShell-språket när elementen används i en mening.

  • Använd alltid det fullständiga namnet för cmdletar och parametrar i rätt Pascal-fall

  • Använd endast ett alias när du specifikt demonstrerar aliaset

  • Nyckelord och operatorer i PowerShell bör vara gemener

  • Följande objekt ska formateras med fet text:

    • Skriv namn

    • Klassnamn

    • Egenskapsnamn

    • Parameternamn

      • Använd som standard parametern utan bindestreckprefixet.
      • Använd parameternamnet med bindestrecket om du illustrerar syntaxen. Omslut parametern i backticks.

      Till exempel:

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

  • Följande objekt ska formateras med hjälp av backticks (`):

    • Egenskaps- och parametervärden

    • Skriv namn som använder det hakparenteserade formatet – till exempel: [System.Io.FileInfo]

    • Refererar till karaktärer med namn. Till exempel: Använd asterisktecknet (*) som jokertecken.

    • Språknyckelord och operatorer

    • Cmdlet-, funktions- och skriptnamn

    • Kommando- och parameteralias

    • Metodnamn – Till exempel: Metoden ToString() returnerar en strängrepresentation av objektet

    • Variabler

    • Interna kommandon

    • Fil- och katalogsökvägar

    • Exempel på infogad kommandosyntax – Se Markdown för kodexempel

      Det här exemplet visar några exempel på 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
```

      I det här exemplet visas kommandosyntaxen i texten:

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

      Om du inkluderar filtillägget ser du till att rätt kommando körs enligt PowerShells kommandoprioret.

Markdown för kodexempel

Markdown har stöd för två olika kodformat:

  • Kodavsnitt (i text) – markeras med ett enda backtick-tecken (`). Används i ett stycke i stället för som ett fristående block.
  • Kodblock – ett flerradsblock omgivet av trebackssträngar (```). Ett kodblock kan också ha en språketikett efter backticks. Språketiketten aktiverar syntaxmarkering för innehållet i kodblocket.

Alla kodblock ska finnas i ett kodstängsel. Använd aldrig indrag för kodblock. Markdown tillåter det här mönstret, men det kan vara problematiskt och bör undvikas.

Ett kodblock är en eller flera kodrader som omges av ett trippel-backtick-kodstängsel (```). Kodstängselmarkörerna måste finnas på sin egen rad före och efter kodexemplet. Öppningsmarkören kan ha en valfri språketikett. Språketiketten aktiverar syntaxmarkering på den renderade webbsidan.

En fullständig lista över språktaggar som stöds finns i Inhägnade kodblock i den centraliserade deltagarguiden.

Publicering lägger också till en Kopiera-knapp som kan kopiera innehållet i kodblocket till urklipp. På så sätt kan du klistra in koden i ett skript för att testa kodexemplet. Alla exempel är dock inte avsedda att köras som skrivna. Vissa kodblock är grundläggande illustrationer av PowerShell-begrepp.

Det finns tre typer av kodblock som används i vår dokumentation:

  1. Syntaxblock
  2. Illustrativa exempel
  3. Körbara exempel

Kodblock för syntax

Syntaxkodblock används för att beskriva den syntaktiska strukturen för ett kommando. Använd inte en språktagg på kodstaketet. Det här exemplet illustrerar alla möjliga parametrar för cmdleten 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>]
```

I det här exemplet beskrivs instruktionen for i generaliserade termer:

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

Illustrativa exempel

Illustrativa exempel används för att förklara ett PowerShell-koncept. Yo'u bör undvika att använda PowerShell-prompter i exempel när det är möjligt. Illustrativa exempel är dock inte avsedda att kopieras och klistras in för exekvering. De används oftast för enkla exempel som är lätta att förstå. Du kan inkludera PowerShell-prompten och exempelutdata.

Här är ett enkelt exempel som illustrerar PowerShell-jämförelseoperatorerna. I det här fallet tänker vi inte att läsaren ska kopiera och köra det här exemplet. Observera att det här exemplet använder PS> som en förenklad promptsträng.

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

Körbara exempel

Komplexa exempel, eller exempel som är avsedda att kopieras och köras, bör använda följande blockformatsmarkering:

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

Utdata som visas med PowerShell-kommandon ska omges av ett kodblock för utdata för att förhindra syntaxmarkering. Till exempel:

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

Kodetiketten Output är inte ett officiellt språk som stöds av syntaxmarkeringssystemet. Den här etiketten är dock användbar eftersom vårt publiceringssystem lägger till utdataetiketten i kodruteramen på webbsidan. Utdatakodrutan har ingen syntaxbelysning.

Kodningsformatregler

Undvik radfortsättning i kodexempel

Undvik att använda radfortsättningstecken (`) i PowerShell-kodexempel. Bakåtstreck är svåra att se och kan orsaka problem om det finns extra mellanslag i slutet av raden.

  • Använd PowerShell-splatting för att minska linjelängden för cmdletar som har flera parametrar.
  • Dra nytta av PowerShells naturliga radbrytningsmöjligheter, till exempel tecken efter rör (|), inledande klammerparenteser ({), parenteser (() och hakparenteser ([).

Undvik att använda PowerShell-prompter i exempel

Användning av promptsträngen rekommenderas inte och bör begränsas till scenarier som är avsedda att illustrera kommandoradsanvändning. I de flesta av dessa exempel ska promptsträngen vara PS>. Den här uppmaningen är oberoende av os-specifika indikatorer.

Prompter krävs i exempel för att illustrera kommandon som ändrar prompten eller när sökvägen som visas är viktig för scenariot. I följande exempel illustreras hur frågeformuläret ändras när du använder registerprovidern.

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

Använd inte alias i exempel

Använd det fullständiga namnet på alla cmdletar och parametrar om du inte specifikt dokumenterar aliaset. Cmdlet- och parameternamn måste använda rätt Pascal-skiftlägesnamn .

Använda parametrar i exempel

Undvik att använda positionsparametrar. För att minska risken för förvirring bör du inkludera parameternamnet i ett exempel, även om parametern är positionell.

Formatering av cmdlet-referensartiklar

Cmdlet-referensartiklar har en specifik struktur. PlatyPS definierar den här strukturen. PlatyPS genererar cmdlet-hjälpen för PowerShell-moduler i Markdown. När du har redigerat Markdown-filerna kan PlatyPS skapa MAML-hjälpfilerna som används av cmdleten Get-Help .

PlatyPS har ett schema som förväntar sig en specifik struktur för cmdlet-referens. PlatyPS-schemadokumentet beskriver den här strukturen. Schemaöverträdelser orsakar byggfel som måste åtgärdas innan vi kan acceptera ditt bidrag.

  • Ta inte bort någon av ATX-huvudstrukturerna. PlatyPS förväntar sig en specifik uppsättning rubriker i en viss ordning.
  • Huvudena H2 INPUTS och OUTPUTS måste ha en H3-typ. Om cmdleten inte tar indata eller returnerar ett värde använder du värdet None för H3.
  • Infogade kodintervall kan användas i alla stycken.
  • Inhägnade kodblock tillåts endast i avsnittet EXEMPEL .

I PlatyPS-schemat är EXAMPLES en H2-rubrik. Varje exempel är en H3-rubrik. I ett exempel tillåter schemat inte att kodblock avgränsas med stycken. Schemat tillåter endast följande struktur:

### Example X - Title sentence

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

Numrera varje exempel och lägg till en kort rubrik.

Till exempel:

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

Formatera About_-dokument

About_* filer skrivs i Markdown men levereras som oformaterade textfiler. Vi använder Pandoc för att konvertera Markdown till oformaterad text. About_* filer är formaterade för bästa kompatibilitet i alla versioner av PowerShell och med publiceringsverktygen.

Grundläggande formateringsriktlinjer:

  • Begränsa styckerader till 80 tecken

  • Begränsa kodblock till 76 tecken

  • Begränsa citatblock och aviseringar till 78 tecken

  • När du använder dessa speciella metatecken \,$ och <:

    • I en rubrik måste dessa tecken undkommas med hjälp av ett inledande \-tecken eller omslutas av kodsegment med hjälp av backticks (`)

    • I ett stycke ska dessa tecken placeras i kodintervall. Till exempel:

      ### The purpose of the \$foo variable

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

  • Markdown-tabeller

    • För About_* artiklar måste tabeller rymmas inom 76 tecken
      • Om innehållet inte får plats inom 76 teckensgräns använder du punktlistor i stället
    • Använd inledande och avslutande | tecken på varje rad

Nästa steg

Redaktionell checklista

  • Last updated on