about_Functions

아티클
05/09/2024

간단한 설명

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

자세한 설명입니다.

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

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

function Get-PowerShellProcess { Get-Process PowerShell }

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

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

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

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

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

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

중요

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

Syntax

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

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>}
}

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

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

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

입력 처리 방법

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

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

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

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

`begin`

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

`process`

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

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

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

중요

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

`end`

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

`clean`

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

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

종료 오류 없이 파이프라인 실행이 정상적으로 완료되는 경우
종료 오류로 인해 파이프라인 실행이 중단되는 경우
Select-Object -First로 인해 파이프라인이 중단되는 경우
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.

명명된 매개 변수

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

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

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

다음 샘플 구문과 같이 키워드(keyword) 없이 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의 Help 속성을 지정하여 매개 변수의 기본값을 설명하는 간단한 도움말 문자열을 제공할 수 있습니다. 함수에서 Size 매개 변수 Get-SmallFiles 의 기본값(100)을 설명하는 도움말 문자열을 제공하려면 다음 예제와 같이 PSDefaultValue 특성을 추가합니다.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

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 호출합니다. 명령은 를 사용하여 @Args 의 Get-Command매개 변수를 나타냅니다.

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.

함수에 개체 파이핑

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

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

다음 함수는 키워드(keyword) 사용합니다 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 나오기 전에 키워드(keyword) 사용하여 문을 실행합니다. 함수는 파이프라인에서 모든 개체를 end 받은 후 키워드(keyword) 사용하여 문을 실행합니다.

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

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 에 키워드(keyword) 있는 경우 의 $input 각 개체가 에서 $input 제거되고 에 $_할당됩니다. 다음 예제에는 process 문 목록이 있습니다.

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

이 예제에서는 함수에 파이프된 각 개체가 문 목록으로 process 전송됩니다. 문은 process 각 개체, 한 번에 하나의 개체에서 실행됩니다. 함수가 $input 키워드(keyword) 도달하면 자동 변수가 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 블록과 의미상 유사합니다. 리소스 정리는 다음과 같은 시나리오에 적용됩니다.

종료 오류 없이 파이프라인 실행이 정상적으로 완료되는 경우
종료 오류로 인해 파이프라인 실행이 중단되는 경우
Select-Object -First로 인해 파이프라인이 중단되는 경우
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

함수 범위

함수가 만들어진 scope 있습니다.

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

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

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

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

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

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

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

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

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

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

Get-ChildItem function:

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

(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

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

함수에 대한 Comment-Based 도움말

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

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

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

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

다음을 통해 공유