2010. 10. 26. 14:12

안녕하세요. 엉스데브 입니다.

오늘은 자작 함수 및 스크립트에 대한 도움말을 작성하는 방법에 대해 알아보겠습니다.

PowerShell 은 Get-Help 라는 도움말 출력 전용 cmdlet 을 제공 합니다.
Get-Help cmdlet 에 자기가 실행하고자 하는 명령어를 지정하면 해당 명령어에 맞는 도움말을 보여주는데요.

PowerShell 에 기본 내장 된 명령어 뿐만 아니라, 직접 만든 함수/스크립트도 Get-Help 를 통해 도움말을 볼 수 있습니다.
다만, 이게 가능하려면 함수/스크립트 작성 시, 주석에 지정된 키워드 및 특정 형식을 지켜서 도움말에 표시 될 내용을 미리 적어 두어야 합니다.

다음은 간단한 도움말을 작성한 함수의 예 입니다.

Function Test-Role
{
<#
.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


다음은 자주 사용되는 도움말용 키워드 목록 및 간단한 설명입니다.

1. Synopsis - 개요
: 함수나 스크립트에 대한 간단한 설명입니다.

2. Description - 설명
: 함수나 스크립트에 대한 자세한 설명입니다

3. Parameter - 매개 변수
: 매개 변수에 대한 설명입니다. 키워드를 적고 바로 뒤에 파라미터 명을 적으시면 됩니다.

4. Example - 예
: 함수나 스크립트를 사용하는 샘플 명령이며, 그 뒤에 샘플 출력과 설명이 올 수 있습니다. 여러개의 예제가 있을 경우, 반복해서 사용하면 됩니다.

5. Link - 관련 링크
: 관련 항목의 이름, 혹은 웹문서의 주소를 지정 할 수 있습니다. 웹 문서를 지정 하는 경우, 반드시 http:// 또는 https:// 로 시작 해야 합니다.


@맺음말:
아무리 잘 만든 함수나 스크립트라도 적절한 설명 혹은 도움말이 없으면, 다른 사람들에게는 도움이 되지 않습니다.
함수나 스크립트에 도움말을 잘 작성 해 두면, 다른 사람이 좀 더 손쉽게 사용 할 수 있게 되어 환영 받고, 더 많이 사용 될 것입니다.

자신이 만든 PowerShell 함수 혹은 스크립트에 도움말을 작성해서, 생명력을 불어넣어 주세요. ^^

감사합니다.

<참고 문서>
about_Comment_Based_Help

Posted by 알 수 없는 사용자
:

BLOG main image
Windows Server를 공부 하는 사람들의 팀블로그 by 마성민

카테고리

분류 전체보기 (76)
Windows (2)
Powershell (56)
AD (0)
Exchange (6)
System Center (9)
IIS (0)
SQL (3)
Sharepoint (0)

태그목록

Tistory Cumulus Flash tag cloud by BLUEnLIVE requires Flash Player 9 or better.

Total :
Today : Yesterday :