Stilguide för PowerShell-Docs
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 Översikt.
Produktterminologi
Det finns flera varianter av PowerShell.
PowerShell – Det här är standardinställningen. Vi anser att PowerShell 7 och mer är det enda, sanna PowerShell.
PowerShell Core – PowerShell som bygger på .NET Core. Användningen av termen Core bör begränsas till fall där det är nödvändigt att skilja den från Windows PowerShell.
Windows PowerShell – PowerShell bygger på .NET Framework. Windows PowerShell levereras endast på Windows och kräver det fullständiga ramverket.
I allmänhet kan referenser till "Windows PowerShell" i dokumentationen ändras till PowerShell. "Windows PowerShell" ska användas när Windows PowerShell-specifikt beteende diskuteras.
Relaterade produkter
- Visual Studio Code (VS Code) – Det här är Microsofts kostnadsfria redigerare med öppen källkod. Vid första omnämnande bör det fullständiga namnet användas. Därefter kan du använda VS Code. Använd inte "VSCode".
- PowerShell-tillägg för Visual Studio Code – Tillägget omvandlar VS Code till önskad IDE för PowerShell. Vid första omnämnande bör det fullständiga namnet användas. Därefter kan du använda PowerShell-tillägget.
- Azure PowerShell – Det här är en samling PowerShell-moduler som används för att hantera Azure-tjänster.
- Azure Stack PowerShell – Det här är en samling PowerShell-moduler som används för att hantera Microsofts hybridmolnlösning.
Markdown-information
Microsoft Open Publishing System (OPS) som skapar vår dokumentation använder markdig för att bearbeta Markdown-dokumenten. Markdig parsar dokumenten baserat på reglerna för den senaste CommonMark-specifikationen.
Den nya CommonMark-specifikationen är mycket striktare när det gäller konstruktion av vissa Markdown-element. Var noga med informationen i det här dokumentet.
Tomma rader, blanksteg och tabbar
Tomma rader indikerar också slutet av ett block i Markdown. Det måste finnas ett tomt värde mellan Markdown-block av olika typer (till exempel mellan ett stycke och en lista eller rubrik).
Flera på varandra följande tomma rader återges som en enda tom rad i HTML. De har inget syfte. I ett kodblock bryter på varandra följande tomma rader kodblocket.
Ta bort extra blanksteg i slutet av rader.
Anteckning
Avståndet har betydelse i Markdown. Använd alltid blanksteg i stället för hårda tabbar. Avslutande blanksteg kan ändra hur Markdown återges.
Rubriker
Använd bara ATX-rubriker (# style, i stället för = eller - stilrubriker).
- Använd bara inledande versal i meningar, och den första bokstaven i en rubrik skrivas med versal
- Det måste finnas ett blanksteg mellan
#och den första bokstaven i rubriken - Rubriker ska omges av en enda tom rad
- Endast en H1 per dokument
- Rubriknivåerna bör ökas med ett. Hoppa inte över nivåer
- Använd inte fetstil eller andra markeringar i rubriker
Begränsa radlängden till 100 tecken
Detta gäller för konceptuella artiklar och cmdlet-referenser. Begränsning av radlängden förbättrar läsbarheten för git-differenser och historik. Det gör det också enklare för andra skrivare att bidra.
Använd markdown-tillägget Reflow i Visual Studio Code för att enkelt flödesomforma stycken så att de passar den angivna radlängden.
About_topics är begränsade till 80 tecken. Mer specifik information finns i Formatering About_ filer.
Listor
Om listan innehåller flera meningar eller stycken bör du överväga att använda ett undernivåhuvud i stället för en lista.
Listan ska omges av en enda tom rad.
Osorterade listor
Avsluta inte listobjekt med en punkt om de inte innehåller flera meningar. Använd bindestreck (-) som punkter för listobjekt. På så sätt undviker du sammanblandning med markeringen för fetstil eller kursiv stil, som använder asterisk [*]. Om du vill lägga till ett stycke eller andra element under ett objekt i en punktlista infogar du en radbrytning och justerar indraget efter det första tecknet efter punkten.
Exempel:
This is a list that contain child elements under a bullet item.
- First bullet item
Sentence explaining the first bullet.
- Child bullet item
Sentence explaining the child bullet.
- Second bullet item
- Third bullet item
Det här är en lista som innehåller underordnade element under ett punktobjekt.
Första objektet i punktlistan
Mening som beskriver den första punkten.
Underobjekt i punktlista
Mening som förklarar den underordnade punkten.
Andra objektet i punktlistan
Tredje objektet i punktlistan
Sorterade listor
Om du vill lägga till ett stycke eller andra element under ett numrerat objekt, justerar du indraget efter det första tecknet som följer efter objektets nummer. Alla objekt i en numrerad lista bör använda talet i 1. stället för att öka varje objekt. Med Markdown-rendering ökar värdet automatiskt. Det här gör det enklare att ändra ordning på objekt och standardiserar indrag för underordnat innehåll.
Exempel:
1. For the first element, insert a single space after the 1. Long sentences should be
wrapped to the next line and must line up with the first character after the numbered
list marker.
To include a second element (like this one), insert a line break after the first
and align indentations. The indentation of the second element must line up with
the first character after the numbered list marker. For single digit items, like
this one, you indent to column 4. For double digits items, for example item number
10, you indent to column 5.
1. The next numbered item starts here.
Markdown-resultatet renderas på följande sätt:
För det första elementet infogar du ett blanksteg efter siffran 1. Långa meningar ska omslutas till nästa rad, och måste anpassas efter det första tecknet efter markören för den numrerade listan.
Vill du lägga till ett andra element (som det här) infogar du en radbrytning efter det första och justerar indragen. Indraget för det andra elementet måste anpassas efter det första tecknet efter markören för den numrerade listan. För ensiffriga objekt, som det här, gör du indrag till kolumn 4. För tvåsiffriga objekt, till exempel objekt nummer 10, gör du indrag till kolumn 5.
Nästa numrerade objekt börjar här.
Avbildningar
Syntax för att infoga en bild:
![[alt text]](<folderPath>)
Example:
alt text är en kort beskrivning av bilden och <folder path> är en relativ sökväg till bilden. Alternativ text krävs för skärmläsare för personer med nedsatt syn.
Bilder ska lagras i en media/<article-name> mapp i mappen som innehåller artikeln.
Dela inte bilder mellan artiklar. Skapa en mapp som matchar filnamnet för din artikel under mappen media. Kopiera bilderna till artikeln till den nya mappen. Om en bild används av flera artiklar måste varje bildmapp innehålla en kopia av bildfilen. Den här metoden förhindrar att en ändring av en bild i en artikel påverkar en annan artikel.
Följande bildfiltyper stöds: *.png , , , *.gif *.jpeg *.jpg , *.svg
Markdown-tillägg stöds av Open Publishing
I Microsoft Docs Authoring Pack finns verktyg som stöder funktioner som är unika för vårt publiceringssystem. Aviseringar är ett Markdown-tillägg för att skapa blockciter som återges på docs.microsoft.com med färger och ikoner som visar innehållets betydelse. Följande aviseringstyper stöds:
> [!NOTE]
> Information the user should notice even if skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Essential information required for user success.
> [!CAUTION]
> Negative potential consequences of an action.
> [!WARNING]
> Dangerous certain consequences of an action.
Dessa aviseringar ser ut så här på docs.microsoft.com:
Anteckningsblock
Anteckning
Information som användaren ska kunna se även vid snabbläsning.
Tipsblock
Tips
Valfri information som hjälper användaren.
Viktigt block
Viktigt
Viktig information som användaren behöver.
Varningsblock
Varning
Potentiella negativa konsekvenser av en åtgärd.
Varningsblock
Varning
Farliga konsekvenser av en åtgärd.
Hyperlänkar
Hyperlänkar måste använda Markdown-syntax
[friendlyname](url-or-path). Länkreferenser stöds.Publiceringssystemet stöder tre typer av länkar:
- URL-länkar
- Fillänkar
- Korsreferenslänkar
Länkar till andra artiklar om docs.microsoft.com måste vara plats relativa sökvägar
Alla webbadresser till externa webbplatser bör använda HTTPS om inte detta inte är giltigt för målplatsen.
Länkar måste ha ett eget namn, vanligtvis rubriken på den länkade artikeln
Alla objekt i avsnittet Relaterade länkar längst ned ska vara hyperlänkade
Använd inte bakåttecken, fetstil eller andra markeringar inom hakparenteserna för en hyperlänk.
Bare URL:er kan användas när du dokumenterar en specifik URI. URI:en måste omges av backticks. Exempel:
By default, if you don't specify this parameter, the DMTF standard resource URI `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
Länka till annat innehåll på docs.microsoft.com
URL-länkar till andra artiklar docs.microsoft.com måste vara plats relativa sökvägar. Det enklaste sättet att skapa en relativ länk är att kopiera URL:en från webbläsaren och sedan ta bort från
https://docs.microsoft.com/en-usdet värde som du klistrar in i markdown. Inkludera inte språk i URL:er i Microsoft-egenskaper (ta bort/en-usfrån URL). Ta bort alla onödiga frågeparametrar från URL:en. Exempel som bör tas bort:?view=powershell-5.1– används för att länka till en specifik version av PowerShell?redirectedfrom=MSDN– läggs till i URL:en när du omdirigeras från en gammal artikel till den nya platsen
Om du behöver länka till en specifik version av ett dokument måste du lägga till
&preserve-view=trueparametern i frågesträngen. Exempelvis:?view=powershell-5.1&preserve-view=trueEn fillänk används för att länka från en referensartikel till en annan, eller från en konceptuell artikel till en annan. Om du behöver länka till en referensartikel för en specifik version av PowerShell måste du använda en URL-länk.
- Fillänkar innehåller en relativ filsökväg (till exempel:
../folder/file.md) - Alla sökvägar använder snedstreck (
/) tecken
- Fillänkar innehåller en relativ filsökväg (till exempel:
Korsreferenslänkar är en särskild funktion som stöds av publiceringssystemet. Du kan använda korsreferenslänkar i konceptuella artiklar för att länka till .NET API eller cmdlet-referens.
Länkar till .NET API-referens finns i Använda länkar i dokumentationen i den centrala deltagarguiden.
Länkar till cmdlet-referenser har följande format:
xref:<module-name>.<cmdlet-name>. Till exempel för att länka tillGet-Contentcmdleten i modulen Microsoft.PowerShell.Management.[Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)
Djuplänkning tillåts på både URL- och fillänkar. Lägg till fästpunkten i slutet av målsökvägen. Exempel:
[about_Splatting](about_Splatting.md#splatting-with-arrays)[custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)
Mer information finns i Använda länkar i dokumentationen.
Formatera element i kommandosyntax
Använd alltid det fullständiga namnet för cmdlets och parametrar. Undvik att använda alias om du inte specifikt demonstrerar aliaset.
Egenskap, parameter, objekt, typnamn, klassnamn, klassmetoder ska vara fetstilt.
- Egenskaps- och parametervärden ska omslutas i backticks (
`). - När du refererar till typer med hakparentesformatet använder du backticks. Exempelvis:
[System.Io.FileInfo]
- Egenskaps- och parametervärden ska omslutas i backticks (
Språknyckelord, cmdlet-namn, funktioner, variabler, interna EXE:er, filsökvägar och infogade syntaxexempel ska vara omslutna med bakåtklick (
`) tecken.Exempel:
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 ```PowerShell-nyckelord och operatorer ska endast vara gemener
Använd rätt (Pascal) hölje för cmdlet-namn och parametrar
När du refererar till en parameter med namnet ska det skrivas med fetstil. När du illustrerar användningen av en parameter med avstavningsprefixet ska parametern omslutas av grava accenter. Exempel:
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.När du visar exempel på användning av ett externt kommando ska exemplet omslutas av grava accenter. Inkludera alltid filnamnstillägget i det interna kommandot. Exempel:
To start the spooler service on a remote computer named DC01, you type `sc.exe \\DC01 start spooler`.Genom att inkludera filnamnstillägget säkerställer du att rätt kommando körs enligt PowerShell-kommandots prioritet.
När du skriver en konceptuell artikel (till skillnad från referensinnehåll) ska den första förekomsten av ett cmdlet-namn hyperlänkas till cmdlet-dokumentationen. Använd inte bakåttecken, fetstil eller andra markeringar inom hakparenteserna för en hyperlänk.
Exempel:
This [Write-Host](/powershell/module/Microsoft.PowerShell.Utility/Write-Host) cmdlet uses the **Object** parameter to ...Mer information finns i hyperlänkavsnittet i den här artikeln.
Markdown för kodexempel
Markdown stöder två olika kodformat:
- Kodintervall (infogade) – markerade med ett enda bakåtklickstecken (
`). Används i ett stycke i stället för som ett fristående block. - Kodblock – ett block med flera linjer som omges av strängar med tredubbel bakåtklick (
```). Kodblock kan också ha en språketikett som följer backticks. Språketiketten möjliggör syntaxmarkering för innehållet i kodblocket.
Alla kodblock ska finnas i en kodavgränsning. 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 en tredubbelklick ( ``` ) kodstängsel.
Kodavgränsningsmarkörerna måste finnas på en egen rad före och efter kodexemplet. Markören i början av kodblocket kan ha en valfri språketikett. Microsofts Open Publishing System (OPS) använder språketiketten för att stödja markeringsfunktionen för syntax.
En fullständig lista över språktaggar som stöds finns i Inhäglade kodblock i den centraliserade deltagarguiden.
OPS lägger också till knappen Kopiera, som kopierar innehållet i kodblocket till Urklipp. På så sätt kan du snabbt klistra in koden i ett skript för att testa kodexe exemplet. Alla exempel i vår dokumentation är dock inte avsedda att köras som de är. Vissa kodblock är enkla illustrationer av ett PowerShell-begrepp.
Det finns tre typer av kodblock som används i vår dokumentation:
- Syntaxblock
- Illustrerande exempel
- 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å kodstängslet. 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 satsen for i generaliserade villkor:
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
Illustrerande exempel
Illustrerande exempel används för att förklara ett PowerShell-begrepp. De är inte avsedda att kopieras till Urklipp för körning. De används oftast för enkla exempel som är enkla att skriva och lätta att förstå. Kodblocket kan innehålla PowerShell-prompten och exempelutdata.
Här är ett enkelt exempel som illustrerar PowerShell-jämförelseoperatorer. I det här fallet förväntar vi oss inte att läsaren ska kopiera och köra exemplet.
```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 blockformat:
```powershell
<Your PowerShell code goes here>
```
De utdata som visas av PowerShell-kommandon måste anges i ett kodblock för utdata för att förhindra markering av syntax. 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
```
Etiketten Utdatakod är inte ett officiellt "språk" som stöds av syntaxmarkeringssystemet. Den här etiketten är dock användbar eftersom OPS lägger till etiketten "Utdata" i kodrutans ram på webbsidan. Kodrutan "Utdata" har ingen syntaxmarkering.
Regler för kodningsformat
Undvik radfortsättning i kodexempel
Undvik att använda radfortsättningstecken (`) i PowerShell-kodexempel. De är svåra att se och kan orsaka problem om det finns extra blanksteg i slutet av raden.
- Använd PowerShell-splatting för att minska radlängden för cmdlets som har flera parametrar.
- Dra nytta av PowerShells naturliga radbrytningsmöjligheter, som efter pipe ( ) tecken, 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 användningen av kommandoraden. I de flesta av de här exemplen ska promptsträngen vara PS> . Den här frågan är oberoende av OS-/regionsspecifika 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 visas hur frågan ä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 cmdlets och parametrar om du inte specifikt dokumenterar aliaset. Cmdlet- och parameternamn måste använda rätt Pascal-cased-namn.
Använda parametrar i exempel
Undvik att använda positionsparametrar. I allmänhet bör du alltid inkludera parameternamnet i ett exempel, även om parametern är positionell. På så sätt minskar du risken för förvirring i exemplen.
Formatera cmdlet-referensartiklar
Artiklar med cmdlet-referenser har en speciell struktur. Strukturen definieras av PlatyPS. PlatyPS genererar cmdlet-hjälpen för PowerShell-moduler i Markdown. När du har redigerat Markdown-filerna används PlatyPS för att skapa MAML-hjälpfiler som används av cmdleten Get-Help.
PlatyPS har ett hårdkodat schema för cmdlet-referenser som skrivs in i koden. Dokumentet platyPS.schema.md är ett försök att beskriva strukturen. Schemaöverträdelser orsakar build-fel som måste åtgärdas innan vi kan acceptera ditt bidrag.
- Ta inte bort någon av ATX-rubrikstrukturerna. PlatyPS förväntar sig en specifik uppsättning rubriker.
- Rubrikerna Indatatyp och Utdatatyp måste ha en typ. Om cmdleten inte tar indata eller returnerar ett värde använder du värdet
None. - Infogade kodomfång kan användas i alla stycken.
- Inhägna 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 inte schemat att kodblock avgränsas med stycken. Schemat tillåter 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.
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_-filer
About_* -filer skrivs i Markdown men levereras som oformaterad textfil. Vi använder Pandoc för att konvertera Markdown till oformaterad text. About_* -filerna är formaterade för bästa kompatibilitet i alla versioner av PowerShell och med publiceringsverktygen.
Riktlinjer för grundläggande formatering:
Begränsa normala rader till 80 tecken
Kodblock är begränsade till 76 tecken
Blockcittar (och aviseringar) är begränsade till 78 tecken
När du använder dessa särskilda metatecken
\$, och<:Inom en rubrik måste dessa tecken vara rymna med hjälp av ett inledande tecken eller omges av
\kodintervall med hjälp av backticks (`)Inom ett stycke ska dessa tecken anges i kodintervall. Exempel:
### The purpose of the \$foo variable The `$foo` variable is used to store ...
Tabeller måste få plats inom 76 tecken
Radbryt innehållet i celler manuellt över flera rader
Använd inledande och avslutande
|-tecken på varje radI följande exempel visas hur du skapar en tabell som innehåller information som radbryts på flera rader i en cell.
``` |Operator|Description |Example | |--------|---------------------------|---------------------------------| |`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | | |is an instance of the |`True` | | |specified .NET type. | | |`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | | |not an instance of the |`False` | | |specified.NET type. | | |`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | | |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| ```Anteckning
Begränsningen på 76 kolumner gäller endast
About_*för ämnen. Du kan använda breda kolumner i konceptuella referensartiklar eller cmdlet-referensartiklar.
Nästa steg
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för