about_Functions_Advanced_Methods

  • 아티클

간단한 설명

특성을 지정 CmdletBinding 하는 함수가 컴파일된 cmdlet에 사용할 수 있는 메서드와 속성을 사용하는 방법을 설명합니다.

자세한 설명

특성을 지정하는 함수는 변수를 CmdletBinding 통해 추가 메서드 및 속성에 $PSCmdlet 액세스할 수 있습니다. 이러한 메서드에는 다음 메서드가 포함됩니다.

  • 모든 함수에서 사용할 수 있는 동일한 입력 처리 메서드입니다.
  • ShouldProcess 작업을 수행하기 전에 사용자 피드백을 가져오는 데 사용되는 메서드 및 ShouldContinue 메서드입니다.
  • ThrowTerminatingError 오류 레코드를 생성하는 메서드입니다.
  • 다양한 형식의 출력을 반환하는 여러 Write 메서드입니다.

PSCmdlet 클래스의 모든 메서드와 속성을 고급 함수에서 사용할 수 있습니다. 자세한 내용은 System.Management.Automation.PSCmdlet을 참조하세요.

특성에 대한 CmdletBinding 자세한 내용은 about_Functions_CmdletBindingAttribute 참조하세요. CmdletBindingAttribute 클래스는 System.Management.Automation.Cmdlet.CmdletBindingAttribute를 참조하세요.

입력 처리 방법

이 섹션에서 설명하는 메서드를 입력 처리 메서드라고 합니다. 함수의 경우 이러한 세 가지 메서드는 함수의 begin블록 process및 end 블록으로 표시됩니다. PowerShell 7.3은 블록 프로세스 메서드를 clean 추가합니다.

함수에서 이러한 블록을 사용할 필요는 없습니다. 명명된 블록을 사용하지 않는 경우 PowerShell은 함수 블록에 end 코드를 넣습니다. 그러나 이러한 명명된 블록을 사용하거나 블록을 정의하는 dynamicparam 경우 모든 코드를 명명된 블록에 배치해야 합니다.

다음 예제에서는 일회성 전처리용 블록, process 여러 레코드 처리를 위한 블록 및 일회성 후처리를 위한 블록을 포함하는 begin 함수의 end 개요를 보여 줍니다.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

참고 항목

이러한 블록은 특성을 사용하는 함수뿐만 아니라 모든 함수에 CmdletBinding 적용됩니다.

begin

이 블록은 함수에 대한 선택적 일회성 전처리를 제공하는 데 사용됩니다. PowerShell 런타임은 파이프라인에 있는 함수의 각 인스턴스에 대해 이 블록의 코드를 한 번 사용합니다.

process

이 블록은 함수에 대한 레코드별 처리를 제공하는 데 사용됩니다. 다른 블록을 정의하지 않고 블록을 사용할 process 수 있습니다. 블록 실행 수는 process 함수를 사용하는 방법과 함수가 수신하는 입력에 따라 달라집니다.

자동 변수 $_ 이거나 $PSItem 블록에서 사용할 파이프라인의 현재 개체를 process 포함합니다. 자동 변수에는 $input 함수 및 스크립트 블록에만 사용할 수 있는 열거자가 포함됩니다. 자세한 내용은 about_Automatic_Variables를 참조하세요.

  • 파이프라인의 시작 또는 외부에서 함수를 호출하면 블록이 process 한 번 실행됩니다.
  • 파이프라인 내에서 블록은 process 함수에 도달하는 각 입력 개체에 대해 한 번 실행됩니다.
  • 함수에 도달하는 파이프라인 입력이 비어 있으면 블록이 process 실행되지 않습니다.
    • , end및 clean 블록은 begin계속 실행됩니다.

Important

함수 매개 변수가 파이프라인 입력을 허용하도록 설정되어 있고 process 블록이 정의되지 않은 경우 레코드별 처리가 실패합니다. 이 경우 함수는 입력에 관계없이 한 번만 실행됩니다.

파이프라인 입력을 허용하고 사용하는 CmdletBinding함수를 만들 때 블록은 process 파이프라인 입력에 대해 정의한 매개 변수 변수를 $_ 사용하거나 $PSItem대신 사용해야 합니다. 예시:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1,2,3,4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

이 블록은 함수에 대한 선택적 일회성 후 처리를 제공하는 데 사용됩니다.

clean

블록이 clean PowerShell 7.3에 추가되었습니다.

clean 블록은 사용자가 begin, process 및 end 블록에 걸쳐 있는 리소스를 정리할 수 있는 편리한 방법입니다. 스크립트 함수 또는 스크립트 cmdlet의 다른 모든 명명된 블록을 포함하는 finally 블록과 의미상 유사합니다. 리소스 정리는 다음과 같은 시나리오에 적용됩니다.

  1. 종료 오류 없이 파이프라인 실행이 정상적으로 완료되는 경우
  2. 종료 오류로 인해 파이프라인 실행이 중단되는 경우
  3. Select-Object -First로 인해 파이프라인이 중단되는 경우
  4. Ctrl+c 또는 StopProcessing()으로 인해 파이프라인이 중지되는 경우

주의

clean 블록을 추가하는 것은 호환성이 손상되는 변경입니다. clean은 키워드로 구문 분석되므로 사용자가 스크립트 블록의 첫 번째 문으로 clean이라는 명령을 직접 호출할 수 없습니다. 그러나 문제가 될 가능성이 없습니다. 호출 연산자(& clean)를 사용하여 명령을 계속 호출할 수 있습니다.

확인 방법

ShouldProcess

이 메서드는 함수가 시스템을 변경하는 작업을 수행하기 전에 사용자에게 확인을 요청하기 위해 호출됩니다. 함수는 메서드에서 반환된 부울 값을 기반으로 계속할 수 있습니다. 이 메서드는 함수 블록 내에서 Process{} 만 호출할 수 있습니다. 또한 이 특성은 CmdletBinding 이전 예제와 같이 함수가 지원 ShouldProcess 한다고 선언해야 합니다.

이 메서드 에 대한 자세한 내용은 System.Management.Automation.Cmdlet.ShouldProcess를 참조하세요.

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

ShouldContinue

이 메서드는 두 번째 확인 메시지를 요청하기 위해 호출됩니다. 메서드가 반환$true될 때 ShouldProcess 호출해야 합니다. 이 메서드에 대한 자세한 내용은 System.Management.Automation.Cmdlet.ShouldContinue를 참조하세요.

오류 메서드

오류가 발생할 때 함수는 두 가지 메서드를 호출할 수 있습니다. 종료되지 않는 오류가 발생하면 함수는 메서드 섹션에 WriteError 설명된 메서드를 Write 호출해야 합니다. 종료 오류가 발생하고 함수를 계속할 수 없는 경우 메서드를 ThrowTerminatingError 호출해야 합니다. 종료 오류에 Throw 문을 사용하고 종료하지 않는 오류에 대해 Write-Error cmdlet을 사용할 수도 있습니다.

자세한 내용은 System.Management.Automation.Cmdlet.ThrowTerminatingError를 참조하세요.

쓰기 메서드

함수는 다음 메서드를 호출하여 다양한 형식의 출력을 반환할 수 있습니다. 모든 출력이 파이프라인의 다음 명령으로 이동하지는 않습니다. 와 같은 Write-Error다양한 Write cmdlet을 사용할 수도 있습니다.

WriteCommandDetail

메서드에 WriteCommandDetails 대한 자세한 내용은 System.Management.Automation.Cmdlet.WriteCommandDetail을 참조하세요.

WriteDebug

함수 문제를 해결하는 데 사용할 수 있는 정보를 제공하려면 함수가 메서드를 WriteDebug 호출하도록 합니다. 메서드는 WriteDebug 사용자에게 디버그 메시지를 표시합니다. 자세한 내용은 System.Management.Automation.Cmdlet.WriteDebug를 참조하세요.

WriteError

함수는 종료되지 않는 오류가 발생하고 함수가 레코드 처리를 계속하도록 설계된 경우 이 메서드를 호출해야 합니다. 자세한 내용은 System.Management.Automation.Cmdlet.WriteError를 참조하세요.

참고 항목

종료 오류가 발생하면 함수는 ThrowTerminatingError 메서드를 호출해야 합니다.

WriteObject

이 WriteObject 메서드를 사용하면 함수가 파이프라인의 다음 명령에 개체를 보낼 수 있습니다. 대부분의 경우 WriteObject 함수가 데이터를 반환할 때 사용할 메서드입니다. 자세한 내용은 System.Management.Automation.PSCmdlet.WriteObject를 참조하세요.

WriteProgress

완료하는 데 시간이 오래 걸리는 함수의 경우 이 메서드를 사용하면 진행률 정보가 표시되도록 함수가 메서드를 호출 WriteProgress 할 수 있습니다. 예를 들어 완료 비율을 표시할 수 있습니다. 자세한 내용은 System.Management.Automation.PSCmdlet.WriteProgress를 참조하세요.

WriteVerbose

함수가 수행하는 일에 대한 자세한 정보를 제공하려면 함수가 메서드를 호출 WriteVerbose 하여 사용자에게 자세한 메시지를 표시하도록 합니다. 기본적으로 자세한 내용은 표시되지 않습니다. 자세한 내용은 System.Management.Automation.PSCmdlet.WriteVerbose를 참조하세요.

WriteWarning

예기치 않은 결과가 발생할 수 있는 조건에 대한 정보를 제공하려면 함수가 WriteWarning 메서드를 호출하여 사용자에게 경고 메시지를 표시하도록 합니다. 기본적으로 경고 메시지가 표시됩니다. 자세한 내용은 System.Management.Automation.PSCmdlet.WriteWarning을 참조하세요.

참고 항목

변수를 구성 $WarningPreference 하거나 명령줄 옵션을 사용하여 경고 메시지를 표시할 VerboseDebug 수도 있습니다. 변수에 대한 $WarningPreference 자세한 내용은 about_Preference_Variables 참조하세요.

기타 메서드 및 속성

변수를 통해 $PSCmdlet 액세스할 수 있는 다른 메서드 및 속성에 대한 자세한 내용은 System.Management.Automation.PSCmdlet을 참조하세요.

예를 들어 ParameterSetName 속성을 사용하면 사용 중인 매개 변수 집합을 볼 수 있습니다. 매개 변수 집합을 사용하면 함수가 실행될 때 지정된 매개 변수에 따라 다른 작업을 수행하는 함수를 만들 수 있습니다.

참고 항목