註解型說明的範例
本主題包含範例，示範如何針對腳本和函式使用以批註為基礎的說明。
範例1：函數的 Comment-Based 說明
下列範例函數包含以批註為基礎的說明。
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
PS> extension -name "File"
File.txt
.EXAMPLE
PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
PS> extension "File" "doc"
File.doc
.LINK
Online version: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
下列輸出會顯示命令的結果 Get-Help ，此命令會顯示函式的說明 Add-Extension 。
PS> Get-Help Add-Extension -full
NAME
Add-Extension
SYNOPSIS
Adds a file name extension to a supplied name.
SYNTAX
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
PARAMETERS
-Name
Specifies the file name.
Required? false
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-Extension
Specifies the extension. "Txt" is the default.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".
INPUTS
None. You cannot pipe objects to Add-Extension.
OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
-------------------------- EXAMPLE 1 --------------------------
PS> extension -name "File"
File.txt
-------------------------- EXAMPLE 2 --------------------------
PS> extension -name "File" -extension "doc"
File.doc
-------------------------- EXAMPLE 3 --------------------------
PS> extension "File" "doc"
File.doc
RELATED LINKS
Online version: http://www.fabrikam.com/extension.html
Set-Item
範例2：腳本的 Comment-Based 說明
下列範例函數包含以批註為基礎的說明。
請注意結尾和語句之間的空白行 #> Param 。 在沒有語句的腳本中，[ Param 說明] 主題和第一個函式宣告中的最後一個批註之間必須至少有兩個空白行。 如果沒有這些空白行，請 Get-Help 將說明主題與函式相關聯，而不是腳本。
<#
.SYNOPSIS
Performs monthly data updates.
.DESCRIPTION
The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.
.PARAMETER InputPath
Specifies the path to the CSV-based input file.
.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.EXAMPLE
PS> .\Update-Month.ps1
.EXAMPLE
PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
下列命令會取得腳本說明。 因為腳本不在 Path 環境變數中所列的目錄中，所以 Get-Help 取得腳本說明的命令必須指定腳本路徑。
PS> Get-Help c:\ps-test\update-month.ps1 -full
NAME
C:\ps-test\Update-Month.ps1
SYNOPSIS
Performs monthly data updates.
SYNTAX
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]
DESCRIPTION
The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.
PARAMETERS
-InputPath
Specifies the path to the CSV-based input file.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
None. You cannot pipe objects to Update-Month.ps1.
OUTPUTS
None. Update-Month.ps1 does not generate any output.
-------------------------- EXAMPLE 1 --------------------------
PS> .\Update-Month.ps1
-------------------------- EXAMPLE 2 --------------------------
PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- EXAMPLE 3 --------------------------
PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
RELATED LINKS
範例3： Param 語句中的參數描述
這個範例示範如何在函數或腳本的語句中插入參數描述 Param 。 當參數描述很簡單時，此格式最有用。
function Add-Extension
{
param
(
[string]
# Specifies the file name.
$name,
[string]
# Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
...
#>
結果與範例1的結果相同。 Get-Help 將參數描述視為伴隨關鍵字來解讀 .Parameter 。
範例4：重新導向至 XML 檔案
您可以撰寫函數和腳本的 XML 型說明主題。 雖然以批註為基礎的說明比較容易執行，但如果您想要更精確地控制說明內容，或將說明主題翻譯成多種語言，則需要以 XML 為基礎的協助。下列範例會顯示腳本的前幾行 Update-Month.ps1 。 腳本會使用 .ExternalHelp 關鍵字來指定腳本的 XML 型說明主題的路徑。
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
下列範例示範如何在函式 .ExternalHelp 中使用關鍵字。
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
範例5：重新導向至不同的說明主題
下列程式碼是 PowerShell 中內建函數開頭的摘要 Help ，它會一次顯示一屏解說文字。 由於 Get-Help Cmdlet 的說明主題會描述 Help 函式，因此 Help 函式會使用 .ForwardHelpTargetName 和 .ForwardHelpCategory 關鍵字將使用者重新導向至 Get-Help Cmdlet 說明主題。
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...
下列命令會使用這項功能。 當使用者輸入函式的 Get-Help 命令時 Help ，會 Get-Help 顯示 Cmdlet 的說明主題 Get-Help 。
PS> get-help help
NAME
Get-Help
SYNOPSIS
Displays information about Windows PowerShell cmdlets and concepts.
...
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應