about_Functions_CmdletBindingAttribute

아티클
11/16/2015

업데이트 날짜: 2014년 5월

적용 대상: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

항목

about_Functions_CmdletBindingAttribute

간단한 설명

함수가 컴파일된 cmdlet처럼 작동하도록 하는 특성에 대해 설명합니다.

자세한 설명

CmdletBinding 특성은 함수가 C#으로 작성된 컴파일된 cmdlet처럼 작동하도록 하는 함수의 특성이며, cmdlet의 기능에 대한 액세스를 제공합니다.

Windows PowerShell®에서는 컴파일된 cmdlet의 매개 변수를 바인딩하는 것과 같은 방식으로 CmdletBinding 특성이 있는 함수의 매개 변수를 바인딩합니다. $PSCmdlet 자동 변수는 CmdletBinding 특성이 있는 함수에서 사용할 수 있지만 $Args 변수는 사용할 수 없습니다.

CmdletBinding 특성이 있는 함수에서는 알 수 없는 매개 변수 및 일치하는 위치 매개 변수가 없는 위치 인수로 인해 매개 변수 바인딩이 실패할 수 있습니다.

참고: 컴파일된 cmdlet은 필요한 Cmdlet 특성을 사용하며, 이 특성은 이 항목에서 설명하는 CmdletBinding 특성과 유사합니다.

구문

다음 예제에서는 CmdletBinding 특성의 모든 옵션 인수를 지정하는 함수의 형식을 보여 줍니다. 이 예제 다음에서는 각 인수에 대해 간략하게 설명합니다.

        {
          [CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

          Param ($Parameter1)
          Begin{}
          Process{}
          End{}
        }

ConfirmImpact

ConfirmImpact 인수는 ShouldProcess 메서드를 호출하여 함수의 동작을 확인해야 하는 경우를 지정합니다. ShouldProcess 메서드를 호출하면 ConfirmImpact 인수가 $ConfirmPreference 기본 설정 변수 값보다 크거나 같은 경우에만 확인 프롬프트가 표시됩니다. 인수의 기본값은 Medium입니다. SupportsShouldProcess 인수도 지정된 경우에만 이 인수를 지정합니다.

확인 요청에 대한 자세한 내용은 MSDN(Microsoft Developer Network) 라이브러리의 "확인 요청"(https://go.microsoft.com/fwlink/?LinkId=136658)(영문)을 참조하세요.

DefaultParameterSetName

DefaultParameterSetName 인수는 사용할 매개 변수 집합을 확인할 수 없는 경우 Windows PowerShell에서 사용하려고 시도하는 매개 변수 집합의 이름을 지정합니다. 각 매개 변수 집합의 고유한 매개 변수를 필수 매개 변수로 설정하면 이 문제를 방지할 수 있습니다.

HelpURI

HelpURI 인수는 함수에 대해 설명하는 온라인 버전 도움말 항목의 인터넷 주소(URI: Uniform Resource Identifier)를 지정합니다. HelpURI 인수의 값은 "http" 또는 "https"로 시작해야 합니다.

HelpURI 인수 값은 Get-Command에서 함수에 대해 반환하는 CommandInfo 개체의 HelpURI 속성 값에 사용됩니다.

그러나 도움말 파일이 컴퓨터에 설치되어 있고 도움말 파일의 RelatedLinks 섹션에서 첫 번째 링크의 값이 URI이거나 주석 기반 도움말에서 첫 번째 .Link 지시문의 값이 URI인 경우 도움말 파일의 URI는 함수의 HelpUri 속성 값으로 사용됩니다.

Get-Help의 Online 매개 변수가 명령에 지정된 경우 Get-Help cmdlet은 HelpURI 속성의 값을 사용하여 함수 도움말 항목의 온라인 버전을 찾습니다.

SupportsPaging

SupportsPaging 인수는 함수에 First, Skip 및 IncludeTotalCount 매개 변수를 추가합니다. 이러한 매개 변수를 사용하여 사용자는 매우 큰 결과 집합에서 출력을 선택할 수 있습니다. 이 인수는 SQL 데이터베이스와 같이 데이터 선택을 지원하는 큰 데이터 저장소에서 데이터를 반환하는 cmdlet 및 함수용으로 설계되었습니다.

이 인수는 Windows PowerShell 3.0에서 도입되었습니다.

First:

처음 'n'개 개체만 가져옵니다.

Skip:

처음 'n'개 개체를 무시하고 나머지 개체를 가져옵니다.

IncludeTotalCount:

데이터 집합의 개체 수(정수)를 보고한 후 개체를 보고합니다. cmdlet에서 총 개수를 확인할 수 없는 경우 "알 수 없는 총 개수"라고 반환합니다.

Windows PowerShell에는 반환할 총 개수 값을 가져오는 도우미 메서드인 NewTotalCount가 포함되어 있고 총 개수 값의 예상 정확도가 포함되어 있습니다.

다음 샘플 함수에서는 페이징 매개 변수에 대한 지원을 고급 함수에 추가하는 방법을 보여 줍니다.

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             param()

             $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
             $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100)

             if ($PSCmdlet.PagingParameters.IncludeTotalCount)
             {
                 $TotalCountAccuracy = 1.0
                 $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy)
                 Write-Output $TotalCount
             }
             $FirstNumber .. $LastNumber | Write-Output
         }

SupportsShouldProcess

SupportsShouldProcess 인수는 Confirm 및 WhatIf 매개 변수를 함수에 추가합니다. Confirm 매개 변수는 파이프라인의 각 개체에서 명령을 실행하기 전에 사용자에게 메시지를 표시합니다. WhatIf 매개 변수는 명령을 실행하는 대신 명령에서 변경하는 내용을 나열합니다.

PositionalBinding

PositionalBinding 인수는 기본적으로 함수의 매개 변수가 위치 매개 변수인지 여부를 결정합니다. 기본값은 $True입니다. 값이 $False인 PositionalBinding 인수를 사용하여 위치 바인딩을 사용하지 않도록 설정할 수 있습니다.

PositionalBinding 인수는 Windows PowerShell3.0에서 도입되었습니다.

매개 변수가 위치 매개 변수인 경우 매개 변수 이름은 선택 사항입니다. Windows PowerShell은 함수 명령에서 명명되지 않은 매개 변수 값의 순서 또는 위치에 따라 명명되지 않은 매개 변수 값을 함수 매개 변수에 연결합니다.

매개 변수가 위치 매개 변수가 아니고 "명명된" 경우에는 매개 변수 이름(또는 이름의 약어나 별칭)이 명령에 필요합니다.

PositionalBinding이 $True인 경우 함수 매개 변수는 기본적으로 위치 매개 변수입니다. Windows PowerShell은 함수에서 매개 변수가 선언되는 순서대로 매개 변수에 위치 번호를 할당합니다.

PositionalBinding이 $False인 경우 함수 매개 변수는 기분적으로 위치 매개 변수가 아닙니다. Parameter 특성의 Position 인수가 매개 변수에 선언된 경우에는 함수에서 매개 변수를 사용할 때 매개 변수 이름(또는 별칭이나 약어)을 포함해야 합니다.

Parameter 특성의 Position 인수는 PositionalBinding 기본값보다 우선합니다. Position 인수를 사용하여 매개 변수의 위치 값을 지정할 수 있습니다. Position 인수에 대한 자세한 내용은 about_Functions_Advanced_Parameters(https://go.microsoft.com/fwlink/?LinkID=135173)를 참조하세요.

참고

SupportsTransactions 인수는 고급 함수에서 지원되지 않습니다.

키워드

about_Functions_CmdletBinding_Attribute

참고 항목

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute

about_Functions_CmdletBindingAttribute

항목

간단한 설명

자세한 설명

참고

키워드

참고 항목

추가 리소스