以批注為基礎的說明範例

本主題包含範例，示範如何使用腳本和函式的批注式說明。

範例 1：函式的批注型說明

下列範例函式包含以批注為基礎的說明。

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 can't pipe objects to Add-Extension.

        .OUTPUTS
        System.String. Add-Extension returns a string with the extension or file name.

        .EXAMPLE
        PS> Add-Extension -Name "File"
        File.txt

        .EXAMPLE
        PS> Add-Extension -Name "File" -Extension "doc"
        File.doc

        .EXAMPLE
        PS> Add-Extension "File" "doc"
        File.doc

        .LINK
        Online version: http://www.fabrikam.com/add-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 can't pipe objects to Add-Extension.

OUTPUTS
    System.String. Add-Extension returns a string with the extension or file name.

    -------------------------- EXAMPLE 1 --------------------------

    PS> Add-Extension -Name "File"
    File.txt

    -------------------------- EXAMPLE 2 --------------------------

    PS> Add-Extension -Name "File" -Extension "doc"
    File.doc

    -------------------------- EXAMPLE 3 --------------------------

    PS> Add-Extension "File" "doc"
    File.doc

RELATED LINKS
    Online version: http://www.fabrikam.com/add-extension.html
    Set-Item

範例 2：腳本的批注型說明

下列範例函式包含以批注為基礎的說明。

請注意結尾 #> 與 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 can't pipe objects to Update-Month.ps1.

  .OUTPUTS
  None. Update-Month.ps1 doesn't 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 can't pipe objects to Update-Month.ps1.

OUTPUTS
        None. Update-Month.ps1 doesn't 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 函式會使用 .FORWARDHELPTARGETNAME 和 .FORWARDHELPCATEGORY 關鍵詞，將使用者重新導向至 Get-Help Cmdlet 說明主題。

function help
{
    <#
      .FORWARDHELPTARGETNAME Get-Help
      .FORWARDHELPCATEGORY Cmdlet
    #>
    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
            [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
            [System.String]
            ${Name},
    ...
}

下列命令會使用這項功能。當使用者輸入 help 函式的 Get-Help 命令時，Get-Help 會顯示 Get-Help Cmdlet 的說明主題。

PS> Get-Help help

NAME
    Get-Help

SYNOPSIS
    Displays information about Windows PowerShell cmdlets and concepts.
...

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-04-10