항목
about_Comment_Based_Help
간단한 설명
함수 및 스크립트에 대한 설명 기반 도움말 항목을 작성하는 방법에 대해 설명합니다.
자세한 설명
특수 도움말 설명 키워드를 사용하여 함수와 스크립트에 대한 설명 기반 도움말 항목을 작성할 수 있습니다.
Get-Help cmdlet은 XML 파일에서 생성되는 cmdlet 도움말 항목을 표시하는 것과 동일한 형식으로 설명
기반 도움말을 표시합니다. 사용자는 Detailed, Full, Example, Online 등의 Get-Help
매개 변수를 모두 사용하여 함수 및 스크립트 도움말을 표시할 수 있습니다.
도움말 설명 키워드를 사용하여 스크립트 및 함수에 대한 XML 기반 도움말 파일을 작성하고 사용자를 다른 도움말
파일로 리디렉션할 수도 있습니다.
이 항목에서는 함수와 스크립트에 대한 도움말 항목을 작성하는 방법에 대해 설명합니다. 함수와 스크립트에 대한
도움말 항목을 표시하는 방법에 대한 자세한 내용은 Get-Help를 참조하십시오.
설명 기반 도움말의 구문
설명 기반 도움말의 구문은 다음과 같습니다.
# .< help keyword>
# <help content>
-또는 -
<#
.< help keyword>
< help content>
#>
설명 기반 도움말은 일련의 설명으로 작성됩니다. 각 설명 줄 앞에 설명 기호(#)를 입력하거나 "<#" 및 "#>" 기호를
사용하여 설명 블록을 만들 수 있습니다. 설명 블록 내의 모든 줄은 설명으로 해석됩니다.
설명 기반 도움말 항목에 있는 모든 줄은 연속적이어야 합니다. 설명 기반 도움말 항목이 도움말 항목에 속하지 않은
설명 뒤에 나오는 경우, 도움말이 아닌 마지막 설명 줄과 설명 기반 도움말의 시작 부분 사이에 하나 이상의 빈 줄이
있어야 합니다.
키워드는 설명 기반 도움말의 각 섹션을 정의합니다. 각 설명 기반 도움말 키워드 앞에는 점(.)이 오며, 키워드는 어떤
순서로든 나타날 수 있습니다. 키워드 이름은 대/소문자를 구분하지 않습니다.
예를 들어, Description 키워드는 함수나 스크립트에 대한 설명 앞에 올 수 있습니다.
<#
.Description
Get-Function은 세션에 있는 모든 함수의 이름과 구문을 표시합니다.
#>
설명 블록에는 키워드가 하나 이상 포함되어야 합니다. EXAMPLE과 같은 일부 키워드는 동일한 설명 블록에 여러 번
나타날 수 있습니다. 각 키워드에 대한 도움말 내용은 키워드 다음 줄에서 시작하며 여러 줄에 표시될 수 있습니다.
함수에 대한 설명 기반 도움말의 구문
함수에 대한 설명 기반 도움말은 다음 세 위치 중 하나에 나타날 수 있습니다.
-- 함수 본문의 시작 부분
-- 함수 본문의 끝 부분
-- Function 키워드 앞. 함수 도움말의 마지막 줄과 Function 키워드 사이에 둘 이상의 빈 줄이
있을 수 없습니다.
예를 들면 다음과 같습니다.
function MyFunction
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-또는 -
function MyFunction
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-또는 -
<#
.< help keyword>
< help content>
#>
function MyFunction { }
스크립트에 대한 설명 기반 도움말의 구문
스크립트에 대한 설명 기반 도움말은 스크립트에서 다음 두 위치 중 하나에 나타날 수 있습니다.
-- 스크립트 파일의 시작 부분. 스크립트에서 스크립트 도움말 앞에는 설명과 빈 줄만 표시될 수 있습니다.
-- 스크립트 본문의 첫 번째 항목(도움말 뒤)이 함수 선언인 경우 스크립트 도움말의 끝 부분과 함수 선언 사이에는 둘
이상의 빈 줄이 있어야 합니다. 그렇지 않으면 도움말이 스크립트에 대한 도움말이 아니라 함수에 대한 도움말로
해석됩니다.
-- 스크립트 파일의 끝 부분
예를 들면 다음과 같습니다.
<#
.< help keyword>
< help content>
#>
function MyFunction { }
-또는-
function MyFunction { }
<#
.< help keyword>
< help content>
#>
설명 기반 도움말 키워드
다음은 유효한 설명 기반 도움말 키워드로, 일반적으로 해당 용도와 함께 도움말 항목에 나타나는
순서로 나열되어 있습니다.
이 키워드는 설명 기반 도움말에서 어떤 순서로든 나타날 수 있으며 대/소문자를 구분하지 않습니다.
.SYNOPSIS
함수나 스크립트에 대한 간단한 설명입니다. 이 키워드는 항목마다 한 번씩만 사용할 수 있습니다.
.DESCRIPTION
함수나 스크립트에 대한 자세한 설명입니다. 이 키워드는 항목마다 한 번씩만 사용할 수 있습니다.
.PARAMETER <Parameter-Name>
매개 변수에 대한 설명입니다. 함수 또는 스크립트 구문에는 각 매개 변수에 대한 Parameter 키워드가 포함될 수
있습니다.
설명 블록에서 Parameter 키워드는 어떤 순서로든 나타날 수 있지만, 도움말 항목에서 매개 변수 및 매개
변수 설명이 나타나는 순서는 함수 또는 스크립트 구문에 따라 결정됩니다. 순서를 변경하려면 구문을 변경합니다.
함수 또는 스크립트 구문에서 매개 변수 이름 바로 앞에 설명을 넣어 매개 변수 설명을 지정할 수도 있습니다.
구문 설명과 Parameter 키워드를 모두 사용하는 경우 Parameter 키워드와 관련된 설명이 사용되고
구문 설명은 무시됩니다.
.EXAMPLE
함수나 스크립트를 사용하는 샘플 명령이며, 그 뒤에 샘플 출력과 설명이 올 수 있습니다. 각 예제에 대해 이
키워드를 반복합니다.
.INPUTS
함수나 스크립트로 파이프될 수 있는 Microsoft .NET Framework 유형의 개체입니다. 입력 개체에 대한 설명도
포함할 수 있습니다.
.OUTPUTS
cmdlet에서 반환되는 .NET Framework 유형의 개체입니다. 반환된 개체에 대한 설명도 포함할 수 있습니다.
.NOTES
함수나 스크립트에 대한 추가 정보입니다.
.LINK
관련 항목의 이름입니다. 각 관련 항목에 대해 이 키워드를 반복합니다.
이 내용은 도움말 항목의 관련 링크 섹션에 나타납니다.
Link 키워드 내용에는 동일한 도움말 항목의 온라인 버전에 대한 URI(Uniform Resource Identifier)도
포함될 수 있습니다. Get-Help의 Online 매개 변수를 사용하면 온라인 버전이 열립니다. URI는 "http" 또는
"https"로 시작해야 합니다.
.COMPONENT
함수나 스크립트에 사용되거나 이와 관련된 기술 또는 기능입니다. Get-Help 명령에 Get-Help의
Component 매개 변수가 포함되면 이 내용이 나타납니다.
.ROLE
도움말 항목에 대한 사용자 역할입니다. Get-Help 명령에 Get-Help의 Role 매개 변수가 포함되면
이 내용이 나타납니다.
.FUNCTIONALITY
함수의 용도입니다. Get-Help 명령에 Get-Help의 Functionality 매개 변수가 포함되면 이
내용이 나타납니다.
.FORWARDHELPTARGETNAME <Command-Name>
지정된 명령에 대한 도움말 항목으로 리디렉션합니다. 함수, 스크립트, cmdlet 또는 공급자에 대한 도움말 항목을
포함하여 어떤 도움말 항목으로든 사용자를 리디렉션할 수 있습니다.
.FORWARDHELPCATEGORY <Category>
ForwardHelpTargetName에서 항목의 도움말 범주를 지정합니다.
유효한 값은 Alias, Cmdlet, HelpFile, Function, Provider, General,
FAQ, Glossary, ScriptCommand, ExternalScript, Filter 또는
All입니다. 이 키워드를 사용하여 같은 이름의 명령이 여러 개 있을 때 충돌을 방지합니다.
.REMOTEHELPRUNSPACE <PSSession-variable>
도움말 항목이 포함되는 세션을 지정합니다. PSSession이 포함된 변수를 입력합니다. Export-PSSession
cmdlet에서는 이 키워드를 사용하여 내보낸 명령에 대한 도움말 항목을 찾습니다.
.EXTERNALHELP <XML Help File Path>
스크립트나 함수에 대한 XML 기반 도움말 파일의 경로를 지정합니다.
Windows Vista 이상 버전의 Windows에서는 지정된 XML 파일 경로에 UI culture별 하위
디렉터리가 포함될 경우 Get-Help는 모든 XML 기반 도움말 항목과 마찬가지로 Windows Vista에
설정된 언어 대체 표준에 따라 하위 디렉터리에서 스크립트 또는 함수 이름이 있는 XML 파일을 재귀적으로
검색합니다.
cmdlet 도움말 XML 기반 도움말 파일 형식에 대한 자세한 내용은 MSDN(Microsoft Developer Network)
라이브러리의 "How to Create Cmdlet Help(Cmdlet 도움말 만드는 방법)"
(https://go.microsoft.com/fwlink/?LinkID=123415)를 참조하십시오.
자동 생성되는 내용
이름, 구문, 매개 변수 목록, 매개 변수 특성 테이블, 일반 매개 변수 및 설명은 Get-Help cmdlet에서 자동으로
생성됩니다.
이름:
함수 도움말 항목의 이름 섹션은 함수 구문의 함수 이름에서 가져오고, 스크립트 도움말 항목의 이름은 스크립트
파일 이름에서 가져옵니다. 이름 또는 이름의 대문자 표시를 변경하려면 함수 구문이나 스크립트 파일 이름을
변경합니다.
구문:
도움말 항목의 구문 섹션은 함수 또는 스크립트 구문에서 생성됩니다. 매개 변수의 .NET Framework 유형과 같은
상세 정보를 도움말 항목 구문에 추가하려면 상세 정보를 구문에 추가합니다. 매개 변수 유형을 지정하지
않으면 "Object" 유형이 기본값으로 삽입됩니다.
매개 변수 목록:
도움말 항목의 매개 변수 목록은 함수 또는 스크립트 구문과 매개 변수 키워드를 사용하여 추가하는 설명에서
생성됩니다. 함수 매개 변수는 함수 또는 스크립트 구문에 나타나는 것과 동일한 순서로 도움말 항목의 "매개
변수" 섹션에 나타냅니다. 매개 변수 이름의 철자와 대문자 표시도 구문에서 가져오며 Parameter 키워드를 통해
지정되는 매개 변수 이름의 영향을 받지 않습니다.
일반 매개 변수:
일반 매개 변수는 영향이 없더라도 도움말 항목의 구문과 매개 변수 목록에 추가됩니다. 일반 매개 변수에 대한
자세한 내용은 about_CommonParameters를 참조하십시오.
매개 변수 특성 테이블:
Get-Help는 Get-Help의 Full 또는 Parameter 매개 변수를 사용할 때 나타나는
매개 변수 특성 테이블을 생성합니다. 필수 여부, 위치 및 기본값 특성의 값은 함수 또는 스크립트 구문에서
가져옵니다.
설명:
도움말 항목의 설명 섹션은 함수 또는 스크립트 이름에서 자동으로 생성됩니다. 내용을 변경하거나 내용에
영향을 줄 수 없습니다.
예제
예 1: 함수에 대한 설명 기반 도움말
다음 샘플 함수에는 설명 기반 도움말이 포함됩니다.
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
제공된 이름에 파일 이름 확장명을 추가합니다.
.DESCRIPTION
제공된 이름에 파일 이름 확장명을 추가합니다. 파일 이름 또는 확장명으로 사용할 수 있는 문자열에는 제한이
없습니다.
.PARAMETER Name
파일 이름을 지정합니다.
.PARAMETER Extension
확장명을 지정합니다. 기본값은 "Txt"입니다.
.INPUTS
None. Add-Extension으로 개체를 파이프할 수 없습니다.
.OUTPUTS
System.String. Add-Extension은 확장명 또는 파일 이름을 포함한 문자열을 반환합니다.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
온라인 버전: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
결과는 다음과 같습니다.
C:\PS> get-help add-extension -full
이름
Add-Extension
개요
제공된 이름에 파일 이름 확장명을 추가합니다.
구문
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
설명
제공된 이름에 파일 이름 확장명을 추가합니다. 파일 이름 또는 확장명으로 사용할 수 있는 문자열에는 제한이
없습니다.
매개 변수
-Name
파일 이름을 지정합니다.
필수 여부 false
위치 0
기본값
파이프라인 입력 적용 여부 false
와일드카드 문자 적용 여부
-Extension
확장명을 지정합니다. 기본값은 "Txt"입니다.
필수 여부 false
위치 1
기본값
파이프라인 입력 적용 여부 false
와일드카드 문자 적용 여부
<CommonParameters>
이 cmdlet은 -Verbose, -Debug, ErrorAction,
-ErrorVariable, -WarningAction, -WarningVariable,
OutBuffer, -OutVariable 등의 일반 매개 변수를 지원합니다. 자세한 내용을
보려면 "get-help about_commonparameters"를 입력하십시오.
입력
None. Add-Extension으로 개체를 파이프할 수 없습니다.
출력
System.String. Add-Extension은 확장명 또는 파일 이름을 포함한 문자열을 반환합니다.
-------------------------- 예제 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- 예제 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- 예제 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
관련 링크
온라인 버전: http://www.fabrikam.com/extension.html Set-Item
예제 2: 함수 구문의 매개 변수 설명
이 예제는 매개 변수 설명이 함수 구문에 삽입된다는 점을 제외하고 앞의 예와 동일합니다. 이 형식은 설명이
간략할 때 가장 유용합니다.
function Add-Extension
{
param
(
[string]
# 파일 이름을 지정합니다.
$name,
[string]
# 파일 이름 확장명을 지정합니다. 기본값은 "Txt"입니다.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
제공된 이름에 파일 이름 확장명을 추가합니다.
.DESCRIPTION
제공된 이름에 파일 이름 확장명을 추가합니다. 파일 이름 또는 확장명으로 사용할 수 있는 문자열에는 제한이
없습니다.
.INPUTS
None. Add-Extension으로 개체를 파이프할 수 없습니다.
.OUTPUTS
System.String. Add-Extension은 확장명 또는 파일 이름을 포함한 문자열을 반환합니다.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
온라인 버전: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
예제 3: 스크립트에 대한 설명 기반 도움말
다음 샘플 스크립트에는 설명 기반 도움말이 포함됩니다.
닫는 "#>" 및 Param 문 사이에 빈 줄이 있습니다. Param 문이 없는 스크립트에서는 도움말 항목의
마지막 설명과 첫 번째 함수 선언 사이에 둘 이상의 빈 줄이 있어야 합니다. 이 사이에 빈 줄이 없으면 Get-
Help는 도움말 항목을 스크립트가 아닌 함수와 연결합니다.
<#
.SYNOPSIS
매월 데이터 업데이트를 수행합니다.
.DESCRIPTION
Update-Month.ps1 스크립트는 지난 달에 생성된 새 데이터로 레지스트리를 업데이트하고 보고서를
생성합니다.
.PARAMETER InputPath
CSV 기반 입력 파일의 경로를 지정합니다.
.PARAMETER OutputPath
CSV 기반 출력 파일의 이름과 경로를 지정합니다. 기본적으로 MonthlyUpdates.ps1은 실행
날짜와 시간으로 이름을 생성하고 로컬 디렉터리에 출력을 저장합니다.
.INPUTS
None. Update-Month.ps1로 개체를 파이프할 수 없습니다.
.OUTPUTS
None. Update-Month.ps1은 출력을 생성하지 않습니다.
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\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 C:\ps-test> get-help .\update-month.ps1 -full
이름
C:\ps-test\Update-Month.ps1
개요
매월 데이터 업데이트를 수행합니다.
구문
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]
설명
Update-Month.ps1 스크립트는 지난 달에 생성된 새 데이터로 레지스트리를 업데이트하고
보고서를 생성합니다.
매개 변수
-InputPath
CSV 기반 입력 파일의 경로를 지정합니다.
필수 여부 true
위치 0
기본값
파이프라인 입력 적용 여부 false
와일드카드 문자 적용 여부
-OutputPath
CSV 기반 출력 파일의 이름과 경로를 지정합니다. 기본적으로 MonthlyUpdates.p
s1은 실행 날짜와 시간으로 이름을 생성하고 로컬 디렉터리에 출력을 저장합니다.
필수 여부 false
위치 1
기본값
파이프라인 입력 적용 여부 false
와일드카드 문자 적용 여부
<CommonParameters>
이 cmdlet은 -Verbose, -Debug, ErrorAction,
-ErrorVariable, -WarningAction, -WarningVariable,
OutBuffer, -OutVariable 등의 일반 매개 변수를 지원합니다. 자세한
내용을 보려면 "get-help about_commonparameters"를 입력하십시오.
입력
없음. Update-Month.ps1로 개체를 파이프할 수 없습니다.
출력
없음. Update-Month.ps1은 출력을 생성하지 않습니다.
-------------------------- 예제 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- 예제 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- 예제 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
관련 링크
예제 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: 다른 도움말 항목으로 리디렉션
다음 코드는 한 번에 하나의 도움말 화면을 표시하는 Windows 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},
...
다음 명령은 이 기능을 사용합니다.
C:\PS> get-help help
이름
Get-Help
개요
Windows PowerShell cmdlet 및 개념에 대한 정보를 표시합니다.
...
참고 항목
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"How to Write Cmdlet Help(Cmdlet 도움말 작성 방법)" (https://go.microsoft.com/fwlink/?LinkID=123415)