about_Functions_CmdletBindingAttribute

about_Functions_CmdletBindingAttribute (CmdletBinding 특성)

함수가 컴파일된 cmdlet처럼 동작하도록 만들어 주는 CmdletBinding 특성에 대해 다뤄요. 일반 함수를 고급 함수(advanced function)로 격상시켜서, C#으로 작성된 cmdlet이 누리는 여러 기능을 그대로 쓸 수 있게 해 주는 핵심 도구예요.

출처: Microsoft Learn — about_Functions_CmdletBindingAttribute

본문

짧은 설명

함수가 컴파일된 cmdlet처럼 동작하게 만들어 주는 특성을 설명해요.

자세한 설명

CmdletBinding 특성은 함수가 C#으로 작성된 컴파일된 cmdlet처럼 동작하게 해 주는 함수용 특성이에요. 이 특성 덕분에 cmdlet이 가진 여러 기능을 함수에서도 그대로 사용할 수 있어요.

CmdletBinding 특성을 쓰면 PowerShell이 자동으로 **공통 매개 변수(Common Parameters)**를 추가해요. 그래서 공통 매개 변수와 같은 이름을 가진 매개 변수를 직접 만들 수 없어요. 자세한 내용은 about_CommonParameters를 참고하세요.

CmdletBinding 특성이 붙은 함수의 매개 변수는 컴파일된 cmdlet의 매개 변수를 바인딩하는 방식과 똑같은 방식으로 PowerShell이 바인딩해요. $PSCmdlet 자동 변수는 CmdletBinding 특성이 있는 함수에서 쓸 수 있지만, $args 변수는 쓸 수 없어요.

CmdletBinding 특성이 붙은 함수에서는, 일치하는 위치 매개 변수가 없는 알 수 없는 매개 변수나 위치 인수가 있으면 매개 변수 바인딩이 실패해요.

참고: 컴파일된 cmdlet은 이 항목에서 설명하는 CmdletBinding 특성과 비슷한 필수 Cmdlet 특성을 사용해요.

구문

다음 예시는 CmdletBinding 특성의 모든 선택 인수를 지정한 함수의 형식을 보여줘요. 각 인수에 대한 간단한 설명은 이 예시 뒤에 이어져요.

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

    param ($Parameter1)
    begin {}
    process {}
    end {}
}

CmdletBinding 특성의 불리언(Boolean) 인수들은 생략하면 기본값이 False예요. 인수 값을 $true로 설정하거나, 값을 생략하고 인수 이름만 나열해도 돼요. 예를 들어 아래 두 CmdletBinding 특성은 서로 같은 의미예요.

{
    [CmdletBinding(SupportsPaging=$true)]

    param ($Parameter1)
    begin {}
    process {}
    end {}
}

# Boolean 인자는 이렇게 축약해서 쓸 수도 있습니다

{
    [CmdletBinding(SupportsPaging)]

    param ($Parameter1)
    begin {}
    process {}
    end {}
}

ConfirmImpact (확인 영향)

ConfirmImpact 인수는 ShouldProcess 메서드를 호출해서 함수의 동작을 언제 확인받을지 지정해요. ShouldProcess 메서드 호출은 ConfirmImpact 인수의 값이 $ConfirmPreference 기본 설정 변수의 값보다 같거나 클 때만 확인 메시지를 표시해요. (인수의 기본값은 Medium이에요.) 이 인수는 SupportsShouldProcess 인수를 함께 지정할 때만 사용하세요.

확인 요청에 대한 자세한 내용은 Requesting Confirmation을 참고하세요.

DefaultParameterSetName (기본 매개 변수 집합 이름)

DefaultParameterSetName 인수는 PowerShell이 어떤 매개 변수 집합을 사용해야 할지 결정하지 못할 때 시도할 매개 변수 집합의 이름을 지정해요. 각 매개 변수 집합의 고유 매개 변수를 필수 매개 변수로 만들면 이런 문제를 피할 수 있어요.

HelpUri (도움말 URI)

HelpUri 인수는 함수를 설명하는 도움말 항목의 온라인 버전 주소를 지정해요. HelpUri 인수의 값은 반드시 "http"나 "https"로 시작해야 해요.

HelpUri 인수의 값은 Get-Command가 함수에 대해 반환하는 CommandInfo 개체의 HelpUri 속성 값을 만드는 데 사용돼요.

다만 컴퓨터에 도움말 파일이 설치되어 있고, 그 도움말 파일의 RelatedLinks 섹션에 있는 첫 번째 링크가 URI이거나 주석 기반 도움말(comment-based help)의 첫 번째 .LINK 키워드 값이 URI라면, 그 도움말 파일의 URI가 함수의 HelpUri 속성 값으로 사용돼요.

Get-Help cmdlet은 명령에서 Get-Help의 Online 매개 변수를 지정했을 때 함수 도움말 항목의 온라인 버전을 찾기 위해 HelpUri 속성 값을 사용해요.

SupportsPaging (페이징 지원)

SupportsPaging 인수는 함수에 First, Skip, IncludeTotalCount 매개 변수를 추가해요. 이 매개 변수들을 통해 사용자는 아주 큰 결과 집합에서 원하는 출력을 골라낼 수 있어요. 이 인수는 SQL 데이터베이스처럼 데이터 선택을 지원하는 큰 데이터 저장소에서 데이터를 반환하는 cmdlet과 함수를 위해 설계되었어요.

이 인수는 Windows PowerShell 3.0에서 도입되었어요.

First: 처음 'n'개의 개체만 가져와요.
Skip: 처음 'n'개의 개체를 건너뛰고 나머지 개체를 가져와요.
IncludeTotalCount: 데이터 집합의 개체 수(정수)를 먼저 보고하고, 이어서 개체들을 보고해요. cmdlet이 전체 개수를 알 수 없으면 "Unknown total count"를 반환해요.

PowerShell에는 반환할 전체 개수 값을 구하고 그 값의 정확도 추정치를 포함해 주는 도우미 메서드 NewTotalCount가 포함되어 있어요.

다음 샘플 함수는 페이징 매개 변수 지원을 고급 함수에 추가하는 방법을 보여줘요.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    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 인수는 함수의 매개 변수가 기본적으로 위치(positional) 매개 변수인지 여부를 결정해요. 기본값은 $true예요. PositionalBinding 인수에 $false를 지정하면 위치 바인딩을 끌 수 있어요.

PositionalBinding 인수는 Windows PowerShell 3.0에서 도입되었어요.

매개 변수가 위치 매개 변수일 때는 매개 변수 이름이 선택 사항이에요. PowerShell은 함수 명령에서 이름 없는 매개 변수 값들을 그 값들의 순서(position)에 따라 함수의 매개 변수와 연결해요.

매개 변수가 위치 매개 변수가 아니면(즉 "이름 지정(named) 매개 변수"라면), 명령에서 매개 변수 이름(또는 그 이름의 약어나 별칭)이 필요해요.

PositionalBinding이 $true일 때는 함수 매개 변수가 기본적으로 위치 매개 변수예요. PowerShell은 함수에 선언된 순서대로 매개 변수에 위치 번호를 할당해요.

PositionalBinding이 $false일 때는 함수 매개 변수가 기본적으로 위치 매개 변수가 아니에요. Parameter 특성의 Position 인수가 매개 변수에 선언되어 있지 않다면, 함수에서 그 매개 변수를 사용할 때 매개 변수 이름(또는 별칭이나 약어)을 반드시 포함해야 해요.

Parameter 특성의 Position 인수는 PositionalBinding 기본값보다 우선해요. Position 인수로 매개 변수의 위치 값을 지정할 수 있어요. Position 인수에 대한 자세한 내용은 about_Functions_Advanced_Parameters를 참고하세요.

참고

SupportsTransactions 인수는 고급 함수에서 지원되지 않아요.

키워드

about_Functions_CmdletBinding_Attribute

about_Functions_CmdletBindingAttribute