필수 개발 지침

cmdlet을 작성할 때는 다음 지침을 따라야 합니다. cmdlet을 디자인하기 위한 지침과 cmdlet 코드를 작성하기 위한 지침으로 구분됩니다. 이러한 지침을 따르지 않으면 cmdlet이 실패할 수 있으며 사용자가 cmdlet을 사용할 때 환경이 좋지 않을 수 있습니다.

이 항목에서

디자인 지침

코드 지침

디자인 지침

cmdlet과 다른 cmdlet 사용 간에 일관된 사용자 환경을 보장하기 위해 cmdlet을 디자인할 때 다음 지침을 따라야 합니다. 상황에 적용되는 디자인 지침을 찾으면 코드 지침에서 유사한 지침을 확인해야 합니다.

승인된 동사만 사용(RD01)

Cmdlet 특성에 지정된 동사는 Windows PowerShell에서 제공하는 인식된 동사 집합에서 제공되어야 합니다. 금지된 동의어 중 하나가 되어서는 안 됩니다. 다음 열거형으로 정의된 상수 문자열을 사용하여 cmdlet 동사를 지정합니다.

  • system.Management.Automation.VerbsCommon
  • System.Management.Automation.VerbsCommunications
  • System.Management.Automation.VerbsData
  • system.Management.Automation.VerbsDiagnostic
  • System.Management.Automation.VerbsLifecycle
  • System.Management.Automation.VerbsSecurity
  • System.Management.Automation.VerbsOther

승인된 동사 이름에 대한 자세한 내용은 Cmdlet 동사를 참조하세요.

사용자에게 검색 가능한 예상 cmdlet 이름 집합이 필요합니다. 사용자가 cmdlet이 수행하는 작업을 빠르게 평가하여 시스템의 기능을 쉽게 검색할 수 있도록 적절한 동사를 사용합니다. 예를 들어 다음 명령줄 명령은 이름이 "Start" Get-Command Start-*로 시작하는 시스템의 모든 명령 목록을 가져옵니다. cmdlet의 명사로 cmdlet을 다른 cmdlet과 구분합니다. 명사에서는 작업이 수행될 리소스를 나타냅니다. 작업 자체는 동사로 표시됩니다.

Cmdlet 이름: 사용할 수 없는 문자(RD02)

cmdlet의 이름을 지정할 때는 다음 특수 문자를 사용하지 마세요.

캐릭터 이름
# 숫자 기호
, 쉼표
( ) 괄호
{ } 중괄호
[ ] 대괄호
& 앰퍼샌드
- 하이픈
/ 슬래시 표시
\ 백슬래시
$ 달러 기호
^ caret
; 세미콜론
: colon
" 큰따옴표
' 작은따옴표
< > 꺾쇠 괄호
| 세로 막대
? 물음표
@ 서명 시
` 후면 틱(그레이브 악센트)
* 별표
% 백분율 기호
+ 더하기 기호
= 등호
~ 물결표

사용할 수 없는 매개 변수 이름(RD03)

Windows PowerShell은 모든 cmdlet에 공통 매개 변수 집합과 특정 상황에서 추가된 추가 매개 변수를 제공합니다. 고유한 cmdlet을 디자인할 때는 다음 ErrorActionWarningActionWarningVariableOutVariableVerboseDebugUseTransactionErrorVariableWhatIfOutBuffer이름을 Confirm사용할 수 없습니다. 이러한 매개 변수에 대한 자세한 내용은 일반 매개 변수 이름을 참조하세요.

지원 확인 요청(RD04)

시스템을 수정하는 작업을 수행하는 cmdlet의 경우 System.Management.Automation.Cmdlet.ShouldProcess* 메서드를 호출하여 확인을 요청해야 하며, 특별한 경우 System.Management.Automation.Cmdlet.ShouldContinue* 메서드를 호출해야 합니다. System.Management.Automation.Cmdlet.ShouldContinue* 메서드는 System.Management.Automation.Cmdlet.ShouldProcess* 메서드를 호출한 후에만 호출해야 합니다.

이러한 호출을 하려면 cmdlet은 Cmdlet 특성의 키워드를 설정 SupportsShouldProcess 하여 확인 요청을 지원하도록 지정해야 합니다. 이 특성을 설정하는 방법에 대한 자세한 내용은 Cmdlet 특성 선언을 참조하세요.

메모

cmdlet 클래스의 Cmdlet 특성이 cmdlet이 System.Management.Automation.Cmdlet.ShouldProcess* 메서드에 대한 호출을 지원한다는 것을 나타내고 cmdlet이 System.Management.Automation.Cmdlet.ShouldProcess* 메서드를 호출하지 못하면 사용자가 예기치 않게 시스템을 수정할 수 있습니다.

시스템 수정에는 System.Management.Automation.Cmdlet.ShouldProcess* 메서드를 사용합니다. 사용자 기본 설정 및 WhatIf 매개 변수는 System.Management.Automation.Cmdlet.ShouldProcess* 메서드를 제어합니다 . 반면 System.Management.Automation.Cmdlet.ShouldContinue* 호출은 잠재적으로 위험한 수정에 대한 추가 검사를 수행합니다. 이 메서드는 사용자 기본 설정 또는 매개 변수에 WhatIf 의해 제어되지 않습니다. cmdlet이 System.Management.Automation.Cmdlet.ShouldContinue* 메서드를 호출하는 경우 이 두 메서드에 대한 호출을 무시하고 작업을 진행하는 매개 변수가 있어야 합니다 Force . 이는 비대화형 스크립트 및 호스트에서 cmdlet을 사용할 수 있기 때문에 중요합니다.

cmdlet이 이러한 호출을 지원하는 경우 사용자는 작업을 실제로 수행해야 하는지 여부를 결정할 수 있습니다. 예를 들어 Stop-Process cmdlet은 System,Winlogon 및 Spoolsv 프로세스를 비롯한 중요한 프로세스 집합을 중지하기 전에 System.Management.Automation.Cmdlet.ShouldContinue* 메서드를 호출합니다.

이러한 방법을 지원하는 방법에 대한 자세한 내용은 확인 요청을 참조하세요.

대화형 세션에 대한 Force 매개 변수 지원(RD05)

cmdlet이 대화형으로 사용되는 경우 항상 Force 매개 변수를 제공하여 프롬프트 또는 입력 줄 읽기와 같은 대화형 작업을 재정의합니다. 이는 비대화형 스크립트 및 호스트에서 cmdlet을 사용할 수 있기 때문에 중요합니다. 다음 메서드는 대화형 호스트에서 구현할 수 있습니다.

문서 출력 개체(RD06)

Windows PowerShell은 파이프라인에 기록된 개체를 사용합니다. 사용자가 각 cmdlet에서 반환되는 개체를 활용하려면 반환되는 개체를 문서화해야 하며 반환된 개체의 멤버가 사용되는 항목을 문서화해야 합니다.

코드 지침

cmdlet 코드를 작성할 때는 다음 지침을 따라야 합니다. 상황에 적용되는 코드 지침을 찾으면 디자인 지침에서 유사한 지침을 확인해야 합니다.

Cmdlet 또는 PSCmdlet 클래스에서 파생(RC01)

cmdlet은 System.Management.Automation.Cmdlet 또는 System.Management.Automation.PSCmdlet 기본 클래스에서 파생되어야 합니다. System.Management.Automation.Cmdlet 클래스에서 파생되는 cmdlet은 Windows PowerShell 런타임에 의존하지 않습니다. Microsoft .NET Framework 언어에서 직접 호출할 수 있습니다. System.Management.Automation.PSCmdlet 클래스에서 파생되는 cmdlet은 Windows PowerShell 런타임에 따라 달라집니다. 따라서 Runspace 내에서 실행됩니다.

구현하는 모든 cmdlet 클래스는 공용 클래스여야 합니다. 이러한 cmdlet 클래스에 대한 자세한 내용은 Cmdlet 개요를 참조하세요.

Cmdlet 특성 지정(RC02)

Windows PowerShell에서 cmdlet을 인식하려면 .NET Framework 클래스를 Cmdlet 특성으로 데코레이트해야 합니다. 이 특성은 cmdlet의 다음 기능을 지정합니다.

  • cmdlet을 식별하는 동사 및 명사 쌍입니다.

  • 여러 매개 변수 집합을 지정할 때 사용되는 기본 매개 변수 집합입니다. 기본 매개 변수 집합은 Windows PowerShell에 사용할 매개 변수 집합을 결정하는 데 충분한 정보가 없는 경우에 사용됩니다.

  • cmdlet이 System.Management.Automation.Cmdlet.ShouldProcess* 메서드에 대한 호출을 지원하는지 나타냅니다. 이 메서드는 cmdlet이 시스템을 변경하기 전에 사용자에게 확인 메시지를 표시합니다. 확인 요청이 이루어지는 방법에 대한 자세한 내용은 확인 요청을 참조하세요.

  • 확인 메시지와 연결된 작업의 영향 수준(또는 심각도)을 나타냅니다. 대부분의 경우 보통의 기본값을 사용해야 합니다. 영향 수준이 사용자에게 표시되는 확인 요청에 미치는 영향에 대한 자세한 내용은 확인 요청을 참조하세요.

cmdlet 특성을 선언하는 방법에 대한 자세한 내용은 CmdletAttribute 선언을 참조하세요.

입력 처리 방법 재정의(RC03)

cmdlet이 Windows PowerShell 환경에 참여하려면 다음 입력 처리 방법 중 하나 이상을 재정의해야 합니다.

OutputType 특성 지정(RC04)

OutputType 특성(Windows PowerShell 2.0에서 도입됨)은 cmdlet이 파이프라인으로 반환하는 .NET Framework 형식을 지정합니다. cmdlet의 출력 형식을 지정하면 cmdlet에서 반환된 개체를 다른 cmdlet에서 더 쉽게 검색할 수 있습니다. 이 특성으로 cmdlet 클래스를 데코레이팅하는 방법에 대한 자세한 내용은 OutputType 특성 선언을 참조하세요.

출력 개체에 대한 핸들 유지 안 함(RC05)

cmdlet은 System.Management.Automation.Cmdlet.WriteObject* 메서드에 전달되는 개체에 대한 핸들을 유지해서는 안 됩니다. 이러한 개체는 파이프라인의 다음 cmdlet에 전달되거나 스크립트에서 사용됩니다. 개체에 대한 핸들을 유지하면 두 엔터티가 각 개체를 소유하므로 오류가 발생합니다.

강력한 오류 처리(RC06)

관리 환경은 기본적으로 사용자가 관리하는 시스템을 검색하고 중요한 변경을 합니다. 따라서 cmdlet이 오류를 올바르게 처리하는 것이 중요합니다. 오류 레코드에 대한 자세한 내용은 Windows PowerShell 오류 보고를 참조하세요.

System.Management.Automation.ErrorRecord 개체에는 사용자에 대한 오류를 그룹화하는 오류 범주도 필요합니다. 사용자는 셸 변수의 $ErrorView 값을 CategoryView로 설정하여 범주에 따라 오류를 볼 수 있습니다. 가능한 범주는 System.Management.Automation.ErrorCategory 열거형에 의해 정의됩니다.

  • cmdlet이 새 스레드를 만들고 해당 스레드에서 실행 중인 코드가 처리되지 않은 예외를 throw하는 경우 Windows PowerShell에서 오류를 catch할 수 없고 프로세스를 종료합니다.

  • 개체의 소멸자에서 처리되지 않은 예외를 발생시키는 코드가 있는 경우 Windows PowerShell은 오류를 catch할 수 없고 프로세스를 종료합니다. 개체가 처리되지 않은 예외를 발생시키는 Dispose 메서드를 호출하는 경우에도 발생합니다.

Windows PowerShell 모듈을 사용하여 cmdlet 배포(RC07)

cmdlet을 패키지하고 배포하는 Windows PowerShell 모듈을 만듭니다. 모듈에 대한 지원은 Windows PowerShell 2.0에서 도입되었습니다. cmdlet 클래스를 포함하는 어셈블리를 이진 모듈 파일로 직접 사용하거나(cmdlet을 테스트할 때 매우 유용함) cmdlet 어셈블리를 참조하는 모듈 매니페스트를 만들 수 있습니다. 모듈을 사용할 때 기존 스냅인 어셈블리를 추가할 수도 있습니다. 모듈에 대한 자세한 내용은 Windows PowerShell 모듈 작성을 참조하세요.

참조 항목

  • Last updated on