about_Functions_CmdletBindingAttribute

아티클
10/04/2023

간단한 설명

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

자세한 설명

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

PowerShell은 컴파일된 cmdlet의 매개 변수를 바인딩하는 것과 동일한 방식으로 특성이 있는 함수 CmdletBinding 의 매개 변수를 바인딩합니다. $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 특성에서 생략하면 CmdletBinding 특성의 부울 인수 형식이 기본적으로 False로 설정됩니다. 인수 값을 $true 이름으로 설정하거나 인수를 나열합니다. 예를 들어 다음 CmdletBinding 특성은 동일합니다.

{
    [CmdletBinding(SupportsPaging=$true)]

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

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

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

ConfirmImpact

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

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

DefaultParameterSetName

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

HelpURI

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

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

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

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

SupportsPaging

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

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

첫 번째: 첫 번째 'n' 개체만 가져옵니다.
건너뛰기: 첫 번째 'n' 개체를 무시한 다음 다시 기본 개체를 가져옵니다.
IncludeTotalCount: 데이터 집합의 개체 수(정수)와 개체를 보고합니다. cmdlet이 총 개수를 확인할 수 없으면 "알 수 없는 총 개수"를 반환합니다.

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

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

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

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

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

PositionalBinding인 경우 $False함수 매개 변수는 기본적으로 위치가 아닙니다. 매개 변수 특성의 Position 인수가 매개 변수에 선언되지 않는 한 매개 변수가 함수에 사용될 때 매개 변수 이름(또는 별칭 또는 약어)을 포함해야 합니다.

Parameter 특성의 Position 인수가 PositionalBinding 기본값보다 우선합니다. Position 인수를 사용하여 매개 변수의 위치 값을 지정할 수 있습니다. Position 인수에 대한 자세한 내용은 about_Functions_Advanced_Parameters 참조하세요.

주의

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

키워드

about_Functions_CmdletBinding_Attribute