주석 기반 도움말의 예

2025-03-25

이 항목에는 스크립트 및 함수에 주석 기반 도움말을 사용하는 방법을 보여 주는 예제가 포함되어 있습니다.

예제 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
    #>
}

다음 출력은 Add-Extension 함수에 대한 도움말을 표시하는 Get-Help 명령의 결과를 보여 줍니다.

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에 대한 도움말 항목에서 도움말 함수를 설명하므로 도움말 함수는 .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-HelpGet-Help cmdlet에 대한 도움말 항목을 표시합니다.

PS> Get-Help help

NAME
    Get-Help

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