本文提供 PowerShell-Docs 內容專屬的樣式指引。 它會以概 觀中所述的資訊為基礎。
格式化命令語法元素
在句子中使用 PowerShell 語言的元素時，請使用下列規則來進行格式化。
在適當的Pascal案例中，一律使用 Cmdlet 和參數的完整名稱
只有在您特別示範別名時，才使用別名
PowerShell 關鍵字和運算子應該全部小寫
下列項目應使用 粗體 文字來格式化：
類型名稱
類別名稱
屬性名稱
參數名稱
- 根據預設，請使用不含連字元前置詞的參數。
- 如果您要說明語法，請使用參數名稱搭配連字元。 將參數用反引號包圍。
例如：
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.
下列項目應使用反引號來格式化（
`）：屬性和參數值
使用括號樣式的類型名稱 ─ 例如：
[System.Io.FileInfo]以名稱引用角色。 例如：使用星號字元 （
*） 作為通配符。語言關鍵詞和運算符
Cmdlet、函式和腳本名稱
命令和參數別名
方法名稱 - 例如：
ToString()方法會傳回 物件的字串表示法變數
原生命令
檔案和目錄路徑
內嵌命令語法範例 - 如需 程式代碼範例，請參閱 Markdown
這個範例顯示一些倒數範例：
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 ```這個範例顯示命令語法內聯：
To start the spooler service on a remote computer named DC01, you type: `sc.exe \\DC01 start spooler`.包含擴展名可確保根據 PowerShell 的命令優先順序執行正確的命令。
程式碼的 Markdown 示例
Markdown 支援兩種不同的程式代碼樣式：
-
程式碼片段內嵌 - 以單個反引號
`字元標示。 在段落內使用，而不是做為獨立區塊。 -
程序代碼區塊 - 多行區塊，周圍有三個反引號 （
```） 字串。 程式碼區塊在反引號後面可以加上指定的程式語言標籤。 語言標籤會啟用程式代碼區塊內容的語法醒目提示。
所有程式代碼區塊都應該包含在程式代碼柵欄中。 請勿對程式代碼區塊使用縮排。 Markdown 允許此模式，但可能會有問題，而且應該避免。
程式碼區塊是一行或多行程式碼，由三個反引號（```）包圍形成的程式碼柵欄。
程式碼圍欄標記必須各自位於程式碼範例之前和之後的行中。 開頭標記可以有選擇性的語言標籤。 語言標籤可在轉譯的網頁上啟用語法醒目提示。
如需支援語言標籤的完整清單，請參閱集中式參與者指南中的 隔離程式代碼區塊 。
發佈也會新增 [ 複製 ] 按鈕，可將程式代碼區塊的內容複製到剪貼簿。 這可讓您將程式代碼貼到腳本中，以測試程式代碼範例。 不過，並非所有範例都打算按照原樣執行。 某些程式代碼區塊是PowerShell概念的基本圖例。
我們的檔案中使用三種類型的程式代碼區塊：
- 語法區塊
- 說明範例
- 可執行範例
語法程式代碼區塊
語法程式代碼區塊可用來描述命令的語法結構。 請勿在程式代碼柵欄上使用語言標記。 此範例說明 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>]
```
此範例以一般化的詞彙描述 for 語句。
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
說明範例
說明範例可用來說明PowerShell概念。 Yo'u 應該盡可能 避免在範例中使用 PowerShell 提示 。 不過，說明範例並非要複製並貼上以供執行。 它們最常用於容易了解的簡單範例。 您可以包含 PowerShell 提示符號和範例輸出。
以下是說明 PowerShell 比較運算子的簡單範例。 在此情況下，我們不希望讀取器複製並執行此範例。 請注意，此範例使用 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
```
可執行範例
要複製和執行的複雜範例，應該使用下列區塊樣式標記：
```powershell
<Your PowerShell code goes here>
```
PowerShell 命令所顯示的輸出應該包含在 輸出 程式代碼區塊中，以防止語法醒目提示。 例如：
```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
```
程式 Output 代碼標籤不是語法醒目提示系統所支援的官方 語言 。
不過，此標籤很有用，因為我們的發佈系統會將 [輸出 ] 標籤新增至網頁上的程式代碼框。 [輸出方塊] 沒有語法高亮顯示。
編碼樣式規則
避免程式代碼範例中的行接續
避免在PowerShell程式碼範例中使用行接續字元 （`）。 反引號字元很難看到，如果行尾有額外的空格，可能會導致問題。
- 使用 PowerShell Splatting 來減少具有數個參數之 Cmdlet 的行長度。
- 利用 PowerShell 的自然換行機會，例如管道 （
|） 字元之後、左大括弧 （{）、括弧 （(） 和括弧 （[）。
避免在範例中使用PowerShell提示
不建議使用提示字串，而且應該受限於說明命令行使用方式的案例。 對於大部分的範例，提示字串應該是 PS>。 此提示與OS特定指標無關。
範例中需要提示，以說明改變提示的命令，或當顯示的路徑對案例很重要時。 下列範例說明使用登錄提供者時提示如何變更。
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
請勿在範例中使用別名
除非您特別記載別名，否則請使用所有 Cmdlet 和參數的完整名稱。 Cmdlet 和參數名稱必須使用適當的 Pascal 式大小寫名稱。
在範例中使用參數
避免使用位置參數。 若要減少混淆的機會，您應該在範例中包含參數名稱，即使參數是位置。
格式化 Cmdlet 指令參考文章
Cmdlet 參考文章具有特定的結構。
PlatyPS 會定義這個結構。 PlatyPS 會在 Markdown 中產生 PowerShell 模組的 Cmdlet 說明。 編輯 Markdown 檔案之後，PlatyPS 可以建立 Cmdlet 所使用的 Get-Help MAML 說明檔。
PlatyPS 有一個架構，該架構要求 Cmdlet 參考具備特定的結構。 PlatyPS 架構檔 描述此結構。 架構違規會導致必須修正的組建錯誤，才能接受您的貢獻。
- 請勿移除任何 ATX 標頭結構。 PlatyPS 預期會以特定順序指定一組標頭。
- H2 INPUTS 和 OUTPUTS 標頭必須具有 H3 類型。 如果 Cmdlet 未接受輸入或傳回值，請使用 H3 的值
None。 - 內嵌程式碼可以用在任何段落中。
- 只有 EXAMPLES 區段中才允許隔離的程式代碼區塊。
在 PlatyPS 架構中， EXAMPLES 是 H2 標頭。 每個範例都是 H3 標題。 在範例中，架構不允許以段落分隔程式代碼區塊。 架構只允許下列結構：
### Example X - Title sentence
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.
為每個範例加上編號，並新增簡短標題。
例如：
### 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
```
About_檔案格式化
About_* 檔案是以 Markdown 撰寫，但會以純文本檔案的形式寄送。 我們使用 Pandoc 將 Markdown 轉換成純文字。
About_* 檔案會針對所有 PowerShell 版本和發行工具的最佳相容性格式化。
基本格式指導方針：
將段落行限制為80個字元
將程式代碼區塊限製為76個字元
將區塊和警示限制為78個字元
使用這些特殊元字元
\、$與<時：在標頭中，必須使用前置
\字元逸出這些字元，或使用反引號將字元括在程式代碼範圍中（`）在段落中，這些字元應該放入程式碼區塊中。 例如：
### The purpose of the \$foo variable The `$foo` variable is used to store ...
Markdown 數據表
- 針對
About_*文章，表格必須符合 76 個字元。- 如果內容不符合 76 個字元的限制，請改用項目符號清單
- 在每個行上使用開頭和結尾
|字元
- 針對
