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 블록을 정의하는 경우 모든 코드를 명명된 블록에 배치해야 합니다.

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

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

메모

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

`begin`

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

`process`

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

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

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

중요하다

함수 매개 변수가 파이프라인 입력을 허용하도록 설정되어 있고 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 블록과 의미상 유사합니다. 리소스 정리는 다음 시나리오에 적용됩니다.

파이프라인 실행이 종료 오류 없이 정상적으로 완료되는 경우
종료 오류로 인해 파이프라인 실행이 중단된 경우
파이프라인이 Select-Object -First 의해 중지되는 경우
Ctrl+c 파이프라인이 중지되는 경우

클린 블록은 성공 스트림에 기록된 모든 출력을 삭제합니다.

주의

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

확인 방법

ShouldProcess

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

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

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

ShouldContinue

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

오류 메서드

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

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

쓰기 메서드

함수는 다음 메서드를 호출하여 다양한 형식의 출력을 반환할 수 있습니다. 모든 출력이 파이프라인의 다음 명령으로 이동하지는 않습니다. Write같은 다양한 Write-Error 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 변수를 구성하거나 Verbose 및 Debug 명령줄 옵션을 사용하여 경고 메시지를 표시할 수도 있습니다. $WarningPreference 변수에 대한 자세한 내용은 about_Preference_Variables참조하세요.

기타 메서드 및 속성

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

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

참고하십시오

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-18