PowerShell 스크립트의 함수
Aug 25, 2025
PowerShell 함수는 재사용 가능한 코드를 모듈식이고 유지보수가 쉬운 단위로 묶어 스크립팅을 간소화하고 오류를 줄입니다. 다음으로 정의합니다 function 키워드를 사용하며, 파라미터를 포함할 수 있고 파이프라인 입력을 받을 수 있으며, 다음을 사용해 cmdlet처럼 동작합니다 [CmdletBinding()] . 함수는 Try/Catch를 통한 오류 처리, 자세한 출력 및 디버그 출력, 모듈 구성 같은 고급 기능을 지원합니다. 모범 사례로는 의미 있는 이름 짓기, 모듈식 설계, 객체 반환, 그리고 주석 기반 도움말로 문서화하는 것이 있습니다.
PowerShell 함수는 특정 작업을 수행하도록 설계된 코드 블록입니다. 함수가 생성되고 테스트되면 여러 스크립트에서 재사용할 수 있어 코딩 노력과 오류 발생 위험이 줄어듭니다. 이름을 잘 지은 함수는 스크립트를 읽고 유지보수하기도 더 쉽게 만듭니다. 또한 함수는 다른 함수나 코드 블록의 입력으로 사용할 수 있는 값을 반환할 수 있으므로, 복잡한 작업을 구성하는 데 도움이 됩니다.
이 문서에서는 PowerShell 함수 사용을 시작하는 데 필요한 모든 내용을, 중요한 모범 사례를 포함해 설명하며, 더 고급 옵션을 자세히 살펴보는 데 도움이 되는 안내도 제공합니다.
PowerShell 함수 시작하기
PowerShell에서 함수 만드는 방법
함수를 정의하려면 function 키워드를 사용합니다. 기본 구문은 다음과 같습니다.
function <Function-Name> {
<Code-Block>
}
중괄호 {} 안의 코드는 함수가 호출될 때 실행됩니다.
원하는 경우 param 키워드를 사용하여 함수 매개변수와 함께 데이터 유형, 기본값 등을 지정할 수 있습니다. 매개변수를 추가한 문법은 다음과 같습니다:
function <Function-Name> {
[param(
[<ParameterType>]$<ParameterName>,
[<ParameterType>]$<ParameterName2> = <DefaultValue>
)]
<Code-Block>
}
이 PowerShell 함수 예제는 두 숫자를 곱하고 결과를 표시합니다:
function Multiply-Numbers {
param (
[int]$Number1,
[int]$Number2
)
$Result = $Number1 * $Number2
Write-Output "The multiplication value of $Number1 and $Number2 is $Result."
}
함수 저장하기
함수를 저장하려면 스크립트 파일에 다음 형식으로 저장하기만 하면 됩니다..ps1 확장자를 사용하세요.
함수 호출하기
PowerShell에서 함수를 호출하려면 함수 이름을 입력한 다음 필요한 이름이 지정된 매개변수를 입력합니다. 예를 들어, 위에서 정의한 함수를 호출하는 방법은 다음과 같습니다:
Multiply-Numbers -number1 6 -Number2 8
현재 세션의 일부로 함수 실행(Dot-Sourcing)
닷 소싱(Dot-sourcing)을 사용하면 현재 콘솔 세션 안에서 스크립트가 직접 정의된 것처럼 PowerShell 스크립트를 실행할 수 있습니다. 닷 소싱을 사용하려면 함수를 호출할 때 함수 이름 앞에 점과 공백(. )을 붙입니다.
예를 들어, 다음과 같은 이름의 함수를 정의했다고 가정해 보겠습니다.Add-Numbers:
function Add-Numbers {
param (
[int]$Number1,
[int]$Number2
)
$Sum = $Number1 + $Number2
Write-Output "The sum of $Number1 and $Number2 is $Sum."
}
다음과 같이 이 함수를 세션에 닷 소싱할 수 있습니다:
PowerShell 함수를 이름 짓는 방법
PowerShell 함수에서 최대의 가치를 얻으려면, 함수를 이름 지을 때 다음 지침을 따르세요.
동사-명사 형식을 사용하세요.
PowerShell은 이름이 특정 형식을 따르는 미리 만들어진 cmdlet 세트를 제공합니다. 즉, 수행할 작업을 나타내는 동사와, 그 작업의 대상이 되는 개체를 나타내는 명사가 이어집니다. 예를 들어, get-user cmdlet은 사용자에 대한 정보를 가져오고, remove-item 는 지정한 항목을 삭제합니다.
새로 만드는 함수에 대해 동일한 명명 규칙을 따르는 것은 모범 사례입니다. 그렇게 하면 함수를 더 효과적으로 설계하고, 재사용하기도 더 쉬워집니다.
승인된 동사만 사용하세요.
PowerShell은 함수에 사용할 것을 권장하는 동사의 목록을 제공합니다. 목록을 보려면 다음 cmdlet을 실행하기만 하면 됩니다:
Get-Verb
설명이 명확한 명사를 선택하세요.
함수에 내장 cmdlet과 동일한 이름을 부여하지 않는 것이 매우 중요합니다. 이 문제를 예방하는 좋은 방법은 다음과 같은 일반적인 명사(예: user 및 data. )를 사용하지 않는 것입니다. 대신, 함수가 처리하는 데이터의 유형을 명확하게 나타내는 명사를 선택하세요. 예를 들어, 다음 함수들이 어떻게 다른지 쉽게 이해할 수 있습니다: Get-EmployeeData, Get-UserInfo 및 Get-ServiceInfo.
버전 관리 목적으로 함수 이름을 사용하지 마세요.
함수 이름에 버전 번호를 덧붙이는 방식(예: Get-UserInfoV2)은 권장되지 않습니다. 스크립트를 이해하기 더 어렵게 만들고, 함수의 이전 버전을 사용할 가능성도 높입니다. 대신 파일 버전 관리 시스템을 통해 버저닝을 처리하세요.
고급 함수 기능
파이프라인 입력 받기
함수를 설계할 때 ValueFromPipeline 속성을 사용하면 파이프라인을 통해 다른 함수 또는 명령의 입력을 받을 수 있습니다.
예를 들어, 문자열 목록을 하나씩 처리하고 각 문자열을 대문자로 변환한 뒤 결과를 출력하는 함수를 만들어 보겠습니다. 이해를 돕기 위해 문자열 처리를 세 가지 서로 다른 블록으로 나누겠습니다:
- BEGIN — 이 코드는 파이프라인 입력을 처리하기 전에 한 번만 실행됩니다.
- PROCESS — 이 섹션은 파이프라인으로 전달되는 각 항목에 대해 실행되며, 입력 객체를 하나씩 처리합니다.
- END — 이 코드는 모든 입력 처리가 끝난 후 실행되어 출력을 최종 확정합니다.
function Convert-ToUppercase {
[CmdletBinding()]
param (
[Parameter(ValueFromPipeline = $true, Mandatory = $true)]
[string]$InputString
)
BEGIN {
Write-Verbose "Starting the uppercase conversion process."
}
PROCESS {
if (-not [string]::IsNullOrWhiteSpace($InputString)) {
Write-Verbose "Processing string: $InputString"
$InputString.ToUpper()
} else {
Write-Verbose "Skipped empty or null string."
}
}
END {
Write-Verbose "Finished processing all strings."
}
}
파이프라인을 통해 제공된 문자열 목록을 변환하기 위해 함수를 호출하는 방법은 다음과 같습니다:
"hello", "world", "this", "is", "powershell" | Convert-ToUppercase -Verbose
가벼운 함수라고 불리는 filters 는 파이프라인을 통해 전달되는 객체를 처리하는 데 매우 효율적인 방법을 제공할 수 있습니다.
함수를 Cmdlet처럼 동작하도록 설정하기
를 사용하면 기본 함수를 고급 함수로 전환할 수 있습니다.CmdletBinding 속성입니다. 그렇게 하면 정의된 PowerShell 매개 변수를 지원하는 등, 함수가 cmdlet처럼 동작하도록 설정됩니다.
두 숫자를 더하기 위해 앞에서 정의한 기본 함수는 다음과 같습니다:
function Add-Numbers {
param (
[int]$Number1,
[int]$Number2
)
$Sum = $Number1 + $Number2
Write-Output "The sum of $Number1 and $Number2 is $Sum."
}
다음과 같이 이를 고급 함수로 바꿀 수 있습니다:
function Add-Numbers {
[CmdletBinding()]
param (
[Parameter(Mandatory)]
[int]$Number1,
[Parameter(Mandatory)]
[int]$Number2
)
process {
# Verbose Output
Write-Verbose "Starting addition of $Number1 and $Number2"
# Debugging Output
Write-Debug "Debugging: Ensuring numbers are valid integers"
# Perform the Addition
try {
$Result = $Number1 + $Number2
Write-Output $Result
} catch {
# Handle errors with error stream
Write-Error "An error occurred while performing the addition."
}
# Verbose Completion Message
Write-Verbose "Addition completed successfully"
}
}
Netwrix Auditor 무료 체험판을 신청하세요
함수 모듈 빌드하기
함수 모듈은 .psm1 확장자를 가진 파일로, 관련 함수들의 모음을 포함합니다. 함수를 모듈로 구성하면 재사용성과 유지보수가 쉬워집니다.
함수 모듈을 만들려면 간단히 텍스트 파일을 만들고 함수를 붙여 넣은 다음 .psm1 확장자로 저장하면 됩니다. 저장 위치는 C:\Program Files\WindowsPowerShell\Modules 디렉터리입니다. 예를 들어 앞에서 정의한 Add-Numbers 함수와 같은 산술 함수로 모듈을 만들 수 있습니다.
PowerShell 세션으로 모듈을 가져오려면 다음에 표시된 Import-Module 명령을 사용합니다.
오류 처리
PowerShell은 0으로 나누기를 시도하는 것처럼, 오류로 인해 함수 실행이 중단될 수 있는 문제를 부드럽게 처리하는 데 도움이 되는 여러 오류 처리 기법을 제공합니다.
Try/Catch/Finally 블록
특정 조건이 문제를 일으킬 수 있음을 알고 있다면, 해당 조건을 우아하게 처리하기 위해 함수에 Try, Catch 및 Finally 블록을 사용할 수 있습니다:
- Try — 이 블록에는 오류를 발생시킬 수 있는 코드(예: 나눗셈 연산)가 포함됩니다. 오류가 발생하지 않으면 Catch 블록은 실행되지 않습니다.
- Catch — Try 블록에서 오류가 발생하면 Catch 블록이 오류 세부 정보를 캡처하고 처리하여 이를 처리합니다.
- 마지막으로 — 이 블록은 선택 사항입니다. 포함되어 있으면 오류 발생 여부와 관계없이 Try 및 Catch 블록 다음에 실행됩니다.
-ErrorAction 매개 변수
-ErrorAction 매개 변수를 사용하면 특정 함수에서 오류를 어떻게 처리할지 지정할 수 있습니다. 가능한 값은 다음과 같습니다:
- 계속 — 오류 메시지를 표시하고 계속 진행합니다.
- 중지 — 오류가 발생하면 스크립트 실행을 중단합니다.
- SilentlyContinue — 오류 메시지를 숨기고 실행을 계속합니다.
- Inquire — 오류를 어떻게 처리할지 사용자에게 다음과 같은 옵션으로 묻습니다: Yes, No 및 Retry.
- Ignore — 메시지도 표시하지 않고 오류를 완전히 무시합니다.
다음은 -ErrorAction 매개변수의 몇 가지 예입니다:
Remove-Item "C:\path\to\nonexistentfile.txt" -ErrorAction SilentlyContinue
Get-Process -Name "Notepad" -ErrorAction Stop
$ErrorActionPreference 변수
변수 $ErrorActionPreference는 세션에서 사용되는 모든 cmdlet에 대해 오류가 전역적으로 어떻게 처리되는지를 제어합니다. 이 변수는 -ErrorAction 매개 변수가 재정의하지 않는 한, 모든 명령 전반에 걸친 오류 처리 동작에 영향을 주도록 설정할 수 있습니다.
자세한 예
아래는 여러 가지 오류 처리 방법을 사용하는 예입니다:
- $ErrorActionPreference 변수는 전역 오류 처리 기본 설정을 stop 으로 설정하므로, 다른 방식으로 처리되지 않은 오류가 발생하면 실행이 중지됩니다.
- Try/Catch 블록은 실행을 중단하지 않고 0으로 나누는 데서 발생할 수 있는 오류를 자연스럽게 처리합니다. Try 블록이 수학 연산을 수행합니다. 0으로 나누기를 만나면 처리는 Catch 블록으로 이동하며, 이 블록이 오류 메시지를 출력합니다.
- 해당 Finally 블록은 오류가 발생했는지 여부와 관계없이 실행되며, 작업이 완료되었음을 알리는 메시지를 출력합니다.
# Set global error action preference to 'Stop' to immediately halt on errors
$ErrorActionPreference = 'Stop'
function Perform-MathOperations {
param (
[int]$Num1,
[int]$Num2
)
try {
# Performing addition
Write-Host "Performing addition: $Num1 + $Num2"
$additionResult = $Num1 + $Num2
Write-Host "Addition Result: $additionResult"
# Checking for division by zero before performing division
if ($Num2 -eq 0) {
throw "Division by zero is not allowed."
}
# Performing division
Write-Host "Performing division: $Num1 / $Num2"
$divisionResult = $Num1 / $Num2
Write-Host "Division Result: $divisionResult"
}
catch {
# Catching any error that occurs in the try block
Write-Host "An error occurred: $_"
Write-Host "Error Type: $($_.Exception.GetType().Name)"
}
finally {
# This block always runs regardless of error occurrence
Write-Host "Finished performing math operations."
}
}
아래 스크린샷은 이 함수를 두 가지 방식으로 호출했을 때의 결과를 보여줍니다. 먼저, 유효한 입력으로 호출합니다.
Perform-MathOperations -Num1 10 -Num2 2
그다음 0으로 나누려는 시도를 발생시키는 입력으로 호출합니다.
Perform-MathOperations -Num1 10 -Num2 0
함수 문제 해결
함수 실행 중에 다양한 수준의 자세한 정보를 제공하는 메시지는 Write-output (또는 Write-host), Write-Verbose 및 Write-Debug 를 사용하여 표시할 수 있습니다. 이 정보는 실행 경로를 단계별로 추적하여 예상치 못한 동작을 정확히 파악하는 데 도움이 됩니다.
예를 들어, 아래 스크린샷에서는 기본 Add-Numbers 함수를 수정하여 문제 해결에 필요한 자세한 정보를 제공하는 방법을 보여줍니다. 기본적으로 자세한(Verbose) 메시지 스트림은 표시되지 않으므로, 함수를 호출할 때 -Verbose 를 사용해야 합니다.
Add-Numbers -Number1 5 -Number2 10 -Verbose
마찬가지로 Write-Debug 메시지는 기본적으로 콘솔에 표시되지 않지만, 함수를 실행할 때 -Debug 를 포함하면 표시할 수 있습니다:
Add-Numbers -Number1 5 -Number2 10 -Debug
모범 사례
- 각 함수가 한 가지 작업만 수행하도록 설계하세요. 그러면 테스트, 사용, 유지 관리가 더 쉬워집니다.
- 함수를 모듈 방식으로 설계하여 서로 다른 스크립트에서 재사용할 수 있도록 하세요.
- 매개변수를 사용할 때는 기본값을 지정하세요.
- 함수에 자세한 주석을 포함하세요. 주석 기반 도움말은 디버깅과 함수 재사용을 더 쉽게 해줍니다.
- 재사용성을 높이려면 함수가 서식이 지정된 출력 대신 객체를 반환하도록 하세요.
추가 예시
아래 함수는 오류 처리 등을 포함하여 앞에서 논의한 많은 기능을 보여줍니다:
# Function: Backup-Files
# Description: Backs up files from a source directory to a backup directory.
function Backup-Files {
param (
[Parameter(Mandatory = $true)]
[string]$SourcePath, # The directory containing the files to back up
[Parameter(Mandatory = $true)]
[string]$BackupPath, # The directory where files will be backed up
[string[]]$Extensions = @("*") # File extensions to back up (default: all files)
)
# Check if the source path exists
if (-not (Test-Path -Path $SourcePath)) {
Write-Error "Source path '$SourcePath' does not exist."
return
}
# Create the backup directory if it does not exist
if (-not (Test-Path -Path $BackupPath)) {
Write-Output "Creating backup directory at '$BackupPath'..."
New-Item -ItemType Directory -Path $BackupPath | Out-Null
}
# Get files matching the specified extensions
foreach ($extension in $Extensions) {
$files = Get-ChildItem -Path $SourcePath -Filter "*.$extension" -File -ErrorAction SilentlyContinue
foreach ($file in $files) {
$destination = Join-Path -Path $BackupPath -ChildPath $file.Name
Write-Output "Backing up file: $($file.FullName) -> $destination"
Copy-Item -Path $file.FullName -Destination $destination -Force
}
}
Write-Output "Backup completed successfully."
}
이 함수를 호출하여 모든 파일을 백업하거나, 여기서처럼 특정 파일 확장자만 선택해 백업할 수도 있습니다:
Backup-Files -SourcePath "D:\Office\project" -BackupPath "D:\Backup" -Extensions @("csv", "txt")
결론
PowerShell의 함수는 스크립팅에 대해 구조화된 접근 방식을 제공하여 모듈성, 재사용성, 유지보수성을 향상시킵니다. 이 글에 제공된 모든 예제 코드를 마음껏 실험해 보세요. 직접 함수를 만들기 시작할 때는 함수의 이름 지정과 사용에 대한 모범 사례를 반드시 따르십시오.
초보자를 위한 Windows PowerShell 스크립팅 튜토리얼
eBook 다운로드공유하기
더 알아보기
저자 소개
Tyler Reese
제품 관리 부사장, CISSP
소프트웨어 보안 업계에서 20년이 넘는 경력을 쌓아온 Tyler Reese는 오늘날 기업이 직면한 빠르게 변화하는 아이덴티티 및 보안 과제에 대해 깊이 잘 알고 있습니다. 현재 그는 Netwrix Identity and Access Management 포트폴리오의 제품 디렉터로 재직 중이며, 시장 동향을 평가하고 IAM 제품 라인의 방향을 설정하는 일을 포함해 궁극적으로는 엔드 유저의 요구를 충족하는 역할을 담당하고 있습니다. 그의 전문 경력은 Fortune 500 기업을 대상으로 한 IAM 컨설팅부터 대형 D2C(Direct-to-Consumer) 기업의 엔터프라이즈 아키텍트로 일한 경험까지 폭넓게 이어져 있습니다. 그는 현재 CISSP 자격증을 보유하고 있습니다.