안녕하세요. 엉스데브 입니다.
오늘은 자작 함수 및 스크립트에 대한 도움말을 작성하는 방법에 대해 알아보겠습니다.
PowerShell 은 Get-Help 라는 도움말 출력 전용 cmdlet 을 제공 합니다.
Get-Help cmdlet 에 자기가 실행하고자 하는 명령어를 지정하면 해당 명령어에 맞는 도움말을 보여주는데요.
PowerShell 에 기본 내장 된 명령어 뿐만 아니라, 직접 만든 함수/스크립트도 Get-Help 를 통해 도움말을 볼 수 있습니다.
다만, 이게 가능하려면 함수/스크립트 작성 시, 주석에 지정된 키워드 및 특정 형식을 지켜서 도움말에 표시 될 내용을 미리 적어 두어야 합니다.
다음은 간단한 도움말을 작성한 함수의 예 입니다.
{
<#
.Synopsis
현재 세션의 역할이 지정한 역할에 포함되어 있는지 확인 합니다.
.Description
현재 세션의 역할이 지정한 역할에 포함되어 있는지 확인 합니다. Role 파라미터에 Administrator 를 주면 현재 세션이 관리자 권한이 있는지 확인하는 용도로 사용 할 수 있습니다.
.Parameter Role
System.String 윈도우 내장 역할을 의미하는 문자열 입니다. 다음 9가지 값 중 선택 가능 합니다.
Administrators, User, Guest, PowerUser, AccountOperator, SystemOperator, PrintOperator, BackupOperator, Replicator
.Example
Test-Role Administrator
False
설명
-----------
현재 세션이 관리자 권한이 아닌 것을 알 수 있습니다.
.Example
Test-Role User
True
설명
-----------
현재 세션이 유저 권한을 가지고 있음을 알 수 있습니다.
.Link
http://svrstudy.tistory.com/26
#>
Param( [Security.Principal.WindowsBuiltinRole]$Role )
$CurrentUser = [Security.Principal.WindowsPrincipal]([Security.Principal.WindowsIdentity]::GetCurrent())
$CurrentUser.IsInRole($Role)
}
도움말 키워드는 . 으로 시작하게 되며, 키워드에 대한 설명은 바로 다음줄 부터 입니다.
설명의 범위는 다른 키워드를 만나거나, 주석이 끝날 때 까지 입니다.
이 예제 함수에 대해 Get-Help 명령어를 실행 하면, 아래와 같이 표시 됩니다.
@Get-Help Test-Role
@Get-Help Test-Role -detailed
다음은 자주 사용되는 도움말용 키워드 목록 및 간단한 설명입니다.
: 함수나 스크립트에 대한 간단한 설명입니다.
2. Description - 설명
: 함수나 스크립트에 대한 자세한 설명입니다
3. Parameter - 매개 변수
: 매개 변수에 대한 설명입니다. 키워드를 적고 바로 뒤에 파라미터 명을 적으시면 됩니다.
4. Example - 예
: 함수나 스크립트를 사용하는 샘플 명령이며, 그 뒤에 샘플 출력과 설명이 올 수 있습니다. 여러개의 예제가 있을 경우, 반복해서 사용하면 됩니다.
5. Link - 관련 링크
: 관련 항목의 이름, 혹은 웹문서의 주소를 지정 할 수 있습니다. 웹 문서를 지정 하는 경우, 반드시 http:// 또는 https:// 로 시작 해야 합니다.
@맺음말:
아무리 잘 만든 함수나 스크립트라도 적절한 설명 혹은 도움말이 없으면, 다른 사람들에게는 도움이 되지 않습니다.
함수나 스크립트에 도움말을 잘 작성 해 두면, 다른 사람이 좀 더 손쉽게 사용 할 수 있게 되어 환영 받고, 더 많이 사용 될 것입니다.
자신이 만든 PowerShell 함수 혹은 스크립트에 도움말을 작성해서, 생명력을 불어넣어 주세요. ^^
감사합니다.
<참고 문서>
about_Comment_Based_Help
'Powershell > 엉스데브' 카테고리의 다른 글
| PowerShell 을 이용해서 파일 내용 대량으로 변경 하기. (sed) (0) | 2010.11.09 |
|---|---|
| PowerShell 로 원격 서버 관리하기. (5) | 2010.10.05 |
| PowerShell 에서 작업 한 모든 내용을 기록하기(Start-Transcript) (0) | 2010.09.28 |
| PowerShell 로 이벤트 로그 저장 설정 변경하기(+ wevtutil) (0) | 2010.09.27 |
| PowerShell 에서 윈도우 내장 방화벽 관리하기 (0) | 2010.09.15 |
