다음을 통해 공유

about_Functions

  • 아티클

간단한 설명

PowerShell에서 함수를 만들고 사용하는 방법을 설명합니다.

자세한 설명

함수는 할당한 이름을 가진 PowerShell 문의 목록입니다. 함수를 실행할 때 함수 이름을 입력합니다. 목록의 문은 명령 프롬프트에서 입력한 것처럼 실행됩니다.

함수는 다음과 같이 간단할 수 있습니다.

function Get-PowerShellProcess { Get-Process pwsh }

함수가 정의되면 기본 제공 cmdlet처럼 사용할 수 있습니다. 예를 들어 새로 정의된 Get-PowerShellProcess 함수를 호출하려면 다음을 수행합니다.

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

함수는 cmdlet 또는 애플리케이션만큼 복잡할 수도 있습니다.

cmdlet과 마찬가지로 함수에는 매개 변수가 있을 수 있습니다. 매개 변수는 이름, 위치, 스위치 또는 동적 매개 변수일 수 있습니다. 함수 매개 변수는 명령줄 또는 파이프라인에서 읽을 수 있습니다.

함수는 표시하거나, 변수에 할당하거나, 다른 함수 또는 cmdlet에 전달할 수 있는 값을 반환할 수 있습니다. 키워드를 사용하여 return 반환 값을 지정할 수도 있습니다. 키워드는 return 함수에서 반환된 다른 출력에 영향을 주거나 표시하지 않습니다. 그러나 키워드는 return 해당 줄에서 함수를 종료합니다. 자세한 내용은 about_Return 참조하세요.

함수의 문 목록에는 키워드begin, processend및 clean. 이러한 문은 파이프라인의 입력을 다르게 처리합니다.

필터 키워드는 파이프라인의 각 개체에서 실행되는 함수 형식을 만드는 데 사용됩니다. 필터는 블록에 모든 문이 있는 process 함수와 유사합니다.

함수는 cmdlet처럼 작동할 수도 있습니다. 프로그래밍을 사용하지 C# 않고 cmdlet처럼 작동하는 함수를 만들 수 있습니다. 자세한 내용은 about_Functions_Advanced 참조하세요.

Important

스크립트 파일 및 스크립트 기반 모듈 내에서 함수를 호출하려면 먼저 정의해야 합니다.

구문

함수의 구문은 다음과 같습니다.

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

함수에는 다음 항목이 포함됩니다.

  • function 키워드
  • 범위(선택 사항)
  • 선택한 이름
  • 임의 개수의 명명된 매개 변수(선택 사항)
  • 중괄호로 묶인 하나 이상의 PowerShell 명령 {}

함수의 dynamicparam 키워드 및 동적 매개 변수에 대한 자세한 내용은 about_Functions_Advanced_Parameters 참조하세요.

입력 처리 방법

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

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

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

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

begin

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

process

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

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

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

Important

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

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)를 사용하여 명령을 계속 호출할 수 있습니다.

단순 함수

함수가 유용하기 위해 복잡할 필요는 없습니다. 가장 간단한 함수의 형식은 다음과 같습니다.

function <function-name> {statements}

예를 들어 다음 함수는 관리자 권한으로 실행 옵션을 사용하여 PowerShell을 시작합니다.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

함수를 사용하려면 다음을 입력합니다. Start-PSAdmin

함수에 문을 추가하려면 각 문을 별도의 줄에 입력하거나 세미콜론 ; 을 사용하여 문을 구분합니다.

예를 들어 다음 함수는 시작 날짜 이후에 변경된 현재 사용자의 디렉터리에서 모든 .jpg 파일을 찾습니다.

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

유용한 작은 함수의 도구 상자를 만들 수 있습니다. 이 항목의 뒷부분에서 about_Profiles 설명한 대로 이러한 함수를 PowerShell 프로필에 추가합니다.

함수 이름

함수에 이름을 할당할 수 있지만 다른 사용자와 공유하는 함수는 모든 PowerShell 명령에 대해 설정된 명명 규칙을 따라야 합니다.

함수 이름은 동사가 함수가 수행하는 작업을 식별하고 명사는 cmdlet이 해당 작업을 수행하는 항목을 식별하는 동사-명사 쌍으로 구성되어야 합니다.

함수는 모든 PowerShell 명령에 대해 승인된 표준 동사를 사용해야 합니다. 이러한 동사는 명령 이름을 일관되고 사용자가 쉽게 이해할 수 있도록 유지하는 데 도움이 될 수 있습니다.

표준 PowerShell 동사에 대한 자세한 내용은 승인된 동사를 참조 하세요.

매개 변수가 있는 함수

명명된 매개 변수, 위치 매개 변수, 스위치 매개 변수 및 동적 매개 변수를 비롯한 함수와 함께 매개 변수를 사용할 수 있습니다. 함수의 동적 매개 변수에 대한 자세한 내용은 about_Functions_Advanced_Parameters 참조하세요.

명명된 매개 변수

명명된 매개 변수 수를 정의할 수 있습니다. 이 항목의 뒷부분에서 설명한 대로 명명된 매개 변수의 기본값을 포함할 수 있습니다.

다음 샘플 구문과 같이 키워드를 param 사용하여 중괄호 안에 매개 변수를 정의할 수 있습니다.

function <name> {
  param ([type]$parameter1 [,[type]$parameter2])
  <statement list>
}

다음 샘플 구문과 같이 키워드 없이 Param 중괄호 외부에서 매개 변수를 정의할 수도 있습니다.

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

다음은 이 대체 구문의 예입니다.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

첫 번째 메서드가 선호되지만 이러한 두 메서드 사이에는 차이가 없습니다.

함수를 실행하면 매개 변수에 제공하는 값이 매개 변수 이름을 포함하는 변수에 할당됩니다. 해당 변수의 값은 함수에서 사용할 수 있습니다.

다음 예제는 .라는 Get-SmallFiles함수입니다. 이 함수에는 매개 변수가 있습니다 $Size . 이 함수는 매개 변수 값 $Size 보다 작은 모든 파일을 표시하고 디렉터리를 제외합니다.

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

함수에서 매개 변수에 $Size 대해 정의된 이름인 변수를 사용할 수 있습니다.

이 함수를 사용하려면 다음 명령을 입력합니다.

Get-SmallFiles -Size 50

매개 변수 이름 없이 명명된 매개 변수의 값을 입력할 수도 있습니다. 예를 들어 다음 명령은 Size 매개 변수의 이름을 지정하는 명령과 동일한 결과를 제공합니다.

Get-SmallFiles 50

매개 변수의 기본값을 정의하려면 예제의 다음 변형 Get-SmallFiles 과 같이 매개 변수 이름 다음에 등호와 값을 입력합니다.

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

값 없이 입력 Get-SmallFiles 하는 경우 함수는 100을 $size할당합니다. 값을 제공하는 경우 함수는 해당 값을 사용합니다.

필요에 따라 매개 변수의 설명에 PSDefaultValue 특성을 추가하고 PSDefaultValue의 도움말 속성을 지정하여 매개 변수의 기본값을 설명하는 간단한 도움말 문자열을 제공할 수 있습니다. 함수에서 Size 매개 변수 Get-SmallFiles 의 기본값(100)을 설명하는 도움말 문자열을 제공하려면 다음 예제와 같이 PSDefaultValue 특성을 추가합니다.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

PSDefaultValue 특성 클래스에 대한 자세한 내용은 PSDefaultValue 특성 멤버를 참조하세요.

위치 매개 변수

위치 매개 변수는 매개 변수 이름이 없는 매개 변수입니다. PowerShell은 매개 변수 값 순서를 사용하여 각 매개 변수 값을 함수의 매개 변수와 연결합니다.

위치 매개 변수를 사용하는 경우 함수 이름 뒤의 값을 하나 이상 입력합니다. 위치 매개 변수 값은 배열 변수에 $args 할당됩니다. 함수 이름을 따르는 값은 배열$args[0]의 첫 번째 위치에 $args 할당됩니다.

다음 Get-Extension 함수는 제공하는 파일 이름에 파일 이름 확장자를 추가합니다 .txt .

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

매개 변수 전환

스위치는 값이 필요하지 않은 매개 변수입니다. 대신 함수 이름 뒤에 switch 매개 변수의 이름을 입력합니다.

switch 매개 변수를 정의하려면 다음 예제와 같이 매개 변수 이름 앞에 형식 [switch] 을 지정합니다.

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

함수 이름 뒤의 On switch 매개 변수를 입력하면 함수가 표시됩니다 Switch on. switch 매개 변수가 없으면 이 매개 변수가 Switch off표시됩니다.

Switch-Item -on

Switch on

Switch-Item

Switch off

다음 예제와 같이 함수를 실행할 때 스위치에 부울 값을 할당할 수도 있습니다.

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Splatting을 사용하여 명령 매개 변수 표시

스플래팅을 사용하여 명령의 매개 변수를 나타낼 수 있습니다. 이 기능은 Windows PowerShell 3.0에서 도입되었습니다.

세션에서 명령을 호출하는 함수에서 이 기술을 사용합니다. 명령 매개 변수를 선언하거나 열거하거나 명령 매개 변수가 변경되면 함수를 변경할 필요가 없습니다.

다음 샘플 함수는 cmdlet을 Get-Command 호출합니다. 이 명령은 .의 Get-Command매개 변수를 나타내는 데 사용합니다@Args.

function Get-MyCommand { Get-Command @Args }

함수를 호출할 때의 Get-Command 모든 매개 변수를 Get-MyCommand 사용할 수 있습니다. 매개 변수 및 매개 변수 값은 .를 사용하여 @Args명령에 전달됩니다.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

이 @Args 기능은 선언되지 않은 cmdlet 매개 변수와 나머지 인수의 값을 나타내는 자동 매개 변수를 사용합니다 $Args .

자세한 내용은 about_Splatting 참조하세요.

함수에 개체 파이프

모든 함수는 파이프라인에서 입력을 받을 수 있습니다. 함수가 , process및 endclean 키워드를 사용하여 begin파이프라인의 입력을 처리하는 방법을 제어할 수 있습니다. 다음 샘플 구문은 다음 키워드를 보여 줍니다.

process 문 목록은 파이프라인의 각 개체에 대해 한 번 실행됩니다. 블록이 process 실행되는 동안 각 파이프라인 개체는 한 번에 하나의 파이프라인 개체인 자동 변수에 할당됩니다 $_ .

다음 함수는 키워드를 process 사용합니다. 이 함수는 파이프라인의 값을 표시합니다.

function Get-Pipeline
{
  process {"The value is: $_"}
}

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

매개 변수에서 파이프라인 입력 또는 입력을 사용할 수 있는 함수를 원하는 경우 블록은 process 두 경우를 모두 처리해야 합니다. 예시:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

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

파이프라인에서 함수를 사용하는 경우 함수에 파이프된 개체가 자동 변수에 $input 할당됩니다. 이 함수는 파이프라인에서 개체가 begin 나오기 전에 키워드를 사용하여 문을 실행합니다. 이 함수는 파이프라인에서 모든 개체를 end 받은 후 키워드를 사용하여 문을 실행합니다.

다음 예제에서는 키워드와 $input end 함께 begin 자동 변수를 보여 줍니다.

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

이 함수가 파이프라인을 사용하여 실행되면 다음 결과가 표시됩니다.

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

begin 문이 실행되면 함수에 파이프라인의 입력이 없습니다. 이 문은 end 함수에 값이 있는 후에 실행됩니다.

함수에 키워드가 있는 process 경우 각 개체 $input 가 제거되고 $input 에 할당됩니다 $_. 다음 예제에는 process 문 목록이 있습니다.

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

이 예제에서는 함수에 파이프되는 각 개체가 문 목록으로 process 전송됩니다. 문은 process 각 개체, 한 번에 하나의 개체에서 실행됩니다. 함수가 $input 키워드에 도달하면 자동 변수가 비어 있습니다 end .

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

자세한 내용은 열거자 사용을 참조 하세요.

PowerShell 7.3에서 블록을 추가했습니다 clean . clean 블록은 사용자가 begin, process, end 블록에서 만들어지고 사용되는 리소스를 정리할 수 있는 편리한 방법입니다. 스크립트 함수 또는 스크립트 cmdlet의 다른 모든 명명된 블록을 포함하는 finally 블록과 의미상 유사합니다. 리소스 정리는 다음과 같은 시나리오에 적용됩니다.

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

주의

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

필터

필터는 파이프라인의 각 개체에서 실행되는 함수의 형식입니다. 필터는 블록에 모든 문이 있는 process 함수와 유사합니다.

필터의 구문은 다음과 같습니다.

filter [<scope:>]<name> {<statement list>}

다음 필터는 파이프라인에서 로그 항목을 가져오고 전체 항목 또는 항목의 메시지 부분만 표시합니다.

filter Get-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

다음과 같이 사용할 수 있습니다.

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

함수 범위

함수가 만들어진 범위에 존재합니다.

함수가 스크립트의 일부인 경우 해당 스크립트 내의 문에 함수를 사용할 수 있습니다. 기본적으로 스크립트의 함수는 해당 스크립트 외부에서 사용할 수 없습니다.

함수의 범위를 지정할 수 있습니다. 예를 들어 함수는 다음 예제에서 전역 범위에 추가됩니다.

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

함수가 전역 범위에 있는 경우 스크립트, 함수 및 명령줄에서 함수를 사용할 수 있습니다.

함수는 새 범위를 만듭니다. 변수와 같은 함수에서 만든 항목은 함수 범위에만 존재합니다.

자세한 내용은 about_Scopes 참조하세요.

함수를 사용하여 함수 찾기 및 관리: 드라이브

PowerShell의 모든 함수와 필터는 드라이브에 Function: 자동으로 저장됩니다. 이 드라이브는 PowerShell 함수 공급자에 의해 노출됩니다.

드라이브를 참조할 Function: 때 컴퓨터의 드라이브나 D 드라이브를 참조할 때와 마찬가지로 함수 뒤의 C 콜론을 입력합니다.

다음 명령은 PowerShell의 현재 세션에 있는 모든 함수를 표시합니다.

Get-ChildItem function:

함수의 명령은 함수의 정의 속성에 스크립트 블록으로 저장됩니다. 예를 들어 PowerShell과 함께 제공되는 도움말 함수에 명령을 표시하려면 다음을 입력합니다.

(Get-ChildItem function:help).Definition

다음 구문을 사용할 수도 있습니다.

$function:help

드라이브에 대한 Function: 자세한 내용은 함수 공급자에 대한 도움말 항목을 참조하세요. Get-Help Function.

새 세션에서 함수 다시 사용

PowerShell 명령 프롬프트에서 함수를 입력하면 함수가 현재 세션의 일부가 됩니다. 이 함수는 세션이 끝날 때까지 사용할 수 있습니다.

모든 PowerShell 세션에서 함수를 사용하려면 PowerShell 프로필에 함수를 추가합니다. 프로필에 대한 자세한 내용은 about_Profiles 참조하세요.

PowerShell 스크립트 파일에 함수를 저장할 수도 있습니다. 텍스트 파일에 함수를 입력한 다음 파일 이름 확장명으로 .ps1 파일을 저장합니다.

함수에 대한 도움말 작성

cmdlet은 Get-Help 함수뿐만 아니라 cmdlet, 공급자 및 스크립트에 대한 도움말을 가져옵니다. 함수에 대한 도움말을 보려면 함수 이름 뒤에 입력 Get-Help 합니다.

예를 들어 함수에 대한 도움말을 보려면 다음을 Get-MyDisks 입력합니다.

Get-Help Get-MyDisks

다음 두 가지 방법 중 하나를 사용하여 함수에 대한 도움말을 작성할 수 있습니다.

  • 함수에 대한 주석 기반 도움말

    주석에서 특수 키워드를 사용하여 도움말 항목을 만듭니다. 함수에 대한 주석 기반 도움말을 만들려면 함수 본문의 시작 또는 끝이나 함수 키워드 앞의 줄에 주석을 배치해야 합니다. 주석 기반 도움말에 대한 자세한 내용은 about_Comment_Based_Help 참조하세요.

  • 함수에 대한 XML 기반 도움말

    cmdlet에 대해 일반적으로 만들어진 형식과 같은 XML 기반 도움말 항목을 만듭니다. 도움말 항목을 여러 언어로 지역화하는 경우 XML 기반 도움말이 필요합니다.

    함수를 XML 기반 도움말 항목과 연결하려면 주석 기반 도움말 키워드를 .EXTERNALHELP 사용합니다. 이 키워드 Get-Help 가 없으면 함수 도움말 항목을 찾을 수 없으며 함수에 Get-Help 대한 호출은 자동 생성된 도움말만 반환합니다.

    키워드에 대한 .EXTERNALHELP 자세한 내용은 about_Comment_Based_Help 참조하세요. XML 기반 도움말에 대한 자세한 내용은 Cmdlet 도움말을 작성하는 방법을 참조 하세요.

참고 항목