資料結構
網路
關係型資料庫管理系統
作業系統
Java
MS Excel
iOS
HTML
CSS
Android
Python
C 程式設計
C++
C#
MongoDB
MySQL
Javascript
PHP
物理學
化學
生物學
數學
英語
經濟學
心理學
社會學
時尚研究
法律研究如何在 PowerShell 中編寫基於註釋的幫助？
在 PowerShell 中，當您建立複雜的指令碼或函式時，應該為終端使用者建立幫助，以便他們輕鬆理解您的指令碼功能。編寫基於註釋的幫助或基於 XML 的幫助，最終與 cmdlet 或函式的 **Get-Help** 語法類似，它是幫助的線上版本。
例如，只需開啟 PowerShell 控制檯並執行以下命令。
Get-Help Get-WmiObject
您可以在輸出中看到各種幫助部分，例如 **NAME、SYNOPSIS、SYNTAX、DESCRIPTION、PARAMETER、LINK**。這些稱為 **關鍵字**。我們可以手動將它們全部包含在指令碼或函式中以獲取幫助。每當我們使用幫助關鍵字時，都需要在它前面使用點 (.) 關鍵字。
當我們編寫基於註釋的幫助時，它應該位於多行註釋框 **<# .. #>** 內。您也可以使用單行註釋 #，但對於使用者來說，更容易閱讀和理解的是將它們放在多行註釋框內。
沒有必要用大寫字母使用語法，但為了使用者的可讀性和區分 **關鍵字**，我們將它們放入 **大寫** 字母中。
以下是基於命令的幫助的結構。
<# .HELP Keyword HELP content #>
讓我們逐一瞭解一些必要的關鍵字。
**.SYNOPSIS** - 函式或指令碼的簡要描述。此關鍵字只能在幫助部分中使用一次。
**.DESCRIPTION** - 函式或指令碼的詳細描述。此關鍵字只能在幫助部分中使用一次。
**.PARAMETER** - 用於引數的簡要描述。您需要為每個引數編寫一個新的引數關鍵字。首先，您需要編寫引數關鍵字並在引數名稱後加空格，並在下一行中編寫引數的內容。
**.Example** - 描述函式或指令碼的示例命令。您還可以包含示例輸出。可以使用每個新的 Example 關鍵字新增多個示例。
**.Notes** - 有關函式或指令碼的其他資訊。
**.Inputs** - 輸入物件的描述。
**.Outputs** - 輸出物件的描述。
上面包含的關鍵字是幫助使用者充分了解函式或指令碼相關幫助的常用關鍵字。您還可以包含許多其他關鍵字。要獲取有關關鍵字的更多資訊，請使用 **about_comment-based_help** 的幫助部分。
get-help about_comment-based_help
示例
function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status
.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green
.
#>
}當您檢查上述函式的幫助時，您將獲得以下輸出。
PS C:\WINDOWS\system32> Get-Help Get-ColoredService NAME Get-ColoredService SYNOPSIS Gets the colored output of the Services based on Status SYNTAX Get-ColoredService [] DESCRIPTION Get-ColoredService will provide the colorful output based on the status of the service. If the Service is in Stopped status - Output will be Red If the service is in Running status - Output will be in Green . RELATED LINKS REMARKS To see the examples, type: "get-help Get-ColoredService -examples". For more information, type: "get-help Get-ColoredService -detailed". For technical information, type: "get-help Get-ColoredService -full".
您可以看到一些幫助關鍵字 **(名稱、語法、描述、相關連結、備註)** 是預設的。
我們現在將使用其他關鍵字（如 **parameter、inputs、outputs、example** 等）建立幫助。在 **param** 塊中宣告為 **parameter** 的任何內容，都會顯示其語法，如下例所示。
function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status
.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green
.PARAMETER ServiceName
Specifies the path to the CSV-based input file.
.EXAMPLE
Get-ColoredService -ServiceName Spooler,WinRM
.EXAMPLE
Get-ColoredService -ServiceName *
.INPUTS
Input single or multiple services names
.OUTPUTS
Output of the services information in the table format
#>
[cmdletbinding()]
param(
[string[]]$ServiceName
)
}當您檢查上述函式的幫助時，您可以在語法中看到變數名稱。
PS C:\WINDOWS\system32> Get-Help Get-ColoredService -Full NAME Get-ColoredService SYNOPSIS Gets the colored output of the Services based on Status SYNTAX Get-ColoredService [[-ServiceName] <String[]>] [<CommonParameters>] DESCRIPTION Get-ColoredService will provide the colorful output based on the status of the service. If the Service is in Stopped status - Output will be Red If the service is in Running status - Output will be in Green PARAMETERS -ServiceName <String[]> Specifies the path to the CSV-based input file. Required? false Position? 1 Default value Accept pipeline input? false Accept wildcard characters? false <CommonParameters> This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). INPUTS Input single or multiple services name OUTPUTS Output of the services information in the table format -------------------------- EXAMPLE 1 -------------------------- PS C:\>Get-ColoredService -ServiceName Spooler,WinRM -------------------------- EXAMPLE 2 -------------------------- PS C:\>Get-ColoredService -ServiceName * RELATED LINKS
469 次檢視
