댓글_기반_도움말_정보

간단한 설명

함수 및 스크립트에 대한 주석 기반 도움말 콘텐츠를 작성하는 방법을 설명합니다.

긴 설명

특수 도움말 주석 키워드를 사용하여 함수 및 스크립트에 대한 주석 기반 도움말 콘텐츠를 작성할 수 있습니다.

Get-Help cmdlet은 XML 파일에서 생성된 cmdlet 도움말 콘텐츠를 표시하는 것과 동일한 형식으로 주석 기반 도움말을 표시합니다. 사용자는 Get-Help, 전체, 예제및 Online같은 모든 매개 변수를 사용하여 주석 기반 도움말의 내용을 표시할 수 있습니다.

함수 및 스크립트에 대한 XML 기반 도움말 파일을 작성할 수도 있습니다. Get-Help cmdlet이 함수 또는 스크립트에 대한 XML 기반 도움말 파일을 찾을 수 있도록 하려면 .EXTERNALHELP 키워드를 사용합니다. 이 키워드가 없으면 Get-Help 함수 또는 스크립트에 대한 XML 기반 도움말 콘텐츠를 찾을 수 없습니다.

이 항목에서는 함수 및 스크립트에 대한 도움말 콘텐츠를 작성하는 방법을 설명합니다. 함수 및 스크립트에 대한 도움말 콘텐츠를 표시하는 방법에 대한 자세한 내용은 Get-Help참조하세요.

Update-Help 및 Save-Help cmdlet은 XML 파일에서만 작동합니다. 업데이트 가능한 도움말은 주석 기반 도움말 콘텐츠를 지원하지 않습니다.

주석 기반 도움말 구문

메모 기반 도움말 콘텐츠를 만들려면 주석 스타일(한 줄 메모 또는 메모 차단)을 사용할 수 있습니다.

주석 기반 도움말의 구문은 다음과 같습니다.

# .<help keyword>
# <help content>

또는

<#
    .<help keyword>
    <help content>
#>

주석 기반 도움말은 일련의 주석으로 작성됩니다. 주석의 각 줄 앞에 # 주석 기호를 입력하거나 <# 및 #> 기호를 사용하여 주석 블록을 만들 수 있습니다. 주석 블록 내의 모든 줄은 주석으로 해석됩니다.

주석 기반 도움말 항목의 모든 줄은 연속되어야 합니다. 메모 기반 도움말 항목이 도움말 항목의 일부가 아닌 주석을 따르는 경우 마지막 비 도움말 메모 줄과 주석 기반 도움말의 시작 사이에 빈 줄이 하나 이상 있어야 합니다.

키워드는 주석 기반 도움말의 각 섹션을 정의합니다. 각 주석 기반 도움말 키워드 앞에는 점 .가 있습니다. 키워드는 순서에 따라 표시할 수 있습니다. 키워드 이름은 대/소문자를 구분하지 않습니다.

예를 들어 .DESCRIPTION 키워드는 함수 또는 스크립트에 대한 설명 앞에 섰습니다.

<#
.DESCRIPTION
Get-Function displays the name and syntax of all functions in the session.
#>

주석 블록에는 하나 이상의 키워드가 포함되어야 합니다. .EXAMPLE같은 일부 키워드는 동일한 주석 블록에 여러 번 나타날 수 있습니다. 각 키워드에 대한 도움말 콘텐츠는 키워드 뒤의 줄에서 시작되며 여러 줄에 걸쳐 있습니다.

함수의 주석 기반 도움말 구문

함수에 대한 주석 기반 도움말은 다음 세 위치 중 하나에 나타날 수 있습니다.

• 함수 본문의 시작 부분에 있습니다.
• 함수 본문의 끝 부분에 있습니다.
• function 키워드 앞에 있습니다. 함수 도움말의 마지막 줄과 function 키워드 사이에는 둘 이상의 빈 줄이 있을 수 없습니다.

예를 들어:

function Get-Function {
    <#
        .<help keyword>
        <help content>
    #>

    # function logic
}

또는

function Get-Function {
    # function logic

    <#
        .<help keyword>
        <help content>
    #>
}

또는

<#
    .<help keyword>
    <help content>
#>
function Get-Function { }

스크립트의 주석 기반 도움말 구문

스크립트에 대한 주석 기반 도움말은 스크립트의 다음 두 위치 중 하나에 나타날 수 있습니다.

• 스크립트 파일의 시작 부분에 있습니다. 스크립트 도움말은 주석과 빈 줄만 스크립트에서 선행할 수 있습니다.

  스크립트 본문의 첫 번째 항목(도움말 뒤)이 함수 선언인 경우 스크립트 도움말의 끝과 함수 선언 사이에 두 개 이상의 빈 줄이 있어야 합니다. 그렇지 않으면 도움말이 스크립트에 대한 도움말이 아니라 함수에 대한 도움말로 해석됩니다.

• 스크립트 파일의 끝에 있습니다. 그러나 스크립트가 서명된 경우 스크립트 파일의 시작 부분에 주석 기반 도움말을 배치합니다. 스크립트의 끝은 서명 블록이 차지하고 있습니다.

예를 들어:

<#
.<help keyword>
<help content>
#>
function Get-Function { }

또는

function Get-Function { }
<#
.<help keyword>
<help content>
#>

주석 기반 도움말 키워드

다음은 유효한 주석 기반 도움말 키워드입니다. 이러한 키워드는 주석 기반 도움말에서 순서대로 표시할 수 있으며 대/소문자를 구분하지 않습니다. 키워드는 일반적으로 도움말 항목에 표시되는 순서대로 이 문서에 나열됩니다.

.SYNOPSIS

함수 또는 스크립트에 대한 간략한 설명입니다. 이 키워드는 각 항목에서 한 번만 사용할 수 있습니다.

.DESCRIPTION

함수 또는 스크립트에 대한 자세한 설명입니다. 이 키워드는 각 항목에서 한 번만 사용할 수 있습니다.

.PARAMETER

매개 변수에 대한 설명입니다. 함수 또는 스크립트 구문의 각 매개 변수에 대한 .PARAMETER 키워드를 추가합니다.

.PARAMETER 키워드와 동일한 줄에 매개 변수 이름을 입력합니다. .PARAMETER 키워드 다음 줄에 매개 변수 설명을 입력합니다. Windows PowerShell은 .PARAMETER 줄과 다음 키워드 또는 주석 블록 끝 사이의 모든 텍스트를 매개 변수 설명의 일부로 해석합니다. 설명에는 단락 나누기를 포함할 수 있습니다.

.PARAMETER  <Parameter-Name>

매개 변수 키워드는 주석 블록에서 순서에 관계없이 나타날 수 있지만 함수 또는 스크립트 구문은 도움말 항목에 매개 변수(및 해당 설명)가 표시되는 순서를 결정합니다. 순서를 변경하려면 구문을 변경합니다.

매개 변수 변수 이름 바로 앞에 함수 또는 스크립트 구문에 주석을 배치하여 매개 변수 설명을 지정할 수도 있습니다. 이렇게 하려면 하나 이상의 키워드가 있는 주석 블록도 있어야 합니다.

구문 주석과 .PARAMETER 키워드를 모두 사용하는 경우 .PARAMETER 키워드와 관련된 설명이 사용되며 구문 주석은 무시됩니다.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .PARAMETER
        [string]$ComputerName
    )
    # Verb the Noun on the computer
}

.EXAMPLE

함수 또는 스크립트를 사용하는 샘플 명령이며, 필요에 따라 샘플 출력 및 설명이 뒤따릅니다. 각 예제에 대해 이 키워드를 반복합니다.

.INPUTS

함수 또는 스크립트에 파이프할 수 있는 개체의 .NET 형식입니다. 입력 개체에 대한 설명을 포함할 수도 있습니다. 각 입력 형식에 대해 이 키워드를 반복합니다.

.OUTPUTS

cmdlet이 반환하는 개체의 .NET 형식입니다. 반환된 개체에 대한 설명을 포함할 수도 있습니다. 각 출력 형식에 대해 이 키워드를 반복합니다.

.NOTES

함수 또는 스크립트에 대한 추가 정보입니다.

.LINK

관련 항목의 이름입니다. 각 관련 항목에 대해 이 키워드를 반복합니다. 이 콘텐츠는 도움말 항목의 관련 링크 섹션에 표시됩니다.

.LINK 키워드 콘텐츠에는 동일한 도움말 항목의 온라인 버전에 대한 URI(Uniform Resource Identifier)도 포함될 수 있습니다. 매개 변수 Get-Help 을 사용할 때 온라인 버전이 열립니다. URI는 다음으로 httphttps시작해야 합니다.

.COMPONENT

함수 또는 스크립트가 사용하거나 관련된 기술 또는 기능의 이름입니다. 에 의해 반환된 검색 결과를 필터링하기 위해 Get-Help의 Get-Help 매개 변수는 이 값을 사용합니다.

.ROLE

도움말 항목의 사용자 역할 이름입니다. 의 Get-Help 매개 변수는 이 값을 사용하여 Get-Help에 의해 반환된 검색 결과를 필터링합니다.

.FUNCTIONALITY

함수의 의도된 사용을 설명하는 키워드입니다. 의 Get-Help 매개변수는 이 값을 사용함으로써 Get-Help에서 반환된 검색 결과를 필터링할 수 있습니다.

.FORWARDHELPTARGETNAME <Command-Name>

지정된 명령에 대한 도움말 항목으로 리디렉션됩니다. 함수, 스크립트, cmdlet 또는 공급자에 대한 도움말 콘텐츠를 비롯한 모든 도움말 항목으로 사용자를 리디렉션할 수 있습니다.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

.FORWARDHELPTARGETNAME항목의 도움말 범주를 지정합니다. 유효한 값은 Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter또는 All. 이름이 같은 명령이 있는 경우 충돌을 방지하려면 이 키워드를 사용합니다.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE <PSSession-variable>

도움말 항목이 포함된 세션을 지정합니다. PSSession 개체가 포함된 변수를 입력합니다. 이 키워드는 Export-PSSession cmdlet에서 내보내는 명령에 대한 도움말 콘텐츠를 찾는 데 사용됩니다.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

스크립트 또는 함수에 대한 XML 기반 도움말 파일을 지정합니다.

# .EXTERNALHELP <XML Help File>

함수 또는 스크립트가 XML 파일에 문서화될 때는 .EXTERNALHELP 키워드가 필요합니다. 이 키워드가 없으면 Get-Help 함수 또는 스크립트에 대한 XML 기반 도움말 파일을 찾을 수 없습니다.

.EXTERNALHELP 키워드는 다른 주석 기반 도움말 키워드보다 우선합니다. .EXTERNALHELP 있는 경우 Get-Help.EXTERNALHELP 키워드의 값과 일치하는 도움말 항목을 찾을 수 없더라도 주석 기반 도움말을 표시하지 않습니다.

모듈에서 함수를 내보내는 경우 경로가 없는 파일 이름으로 .EXTERNALHELP 키워드의 값을 설정합니다. Get-Help 는 모듈 디렉터리의 언어별 하위 디렉터리에서 지정된 파일 이름을 찾습니다. 함수에 대한 XML 기반 도움말 파일의 이름에 대한 요구 사항은 없습니다. PowerShell 5.0부터 모듈에서 내보낸 함수는 모듈에 이름이 지정된 도움말 파일에 문서화할 수 있습니다. 주석 키워드를 사용할 .EXTERNALHELP 필요가 없습니다. 예를 들어 모듈에서 Test-Function 함수를 내보낸 MyModule 경우 도움말 파일 MyModule-help.xml의 이름을 지정할 수 있습니다. cmdlet은 Get-Help 모듈 디렉터리의 파일에서 함수에 Test-Function 대한 MyModule-help.xml 도움말을 찾습니다.

함수가 모듈에 포함되지 않은 경우 XML 기반 도움말 파일의 경로를 포함합니다. 값에 경로가 포함되고 경로에 UI 문화권별 하위 디렉터리가 포함된 경우 Get-Help 모듈 디렉터리에서와 마찬가지로 Windows에 설정된 언어 대체 표준에 따라 스크립트 또는 함수의 이름을 가진 XML 파일을 재귀적으로 검색합니다.

cmdlet 도움말 XML 기반 도움말 파일 형식에 대한 자세한 내용은 Cmdlet 도움말작성하는 방법을 참조하세요.

자동 생성된 콘텐츠

이름, 구문, 매개 변수 목록, 매개 변수 특성 테이블, 공통 매개 변수 및 설명은 Get-Help cmdlet에 의해 자동으로 생성됩니다.

이름

함수 도움말 항목의 이름 섹션은 함수 구문의 함수 이름에서 가져옵니다. 스크립트 도움말 항목의 이름 스크립트 파일 이름에서 가져옵니다. 이름 또는 대문자를 변경하려면 함수 구문 또는 스크립트 파일 이름을 변경합니다.

통사론

도움말 항목의 구문 섹션은 함수 또는 스크립트 구문에서 생성됩니다. 매개 변수의 .NET 형식과 같은 도움말 항목 구문에 세부 정보를 추가하려면 구문에 세부 정보를 추가합니다. 매개 변수 형식을 지정하지 않으면 Object 형식이 기본값으로 삽입됩니다.

매개 변수 목록

도움말 항목의 매개 변수 목록은 함수 또는 스크립트 구문과 .PARAMETER 키워드를 사용하여 추가하는 설명에서 생성됩니다. 함수 매개 변수는 함수 또는 스크립트 구문에 표시되는 순서와 동일한 순서로 도움말 항목의 매개 변수 섹션에 표시됩니다. 매개 변수 이름의 맞춤법 및 대문자 지정도 구문에서 가져옵니다. .PARAMETER 키워드로 지정된 매개 변수 이름의 영향을 받지 않습니다.

일반적인 매개 변수

공통 매개 변수는 아무런 효과가 없더라도 도움말 항목의 구문 및 매개 변수 목록에 추가됩니다. 일반적인 매개 변수에 대한 자세한 내용은 about_CommonParameters참조하세요.

매개 변수 특성 테이블

Get-Help은 의 Full 또는 Get-Help 매개 변수를 사용할 때 표시되는 매개 변수 속성 테이블을 생성합니다. 필수, 위치및 기본 값 특성의 값은 함수 또는 스크립트 구문에서 가져옵니다.

와일드카드 문자 허용 기본값 및 값은 함수 또는 스크립트에 정의된 경우에도 매개 변수 특성 테이블에 나타나지 않습니다. 사용자를 돕기 위해 매개 변수 설명에 이 정보를 제공합니다.

발언

도움말 항목의 설명 섹션은 함수 또는 스크립트 이름에서 자동으로 생성됩니다. 콘텐츠는 변경하거나 영향을 줄 수 없습니다.

예시

함수에 대한 주석 기반 도움말

다음 샘플 함수에는 주석 기반 도움말이 포함되어 있습니다.

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

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

결과는 다음과 같습니다.

Get-Help -Name "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

http://www.fabrikam.com/extension.html
Set-Item

함수 구문의 매개 변수 설명

이 예제는 매개 변수 설명이 함수 구문에 삽입된다는 점을 제외하고 이전 예제와 동일합니다. 이 형식은 설명이 간단할 때 가장 유용합니다.

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.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.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

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

스크립트에 대한 주석 기반 도움말

다음 샘플 스크립트에는 주석 기반 도움말이 포함되어 있습니다. 닫는 #>과 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 { }
...

다음 명령은 스크립트 도움말을 가져옵니다. 스크립트가 $Env:PATH 환경 변수에 나열된 디렉터리에 없기 때문에 스크립트 도움말을 가져오는 Get-Help 명령은 스크립트 경로를 지정해야 합니다.

Get-Help -Name .\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

XML 파일로 리디렉션

함수 및 스크립트에 대한 XML 기반 도움말 콘텐츠를 작성할 수 있습니다. 주석 기반 도움말은 구현하기 더 쉽지만, 업데이트 가능한 도움말 및 여러 언어로 도움말 콘텐츠를 제공하려면 XML 기반 도움말이 필요합니다.

다음 예제에서는 Update-Month.ps1 스크립트의 처음 몇 줄을 보여줍니다. 스크립트는 .EXTERNALHELP 키워드를 사용하여 스크립트에 대한 XML 기반 도움말 항목의 경로를 지정합니다.

.EXTERNALHELP 키워드의 값은 키워드와 동일한 줄에 나타납니다. 다른 배치는 효과가 없습니다.

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutputPath)
function Get-Data { }
...

다음 예제에서는 함수에서 .EXTERNALHELP 키워드의 세 가지 유효한 배치를 보여 줍니다.

function Add-Extension {
    # .EXTERNALHELP C:\ps-test\Add-Extension.xml

    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

# .EXTERNALHELP C:\ps-test\Add-Extension.xml
function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

다른 도움말 항목으로 리디렉션

다음 코드는 PowerShell에서 기본 제공 도움말 함수의 시작 부분에서 발췌한 것으로, 도움말 텍스트의 화면을 한 번에 하나씩 표시합니다. 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},
    ...

다음 명령은 이 기능을 사용합니다.

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

참고하십시오

• 함수에_대해
• 함수_고급_매개변수에_대하여
• about_Scripts
• 쓰기 Comment-Based 도움말 콘텐츠