다음을 통해 공유

적극 권장되는 개발 지침

이 섹션에서는 cmdlet을 작성할 때 따라야 하는 지침을 설명합니다. cmdlet을 디자인하기 위한 지침과 cmdlet 코드를 작성하기 위한 지침으로 구분됩니다. 이러한 지침은 모든 시나리오에 적용되지 않을 수 있습니다. 그러나 해당 지침이 적용되고 이러한 지침을 따르지 않으면 사용자가 cmdlet을 사용할 때 환경이 좋지 않을 수 있습니다.

디자인 지침

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

Cmdlet 이름에 특정 명사 사용(SD01)

cmdlet 이름 지정에 사용되는 명사에는 사용자가 cmdlet을 검색할 수 있도록 매우 구체적이어야 합니다. "서버"와 같은 일반적인 명사 앞에 제품 이름의 단축된 버전을 접두어로 추가하세요. 예를 들어 명사에서 Microsoft SQL Server 인스턴스를 실행하는 서버를 참조하는 경우 "SQLServer"와 같은 명사(예: "SQLServer")를 사용합니다. 특정 명사와 승인된 동사의 짧은 목록을 조합하여 cmdlet 이름 간의 중복을 방지하면서 기능을 빠르게 검색하고 예상할 수 있습니다.

사용자 환경을 개선하려면 cmdlet 이름에 대해 선택한 명사만 단수여야 합니다. 예를 들어 Get-Processes 대신 Get-Process 이름을 사용합니다. cmdlet이 둘 이상의 항목에 대해 작동할 가능성이 있는 경우에도 모든 cmdlet 이름에 대해 이 규칙을 따르는 것이 가장 좋습니다.

Cmdlet 이름에 파스칼 대/소문자 사용(SD02)

매개 변수 이름에 파스칼 표기법을 사용합니다. 즉, 동사의 첫 글자와 명사에 사용되는 모든 용어를 대문자로 표시합니다. 예: "Clear-ItemProperty".

매개 변수 디자인 지침(SD03)

cmdlet에는 작동해야 하는 데이터를 수신하는 매개 변수와 작업의 특성을 확인하는 데 사용되는 정보를 나타내는 매개 변수가 필요합니다. 예를 들어 cmdlet에는 Name 파이프라인에서 데이터를 수신하는 매개 변수가 있을 수 있으며 cmdlet에는 cmdlet이 강제로 작업을 수행할 수 있음을 나타내는 매개 변수가 있을 수 있습니다 Force . cmdlet이 정의할 수 있는 매개 변수 수에는 제한이 없습니다.

표준 매개 변수 이름 사용

사용자가 특정 매개 변수의 의미를 빠르게 확인할 수 있도록 cmdlet은 표준 매개 변수 이름을 사용해야 합니다. 더 구체적인 이름이 필요한 경우 표준 매개 변수 이름을 사용한 다음 더 구체적인 이름을 별칭으로 지정합니다. 예를 들어 Get-Service cmdlet에는 제네릭 이름()과 보다 구체적인 별칭(NameServiceName)이 있는 매개 변수가 있습니다. 두 용어를 모두 사용하여 매개 변수를 지정할 수 있습니다.

매개 변수 이름 및 해당 데이터 형식에 대한 자세한 내용은 Cmdlet 매개 변수 이름 및 기능 지침을 참조하세요.

단수 매개 변수 이름 사용

값이 단일 요소인 매개 변수에 복수 이름을 사용하지 않습니다. 여기에는 사용자가 하나의 요소로 배열 또는 목록을 제공할 수 있기 때문에 배열 또는 목록을 사용하는 매개 변수가 포함됩니다.

복수 매개 변수 이름은 매개 변수 값이 항상 다중 요소 값인 경우에만 사용해야 합니다. 이러한 경우 cmdlet은 여러 요소가 제공되었는지 확인해야 하며, 여러 요소가 제공되지 않으면 cmdlet에서 사용자에게 경고를 표시해야 합니다.

매개변수 이름에는 파스칼 케이스를 사용하세요.

매개 변수 이름에 Pascal 표기법을 사용합니다. 즉, 이름의 첫 글자를 포함하여 매개 변수 이름에 있는 각 단어의 첫 글자를 대문자로 표시합니다. 예를 들어 매개 변수 이름은 ErrorAction 올바른 대문자를 사용합니다. 다음 매개 변수 이름은 잘못된 대문자를 사용합니다.

  • errorAction
  • erroraction

옵션 목록을 사용하는 매개 변수

옵션 집합에서 값을 선택할 수 있는 매개 변수를 만드는 방법에는 두 가지가 있습니다.

  • 유효한 값을 지정하는 열거형 형식을 정의하거나 기존 열거형 형식을 사용합니다. 그런 다음 열거형 형식을 사용하여 해당 형식의 매개 변수를 만듭니다.

  • 매개 변수 선언에 ValidateSet 특성을 추가합니다. 이 특성에 대한 자세한 내용은 ValidateSet 특성 선언을 참조하세요.

매개 변수에 표준 형식 사용

다른 cmdlet과 일관성을 유지하려면 가능한 경우 매개 변수에 표준 형식을 사용합니다. 다른 매개 변수에 사용해야 하는 형식에 대한 자세한 내용은 Standard Cmdlet 매개 변수 이름 및 형식을 참조하세요. 이 항목에서는 "활동 매개 변수"와 같은 표준 매개 변수 그룹에 대한 이름 및 .NET Framework 형식을 설명하는 여러 항목에 대한 링크를 제공합니다.

강력한 형식의 .NET 프레임워크 유형 사용

매개 변수는 더 나은 매개 변수 유효성 검사를 제공하기 위해 .NET Framework 형식으로 정의되어야 합니다. 예를 들어 값 집합에서 하나의 값으로 제한된 매개 변수는 열거형 형식으로 정의되어야 합니다. URI(Uniform Resource Identifier) 값을 지원하려면 매개 변수를 System.Uri 형식으로 정의합니다. 자유 형식 텍스트 속성을 제외한 모든 속성에 대한 기본 문자열 매개 변수를 사용하지 않습니다.

일관된 매개 변수 형식 사용

여러 cmdlet에서 동일한 매개 변수를 사용하는 경우 항상 동일한 매개 변수 형식을 사용합니다. 예를 들어 매개 변수가 Process 한 cmdlet에 대한 System.Int16 형식인 경우 다른 cmdlet에 Process 대한 매개 변수를 System.Uint16 형식으로 만들지 마세요.

True 및 False를 사용하는 매개 변수

만약 매개 변수가 true 및 false만 사용한다면, 매개 변수를 System.Management.Automation.SwitchParameter 형식으로 정의합니다. [switch] 매개 변수는 명령에 지정된 경우처럼 true 처리됩니다. 매개 변수가 명령에 포함되지 않은 경우 Windows PowerShell은 매개 변수 값을 false 간주합니다. 부울 매개 변수를 정의하지 마세요.

매개 변수가 $true, $false 및 "unspecified"의 세 값을 구분해야 하는 경우 Nullable<bool> 형식의 매개 변수를 정의합니다. 개체의 불리언 속성을 cmdlet이 수정할 수 있는 경우에는 보통 세 번째 "지정되지 않은" 값이 필요합니다. 이 경우 "지정되지 않음"은 속성의 현재 값을 변경하지 않음을 의미합니다.

매개 변수에 대한 배열 지원

사용자가 여러 인수에 대해 동일한 작업을 수행해야 하는 경우가 많습니다. 이러한 사용자의 경우 사용자가 매개 변수에 인수를 Windows PowerShell 변수로 전달할 수 있도록 cmdlet은 배열을 매개 변수 입력으로 수락해야 합니다. 예를 들어 Get-Process cmdlet은 검색할 프로세스의 이름을 식별하는 문자열에 배열을 사용합니다.

PassThru 매개 변수 지원

기본적으로 Stop-Process cmdlet과 같이 시스템을 수정하는 많은 cmdlet은 개체에 대해 "싱크" 역할을 하며 결과를 반환하지 않습니다. 이러한 cmdlet은 cmdlet이 PassThru 개체를 반환하도록 강제하는 매개 변수를 구현해야 합니다. 매개 변수를 PassThru 지정하면 cmdlet은 System.Management.Automation.Cmdlet.WriteObject 메서드를 호출하여 개체를 반환합니다. 예를 들어 다음 명령은 Calc(CalculatorApp.exe)를 중지하고 결과 프로세스를 파이프라인에 전달합니다.

Stop-Process -Name CalculatorApp -PassThru

대부분의 경우 추가, 설정 및 새 cmdlet은 매개 변수를 PassThru 지원해야 합니다.

지원 매개 변수 집합

cmdlet은 단일 목적을 달성하기 위한 것입니다. 그러나 작업 또는 작업 대상을 설명하는 방법은 두 가지 이상인 경우가 많습니다. 예를 들어 프로세스는 해당 이름, 식별자 또는 프로세스 개체로 식별될 수 있습니다. cmdlet은 대상의 모든 적절한 표현을 지원해야 합니다. 일반적으로 cmdlet은 함께 작동하는 매개 변수 집합(매개 변수 집합이라고 함)을 지정하여 이 요구 사항을 충족합니다. 단일 매개 변수는 임의의 수의 매개 변수 집합에 속할 수 있습니다. 매개 변수 집합에 대한 자세한 내용은 Cmdlet 매개 변수 집합을 참조하세요.

매개 변수 집합을 지정할 때 집합에서 하나의 매개 변수만 ValueFromPipeline으로 설정합니다. 매개 변수 특성을 선언하는 방법에 대한 자세한 내용은 ParameterAttribute 선언을 참조하세요.

매개 변수 집합을 사용하는 경우 기본 매개 변수 집합은 Cmdlet 특성에 의해 정의됩니다. 기본 매개 변수 집합에는 대화형 Windows PowerShell 세션에서 사용할 가능성이 가장 큰 매개 변수가 포함되어야 합니다. Cmdlet 특성을 선언하는 방법에 대한 자세한 내용은 CmdletAttribute 선언을 참조하세요.

사용자에게 피드백 제공(SD04)

이 섹션의 지침을 사용하여 사용자에게 피드백을 제공합니다. 이 피드백을 통해 사용자는 시스템에서 발생하는 일을 인식하고 더 나은 관리 결정을 내릴 수 있습니다.

Windows PowerShell 런타임을 사용하면 사용자가 기본 설정 변수를 설정하여 Write 메서드에 대한 각 호출의 출력을 처리하는 방법을 지정할 수 있습니다. 사용자는 시스템에서 정보를 표시해야 하는지 여부를 결정하는 변수와 추가 작업을 수행하기 전에 시스템에서 사용자를 쿼리해야 하는지 여부를 결정하는 변수를 포함하여 여러 기본 설정 변수를 설정할 수 있습니다.

WriteWarning, WriteVerbose 및 WriteDebug 메서드 지원

cmdlet이 의도하지 않은 결과가 있을 수 있는 작업을 수행하려고 할 때 cmdlet은 System.Management.Automation.Cmdlet.WriteWarning 메서드를 호출해야 합니다. 예를 들어 cmdlet이 읽기 전용 파일을 덮어쓰려는 경우 이 메서드를 호출해야 합니다.

cmdlet은 사용자가 cmdlet이 수행하는 작업에 대한 세부 정보가 필요할 때 System.Management.Automation.Cmdlet.WriteVerbose 메서드를 호출해야 합니다. 예를 들어 cmdlet 작성자가 cmdlet이 수행하는 작업에 대한 자세한 정보가 필요할 수 있는 시나리오가 있다고 생각되면 cmdlet에서 이 정보를 호출해야 합니다.

개발자 또는 제품 지원 엔지니어가 cmdlet 작업이 손상된 내용을 이해해야 하는 경우 cmdlet은 System.Management.Automation.Cmdlet.WriteDebug 메서드를 호출해야 합니다. 매개 변수가 두 정보 집합을 모두 표시하기 때문에 System.Management.Automation.Cmdlet.WriteDebug 메서드를 호출하는 동일한 코드에서 System.Management.Automation.Cmdlet.WriteVerbose 메서드를 호출할 필요는 없습니다.

시간이 오래 걸리는 작업에 대한 WriteProgress 지원

완료하는 데 시간이 오래 걸리고 백그라운드에서 실행할 수 없는 Cmdlet 작업은 System.Management.Automation.Cmdlet.WriteProgress 메서드에 대한 정기적인 호출을 통해 진행률 보고를 지원해야 합니다.

호스트 인터페이스 사용

경우에 따라 cmdlet은 System.Management.Automation.Cmdlet 클래스에서 지원하는 다양한 Write 또는 Should 메서드를 사용하는 대신 사용자와 직접 통신해야 합니다. 이 경우 cmdlet은 System.Management.Automation.PSCmdlet 클래스에서 파생되고 System.Management.Automation.PSCmdlet.Host* 속성을 사용해야 합니다. 이 속성은 PromptForChoice, 프롬프트 및 WriteLine/ReadLine 형식을 포함하여 다양한 수준의 통신 유형을 지원합니다. 가장 구체적인 수준에서 개별 키를 읽고 쓰고 버퍼를 처리하는 방법도 제공합니다.

cmdlet이 GUI(그래픽 사용자 인터페이스)를 생성하도록 특별히 설계되지 않은 경우 System.Management.Automation.PSCmdlet.Host* 속성을 사용하여 호스트를 바이패스해서는 안 됩니다. GUI를 생성하도록 설계된 cmdlet의 예로는 Out-GridView cmdlet이 있습니다.

메모

Cmdlet은 System.Console API를 사용하면 안 됩니다.

Cmdlet 도움말 파일 만들기(SD05)

각 cmdlet 어셈블리에 대해 cmdlet에 대한 정보가 포함된 Help.xml 파일을 만듭니다. 이 정보에는 cmdlet에 대한 설명, cmdlet의 매개 변수에 대한 설명, cmdlet 사용 예제 등이 포함됩니다.

코드 지침

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

코딩 매개 변수(SC01)

매개 변수 특성으로 데코레이팅된 cmdlet 클래스의 public 속성을 선언하여 매개 변수 를 정의합니다. 매개 변수는 cmdlet에 대한 파생 .NET Framework 클래스의 정적 멤버일 필요는 없습니다. 매개 변수 특성을 선언하는 방법에 대한 자세한 내용은 매개 변수 특성 선언을 참조하세요.

Windows PowerShell 경로 지원

Windows PowerShell 경로는 네임스페이스에 대한 액세스를 정규화하는 메커니즘입니다. cmdlet의 매개 변수에 Windows PowerShell 경로를 할당하면 사용자는 특정 경로에 대한 바로 가기 역할을 하는 사용자 지정 "드라이브"를 정의할 수 있습니다. 사용자가 이러한 드라이브를 지정할 때 레지스트리의 데이터와 같은 저장된 데이터를 일관된 방식으로 사용할 수 있습니다.

cmdlet에서 사용자가 파일 또는 데이터 원본을 지정할 수 있도록 허용하는 경우 System.String 형식의 매개 변수를 정의해야 합니다. 둘 이상의 드라이브가 지원되는 경우 형식은 배열이어야 합니다. 매개 변수의 이름은 Path이며, 별칭은 PSPath입니다. 또한 매개 변수는 Path 와일드카드 문자를 지원해야 합니다. 와일드카드 문자에 대한 지원이 필요하지 않은 경우 매개 변수를 정의합니다 LiteralPath .

cmdlet이 읽거나 쓰는 데이터가 파일이어야 하는 경우 cmdlet은 Windows PowerShell 경로 입력을 허용해야 하며, cmdlet은 System.Management.Automation.SessionState.Path 속성을 사용하여 Windows PowerShell 경로를 파일 시스템에서 인식하는 경로로 변환해야 합니다. 특정 메커니즘에는 다음 메서드가 포함됩니다.

cmdlet이 읽거나 쓰는 데이터가 파일 대신 문자열 집합일 경우 cmdlet은 공급자 콘텐츠 정보(Content 멤버)를 사용하여 읽고 씁니다. 이 정보는 System.Management.Automation.Provider.CmdletProvider.InvokeProvider 속성에서 가져옵니다. 이러한 메커니즘을 사용하면 다른 데이터 저장소가 데이터 읽기 및 쓰기에 참여할 수 있습니다.

와일드카드 문자 지원

가능하면 cmdlet에서 와일드카드 문자를 지원해야 합니다. 와일드카드 문자에 대한 지원은 cmdlet의 여러 위치에서 발생합니다(특히 매개 변수가 개체 집합에서 하나의 개체를 식별하기 위해 문자열을 사용하는 경우). 예를 들어 Stop-Proc의 샘플 cmdlet은 프로세스 이름을 나타내는 문자열을 처리하는 매개 변수를 정의 Name 합니다. 이 매개 변수는 사용자가 중지할 프로세스를 쉽게 지정할 수 있도록 와일드카드 문자를 지원합니다.

와일드카드 문자를 지원할 수 있는 경우 cmdlet 작업은 일반적으로 배열을 생성합니다. 경우에 따라 사용자가 한 번에 하나의 항목만 사용할 수 있으므로 배열을 지원하는 것은 의미가 없습니다. 예를 들어 Set-Location cmdlet은 사용자가 단일 위치만 설정하므로 배열을 지원할 필요가 없습니다. 이 경우 cmdlet은 와일드카드 문자를 계속 지원하지만 단일 위치에 대한 해상도를 강제로 적용합니다.

와일드카드 문자 패턴에 대한 자세한 내용은 Cmdlet 매개 변수에서 와일드카드 문자 지원을 참조하세요.

개체 정의

이 섹션에는 cmdlet에 대한 개체를 정의하고 기존 개체를 확장하기 위한 지침이 포함되어 있습니다.

표준 멤버 정의

표준 멤버를 정의하여 사용자 지정 Types.ps1xml 파일에서 개체 형식을 확장합니다(Windows PowerShell Types.ps1xml 파일을 템플릿으로 사용). 표준 멤버는 PSStandardMembers라는 이름의 노드에 의해 정의됩니다. 이러한 정의를 사용하면 다른 cmdlet 및 Windows PowerShell 런타임이 일관된 방식으로 개체와 함께 작동할 수 있습니다.

매개 변수로 사용할 ObjectMembers 정의

cmdlet에 대한 개체를 디자인하는 경우 해당 멤버가 cmdlet을 사용할 cmdlet의 매개 변수에 직접 매핑되는지 확인합니다. 이 매핑을 사용하면 개체를 파이프라인으로 쉽게 보내고 한 cmdlet에서 다른 cmdlet으로 전달할 수 있습니다.

cmdlet에서 반환되는 기존 .NET Framework 개체에는 스크립트 개발자 또는 사용자가 필요로 하는 중요하거나 편리한 멤버가 누락되는 경우가 많습니다. 이러한 누락된 멤버는 개체를 파이프라인에 올바르게 전달할 수 있도록 표시 및 올바른 멤버 이름을 만드는 데 특히 중요할 수 있습니다. 이러한 필수 멤버를 문서화하는 사용자 지정 Types.ps1xml 파일을 만듭니다. 이 파일을 만들 때는 Your_Product_Name 명명 규칙을 <>사용하는 것이 좋습니다. Types.ps1xml.

예를 들어 Mode 형식에 스크립트 속성을 추가하여 파일의 특성을 보다 명확하게 표시할 수 있습니다. 또한 Count 형식에 별칭 속성을 추가하여 해당 속성 이름(대신Length)을 일관되게 사용할 수 있습니다.

IComparable 인터페이스 구현

모든 출력 개체에 System.IComparable 인터페이스를 구현합니다. 이렇게 하면 출력 개체를 다양한 정렬 및 분석 cmdlet에 쉽게 파이프할 수 있습니다.

표시 정보 업데이트

개체에 대한 디스플레이가 예상 결과를 제공하지 않는 경우 사용자 지정 <YourProductName을 만듭니다>. 해당 개체에 대한 Format.ps1xml 파일입니다.

잘 정의된 파이프라인 입력(SC02) 지원

파이프라인의 중간에 대한 구현

파이프라인의 중간에서 호출된다는 가정으로 cmdlet을 구현합니다(즉, 다른 cmdlet은 입력을 생성하거나 출력을 사용합니다). 예를 들어 cmdlet은 Get-Process 데이터를 생성하기 때문에 파이프라인의 첫 번째 cmdlet으로만 사용된다고 가정할 수 있습니다. 그러나 이 cmdlet은 파이프라인의 중간을 위해 설계되었기 때문에 이 cmdlet을 사용하면 파이프라인의 이전 cmdlet 또는 데이터가 검색할 프로세스를 지정할 수 있습니다.

파이프라인에서 입력 수용 지원

cmdlet에 대해 설정된 각 매개 변수에 파이프라인의 입력을 지원하는 매개 변수를 하나 이상 포함합니다. 파이프라인 입력을 지원하면 사용자가 데이터 또는 개체를 검색하고, 올바른 매개 변수 집합으로 보내고, 결과를 cmdlet에 직접 전달할 수 있습니다.

매개 변수 특성에 키워드, 키워드 특성, 또는 선언에 두 키워드가 모두 포함된 경우, 매개 변수는 파이프라인의 입력을 허용합니다. 매개 변수 집합의 매개 변수가 ValueFromPipeline 또는 ValueFromPipelineByPropertyName 키워드를 지원하지 않는 경우, cmdlet은 파이프라인 입력을 무시하므로 다른 cmdlet 뒤에 의미 있게 배치될 수 없습니다.

ProcessRecord 메서드 지원

파이프라인에서 이전 cmdlet의 모든 레코드를 허용하려면 cmdlet이 System.Management.Automation.Cmdlet.ProcessRecord 메서드를 구현해야 합니다. Windows PowerShell은 cmdlet으로 전송되는 모든 레코드에 대해 한 번씩 이 메서드를 여러 번 호출합니다.

파이프라인에 단일 레코드 쓰기(SC03)

cmdlet이 개체를 반환할 때 cmdlet은 생성되는 즉시 개체를 작성해야 합니다. cmdlet은 항목을 결합된 배열로 버퍼링하기 위해 보유해서는 안 됩니다. 그러면 개체를 입력으로 수신하는 cmdlet은 지연 없이 출력 개체를 처리, 표시 또는 처리하고 표시할 수 있습니다. 출력 개체를 한 번에 하나씩 생성하는 cmdlet은 System.Management.Automation.Cmdlet.WriteObject 메서드를 호출해야 합니다. 출력 개체를 일괄 처리로 생성하는 cmdlet(예: 기본 API가 출력 개체의 배열을 반환하기 때문에)은 두 번째 매개 변수가 설정된 System.Management.Automation.Cmdlet.WriteObject 메서드를 true호출해야 합니다.

cmdlet을 대소문자 구별 없이 처리하고 원래 대소문자를 유지하도록 만들기(SC04)

기본적으로 Windows PowerShell 자체는 대/소문자를 구분하지 않습니다. 그러나 많은 기존 시스템을 다루기 때문에 Windows PowerShell은 운영 및 호환성을 위해 사례를 유지합니다. 즉, 문자가 대문자로 제공된 경우 Windows PowerShell은 대문자로 유지합니다. 시스템이 제대로 작동하려면 cmdlet이 이 규칙을 따라야 합니다. 가능하면 대/소문자를 구분하지 않는 방식으로 작동해야 합니다. 그러나 나중에 명령 또는 파이프라인에서 발생하는 cmdlet에 대한 원래 사례를 유지해야 합니다.

또한 참조하십시오

필수 개발 지침

권고 개발 지침

Windows PowerShell Cmdlet 작성

  • Last updated on