about_Functions_Advanced_Parameters
about_Functions_Advanced_Parameters
고급 함수(advanced function)에 매개 변수를 추가하고, 매개 변수 속성(attribute)과 인자(argument)로 사용자가 넘길 값을 제한하는 방법을 하나씩 설명해 드릴게요. 이 문서를 차근차근 따라오시면 고급 함수의 매개 변수를 능숙하게 다루실 수 있게 돼요.
출처: Microsoft Learn — PowerShell 공식 문서
본문
간단한 설명
고급 함수에 매개 변수를 추가하는 방법을 설명해요.
자세한 설명
직접 작성한 고급 함수에 매개 변수를 추가할 수 있고요, 매개 변수 속성과 인자를 활용해서 함수를 호출하는 사람이 매개 변수를 통해 제출하는 값을 제한할 수 있어요.
CmdletBinding 속성을 사용하면 PowerShell이 공통 매개 변수(Common Parameters)를 자동으로 추가해 줘요. 그래서 공통 매개 변수와 같은 이름을 가진 매개 변수는 만들 수 없어요. 자세한 내용은 about_CommonParameters 문서를 참고해 주세요.
PowerShell 3.0부터는 명령 안의 매개 변수를 나타낼 때 @args를 사용한 스플래팅(splatting)을 쓸 수 있어요. 스플래팅은 단순 함수와 고급 함수 모두에서 유효해요. 자세한 내용은 about_Functions와 about_Splatting 문서를 확인해 주세요.
매개 변수 선언
매개 변수는 함수나 스크립트 블록의 param() 문 안에 선언하는 변수예요. 선택 사항인 [Parameter()] 속성을 단독으로 쓰거나, [Alias()] 속성 또는 각종 매개 변수 유효성 검사 속성과 함께 쓸 수 있어요.
매개 변수 이름은 변수 이름 규칙을 따르는데요, 10진 숫자, 알파벳 문자, 밑줄로 구성돼요. 이름 규칙 전체 목록은 about_Variables 문서에서 확인할 수 있어요.
중요: 매개 변수 이름이 10진 숫자로 시작하도록 정의하는 것도 가능하긴 한데요, 권장하지는 않아요. PowerShell이 그런 매개 변수를 위치 매개 변수로 전달되는 문자열 값으로 취급하거든요.
다음 예시를 살펴볼게요.
function TestFunction {
param (
[switch] $100,
[string] $200
)
"100: $100"
"200: $200"
}
이 매개 변수들을 실제로 사용해 보면, PowerShell이 이들을 위치 매개 변수로 전달되는 문자열로 해석해요.
PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello
출력 결과를 보면 PowerShell이 값 -100을 $200 매개 변수 변수에 바인딩했고요, 나머지 위치 값들은 $args에 바인딩된 걸 알 수 있어요. 이런 문제를 우회하려면 스플래팅을 사용해서 매개 변수 값을 전달하면 돼요.
PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:
자세한 내용은 about_Splatting 문서를 참고해 주세요.
매개 변수 값의 형식 변환
예상 형식과 다른 형식의 문자열을 매개 변수 인자로 제공하면, PowerShell이 그 문자열을 매개 변수의 대상 형식으로 암시적으로 변환해요. 고급 함수는 매개 변수 값을 문화권과 무관하게(invariant) 파싱해요.
반면에 컴파일된 cmdlet은 매개 변수 바인딩 시 문화권을 고려한(문화권에 민감한) 변환을 수행해요.
이 예시에서는 [datetime] 매개 변수를 받는 cmdlet과 스크립트 함수를 하나씩 만들어 볼게요. 현재 문화권을 독일어 설정으로 바꾸고, 독일어 형식의 날짜를 매개 변수에 전달해 볼게요.
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
위에서 볼 수 있듯이, cmdlet은 문화권을 고려한 파싱으로 문자열을 변환해요.
# Define an equivalent function.
function Get-Date_Func {
param(
[datetime] $Date
)
process {
$Date
}
}
[cultureinfo]::CurrentCulture = 'de-DE'
# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'
Get-Date_Func $dateStr
고급 함수는 문화권과 무관한 파싱을 수행하기 때문에, 다음과 같은 오류가 발생해요.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
자세한 내용은 about_Type_Conversion 문서를 참고해 주세요.
정적 매개 변수
정적 매개 변수는 함수 안에서 언제나 사용할 수 있는 매개 변수예요. PowerShell cmdlet과 스크립트에 있는 매개 변수의 대부분이 정적 매개 변수에 해당해요.
다음 예시는 아래 특징을 가진 ComputerName 매개 변수의 선언을 보여줘요.
- 필수(필요) 항목이에요.
- 파이프라인에서 입력을 받아요.
- 문자열 배열을 입력으로 받아요.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
[switch] 매개 변수
[switch] 매개 변수는 매개 변수 값을 받지 않는 매개 변수예요. 대신에 매개 변수의 존재 여부를 통해 참(true) 또는 거짓(false)이라는 불리언 값을 전달해요. 그래서 [switch] 매개 변수가 있으면 참 값, 없으면 거짓 값이 돼요.
예를 들어 Get-ChildItem의 Recurse 매개 변수가 [switch] 매개 변수예요.
다음 예시는 데이터를 바이트 배열로 출력하는 옵션을 제공할 때 쓸 수 있는 [switch] 매개 변수의 정의를 보여줘요.
param([switch]$AsByteArray)
[switch] 매개 변수는 사용하기 쉽고, PowerShell에서 덜 자연스러운 문법을 가진 불리언 매개 변수보다 선호돼요.
[switch] 매개 변수를 사용하려면 명령에 해당 매개 변수를 포함시키면 돼요. 예를 들어:
-IncludeAll
불리언 매개 변수를 사용하려면 매개 변수와 불리언 값을 모두 제공해야 해요.
-IncludeAll $true
[switch] 매개 변수를 만들 때는 매개 변수 이름을 신중하게 정해야 해요. 이름이 사용자에게 매개 변수가 어떤 효과를 내는지 잘 전달되도록 하고요, Filter나 Maximum처럼 값을 요구할 것처럼 느껴지는 모호한 용어는 피하는 게 좋아요.
[switch] 매개 변수 설계 고려 사항
-
[switch]매개 변수에는 기본값을 설정하지 마세요.[switch]매개 변수는 항상 기본적으로 거짓(false)이에요. -
[switch]매개 변수를 위치 매개 변수로 만들지 마세요. 기본적으로[switch]매개 변수는 위치 매개 변수에서 제외되는데요, Parameter 속성에서 이를 재정의할 수는 있지만 사용자를 헷갈리게 만들 수 있어요. -
[switch]매개 변수를 사용하면 명령의 기본 동작이 덜 흔하거나 더 복잡한 모드로 바뀌도록 설계하세요. 명령의 가장 단순한 동작이 바로 기본 동작이어야 하고, 그 기본 동작은[switch]매개 변수 없이도 동작해야 해요. -
[switch]매개 변수를 필수로 만들지 마세요.[switch]매개 변수를 필수로 만드는 게 유용한 유일한 경우는 매개 변수 집합을 구분해야 할 때예요. -
조건식 안에서
[switch]매개 변수 변수를 직접 사용하세요.SwitchParameter형식은 불리언으로 암시적으로 변환돼요. 예를 들어:if ($MySwitch) { ... } -
[switch]매개 변수가 제어하는 동작은 항상 매개 변수의 존재 여부가 아니라 매개 변수의 값을 기준으로 삼으세요.[switch]매개 변수의 존재 여부를 테스트하는 방법은 여러 가지가 있어요.$PSBoundParameters에는[switch]매개 변수 이름이 키로 들어 있어요$MyInvocation.BoundParameters에는[switch]매개 변수 이름이 키로 들어 있어요 스위치가 고유한 매개 변수 집합을 정의하는 경우$PSCmdlet.ParameterSetName
예를 들어 -MySwitch:$false나 스플래팅을 사용해서 스위치에 명시적인 값을 제공할 수 있어요. 매개 변수의 존재 여부만 테스트하면, 스위치 값이 $false인데도 명령이 $true인 것처럼 동작해요.
동적 매개 변수
동적 매개 변수는 특정 조건에서만 사용할 수 있는 cmdlet, 함수, 스크립트의 매개 변수예요.
예를 들어 여러 공급자 cmdlet에는 cmdlet을 공급자 드라이브에서, 또는 공급자 드라이브의 특정 경로에서 사용할 때만 사용할 수 있는 매개 변수가 있어요. 예를 들어 Encoding 매개 변수는 파일 시스템 드라이브에서 사용할 때에만 Add-Content, Get-Content, Set-Content cmdlet에서 사용할 수 있어요.
또한 함수 명령에서 다른 매개 변수를 사용할 때, 또는 다른 매개 변수가 특정 값을 가질 때에만 나타나는 매개 변수를 만들 수도 있어요.
동적 매개 변수는 유용하긴 하지만, 사용자가 발견하기 어려울 수 있으니 꼭 필요할 때만 사용하는 게 좋아요. 동적 매개 변수를 찾으려면 사용자가 공급자 경로 안에 있어야 하거나, Get-Command cmdlet의 ArgumentList 매개 변수를 사용하거나, Get-Help의 Path 매개 변수를 사용해야 해요.
함수나 스크립트에 동적 매개 변수를 만들려면 dynamicparam 키워드를 사용하면 돼요.
구문은 다음과 같아요.
dynamicparam {<statement-list>}
문장 목록 안에서는 if 문을 사용해서 함수에서 매개 변수를 사용할 수 있는 조건을 지정해요.
다음 예시는 Name과 Path라는 표준 매개 변수와, KeyCount라는 선택적인 동적 매개 변수를 가진 함수를 보여줘요. KeyCount 매개 변수는 ByRegistryPath 매개 변수 집합에 있고 형식은 Int32예요. KeyCount 매개 변수는 Path 매개 변수 값이 HKLM:로 시작할 때, 즉 HKEY_LOCAL_MACHINE 레지스트리 드라이브에서 사용되고 있음을 나타낼 때에만 Get-Sample 함수에서 사용할 수 있어요.
function Get-Sample {
[CmdletBinding()]
param([string]$Name, [string]$Path)
dynamicparam
{
if ($Path.StartsWith("HKLM:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
자세한 내용은 RuntimeDefinedParameter 형식 문서를 참고해 주세요.
매개 변수의 속성
이 절에서는 함수 매개 변수에 추가할 수 있는 속성들을 설명해요.
모든 속성은 선택 사항이에요. 다만 CmdletBinding 속성을 생략하면, 고급 함수로 인식되려면 함수에 Parameter 속성을 반드시 포함해야 해요.
각 매개 변수 선언에는 하나 또는 여러 개의 속성을 추가할 수 있어요. 매개 변수 선언에 추가할 수 있는 속성 수에는 제한이 없어요.
Parameter 속성
Parameter 속성은 함수 매개 변수의 특성을 선언하는 데 사용돼요.
Parameter 속성은 선택 사항이라서, 함수의 어떤 매개 변수도 속성이 필요하지 않다면 생략할 수 있어요. 하지만 단순 함수가 아니라 고급 함수로 인식되려면, 함수에 CmdletBinding 속성이나 Parameter 속성 중 하나 또는 둘 다가 있어야 해요.
Parameter 속성에는 매개 변수가 필수인지 선택인지 같은, 매개 변수의 특징을 정의하는 인자들이 있어요.
Parameter 속성과 인자, 그리고 인자 값을 선언할 때는 다음과 같은 구문을 사용해요. 인자와 인자 값을 감싸는 괄호는 Parameter 다음에 공백 없이 바로 이어져야 해요.
param(
[Parameter(Argument=value)]
$ParameterName
)
괄호 안의 인자들은 쉼표로 구분해요. Parameter 속성의 인자 두 개를 선언할 때는 다음과 같은 구문을 사용해요.
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
Parameter 속성의 불리언 인자 형식은 Parameter 속성에서 생략하면 기본적으로 False예요. 인자 값을 $true로 설정하거나, 인자 이름만 나열하면 돼요. 예를 들어 다음 두 Parameter 속성은 동일해요.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Parameter 속성을 인자 없이 사용하면(CmdletBinding 속성을 쓰는 대신에), 속성 이름 뒤에 오는 괄호는 여전히 필요해요.
param(
[Parameter()]
$ParameterName
)
Mandatory 인자
Mandatory 인자는 매개 변수가 필수임을 나타내요. 이 인자를 지정하지 않으면 매개 변수는 선택 사항이 돼요.
다음 예시는 ComputerName 매개 변수를 선언하고 있어요. Mandatory 인자를 사용해서 매개 변수를 필수로 만들어요.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Position 인자
Position 인자는 명령에서 매개 변수를 사용할 때 매개 변수 이름이 필요한지 여부를 결정해요. 매개 변수 선언에 Position 인자가 포함되면 매개 변수 이름을 생략할 수 있고, PowerShell이 명령 안의 이름 없는 매개 변수 값 목록에서 그 위치(순서)를 기준으로 이름 없는 매개 변수 값을 식별해요.
Position 인자를 지정하지 않으면, 명령에서 매개 변수를 사용할 때마다 매개 변수 이름(또는 이름 별칭, 약어)이 매개 변수 값보다 앞에 와야 해요.
기본적으로 모든 함수 매개 변수는 위치 매개 변수예요. PowerShell은 함수에서 매개 변수가 선언된 순서대로 매개 변수에 위치 번호를 할당해요. 이 동작을 끄려면 CmdletBinding 속성의 PositionalBinding 인자 값을 $false로 설정하면 돼요. Position 인자는 CmdletBinding 속성의 PositionalBinding 인자 값보다 우선해요. 자세한 내용은 about_Functions_CmdletBindingAttribute 문서의 PositionalBinding을 참고해 주세요.
Position 인자 값은 정수로 지정해요. 위치 값 0은 명령에서 첫 번째 위치를, 위치 값 1은 두 번째 위치를 나타내는 식이에요.
함수에 위치 매개 변수가 하나도 없으면, PowerShell이 매개 변수 선언 순서에 따라 각 매개 변수에 위치를 할당해요. 다만 모범 사례상 이 할당을 믿지 않는 게 좋아요. 매개 변수를 위치 매개 변수로 만들고 싶다면 Position 인자를 사용하세요.
다음 예시는 ComputerName 매개 변수를 선언하고 있어요. Position 인자를 값 0과 함께 사용하고 있어요. 그 결과 -ComputerName을 명령에서 생략하면, 그 값이 명령에서 첫 번째이자 유일한 이름 없는 매개 변수 값이 되어야 해요.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName 인자
ParameterSetName 인자는 매개 변수가 속하는 매개 변수 집합을 지정해요. 매개 변수 집합을 지정하지 않으면, 그 매개 변수는 함수가 정의하는 모든 매개 변수 집합에 속해요. 각 매개 변수 집합이 고유하려면, 다른 어떤 매개 변수 집합에도 속하지 않는 매개 변수가 최소한 하나는 있어야 해요.
참고: cmdlet이나 함수에는 매개 변수 집합이 최대 32개로 제한돼요.
다음 예시는 Computer 매개 변수 집합에 ComputerName 매개 변수를, User 매개 변수 집합에 UserName 매개 변수를, 두 매개 변수 집합 모두에 Summary 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
각 인자에는 ParameterSetName 값을 하나만, 각 Parameter 속성에는 ParameterSetName 인자를 하나만 지정할 수 있어요. 매개 변수를 둘 이상의 매개 변수 집합에 포함하려면 Parameter 속성을 추가하면 돼요.
다음 예시는 Summary 매개 변수를 Computer와 User 매개 변수 집합에 명시적으로 추가하고 있어요. Summary 매개 변수는 Computer 매개 변수 집합에서는 선택 사항이고, User 매개 변수 집합에서는 필수예요.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]$Summary
)
매개 변수 집합에 대한 자세한 내용은 About Parameter Sets 문서를 참고해 주세요.
ValueFromPipeline 인자
ValueFromPipeline 인자는 매개 변수가 파이프라인 개체에서 입력을 받는다는 것을 나타내요. 함수가 개체의 속성 하나만이 아니라 개체 전체를 받는다면 이 인자를 지정해요.
다음 예시는 필수이며, 파이프라인에서 함수로 전달된 개체를 받는 ComputerName 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string[]]$ComputerName
)
ValueFromPipelineByPropertyName 인자
ValueFromPipelineByPropertyName 인자는 매개 변수가 파이프라인 개체의 속성에서 입력을 받는다는 것을 나타내요. 개체 속성은 매개 변수와 같은 이름이나 별칭을 가져야 해요.
예를 들어 함수에 ComputerName 매개 변수가 있고, 파이프라인으로 전달된 개체에 ComputerName 속성이 있다면, ComputerName 속성 값이 함수의 ComputerName 매개 변수에 할당돼요.
다음 예시는 필수이며, 파이프라인을 통해 함수로 전달되는 개체의 ComputerName 속성에서 입력을 받는 ComputerName 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
이 인자를 사용하는 함수의 구현을 살펴볼게요.
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
그리고 ComputerName 속성을 가진 개체를 파이프라인으로 전달하는 예시는 다음과 같아요.
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
참고: 파이프라인 입력(
by Value) 또는(by PropertyName)을 받는 형식 지정 매개 변수는 매개 변수에서 지연 바인딩 스크립트 블록(delay-bind scriptblock)을 사용할 수 있게 해 줘요.지연 바인딩 스크립트 블록은 ParameterBinding 중에 자동으로 실행되고, 그 결과가 매개 변수에 바인딩돼요. 지연 바인딩은 형식이 ScriptBlock 또는 System.Object로 정의된 매개 변수에서는 동작하지 않아요. 해당 스크립트 블록은 호출되지 않은 채 그대로 전달돼요. 지연 바인딩 스크립트 블록에 대한 자세한 내용은 about_Script_Blocks 문서를 참고해 주세요.
ValueFromRemainingArguments 인자
ValueFromRemainingArguments 인자는 매개 변수가 함수의 다른 매개 변수에 할당되지 않은, 명령 안의 매개 변수 값을 모두 받는다는 것을 나타내요.
다음 예시는 필수인 Value 매개 변수와, 함수에 제출된 나머지 매개 변수 값을 모두 받는 Remaining 매개 변수를 선언하고 있어요.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(ValueFromRemainingArguments, Position=1)]
[string[]]$Remaining
)
"Value = $Value"
"Found $($Remaining.Count) remaining values"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
PS> Test-Remainder first one two three
Value = first
Found 3 remaining values
0: one
1: two
2: three
PowerShell 6.2부터는 컬렉션을 ValueFromRemainingArguments에 전달할 때 처리 방식이 달라져요. 컬렉션만 전달하면 컬렉션 안의 각 값이 별도의 항목으로 취급돼요.
PS> Test-Remainder first one, two, three
Value = first
Found 3 remaining values
0: one
1: two
2: three
하나 이상이 컬렉션이 아닌 여러 값을 전달하면, 컬렉션은 단일 항목으로 취급돼요.
PS> Test-Remainder first one, two three four
Value = first
Found 3 remaining values
0: one two
1: three
2: four
HelpMessage 인자
HelpMessage 인자는 매개 변수나 그 값에 대한 간단한 설명을 담은 문자열을 지정해요. 필수 매개 변수 없이 명령을 실행하면 PowerShell이 입력을 요구해요. 도움말 메시지를 보려면 프롬프트에서 !?를 입력하고 Enter를 누르면 돼요.
다음 예시는 필수인 ComputerName 매개 변수와, 예상되는 매개 변수 값을 설명하는 도움말 메시지를 선언하고 있어요.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
출력 예시:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
함수에 주석 기반 도움말이 없으면, 이 메시지가 Get-Help -Full 출력에 표시돼요.
이 인자는 선택 매개 변수에는 아무 효과가 없어요.
DontShow 인자
DontShow 값은 주로, 제거할 수 없는 사용되지 않는 매개 변수가 있는 명령의 이전 버전 호환성을 지원하는 데 사용돼요. DontShow를 True로 설정하면 탭 확장과 IntelliSense에서 사용자에게 매개 변수가 숨겨져요.
PowerShell v7(이상)은 DontShow를 사용해서 다음과 같은 사용되지 않는 매개 변수를 숨겨요.
ConvertTo-Csv와Export-Csv의 NoTypeInformation 매개 변수Format-Hex의 Raw 매개 변수Invoke-RestMethod와Invoke-WebRequest의 UseBasicParsing 매개 변수
DontShow 인자에는 다음과 같은 부작용이 있어요.
DontShow가 사용되지 않는 매개 변수 집합이 있더라도, 연결된 매개 변수의 모든 매개 변수 집합에 영향을 줘요.- 탭 완성과 IntelliSense에서 공통 매개 변수를 숨겨요.
DontShow는 선택적인 공통 매개 변수인 WhatIf, Confirm, UseTransaction은 숨기지 않아요.
Alias 속성
Alias 속성은 매개 변수의 대체 이름을 설정해요. 매개 변수에 할당할 수 있는 별칭 수에는 제한이 없어요.
다음 예시는 필수인 ComputerName 매개 변수에 CN과 MachineName 별칭을 추가하는 매개 변수 선언을 보여줘요.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Credential 속성
Credential 속성은 매개 변수가 자격 증명(credential)을 받는다는 것을 나타내는 데 사용돼요. 다음 예시는 Credential 속성을 사용하는 매개 변수 선언을 보여줘요.
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Experimental 속성
Experimental 속성은 일부 코드를 실험적이라고 선언하는 데 사용해요. 속성에 대한 전체 설명은 about_Experimental_Features 문서를 참고해 주세요.
PSDefaultValue 속성
PSDefaultValue는 스크립트에서 명령 매개 변수의 기본값을 지정해요. 이 정보는 Get-Help cmdlet이 표시해요. 기본값 정보를 보려면 함수에 주석 기반 도움말이 포함되어 있어야 해요. 예를 들어:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Get-Help를 사용해서 기본값 정보를 확인할 수 있어요.
Get-Help TestDefaultValue -Parameter Name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
PSDefaultValue 속성 인자
PSDefaultValue 속성에는 두 가지 인자가 있어요.
- Help - 기본값을 설명하는 문자열이에요. 이 정보는
Get-Helpcmdlet이 표시해요. - Value - 매개 변수의 기본값이에요.
두 인자 모두 선택 사항이에요. 어떤 인자도 지정하지 않으면, Get-Help가 매개 변수에 할당된 값을 보여줘요.
PSTypeName 속성
형식 선언에서는 확장 형식 이름을 쓸 수 없어요. PSTypeName* 속성은 매개 변수 형식을 확장 형식으로 제한할 수 있게 해 줘요.
이 예시에서 Test-Connection cmdlet은 확장 형식을 반환해요. PSTypeName 속성을 사용해서 매개 변수 형식을 확장 형식으로 제한할 수 있어요.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
System.Obsolete 속성
System.Obsolete 속성은 더 이상 지원되지 않는 매개 변수를 표시하는 데 사용해요. 함수에서 매개 변수를 제거하고 싶지만, 그 함수를 사용하는 기존 스크립트를 깨뜨리고 싶지 않을 때 유용해요.
예를 들어 출력에 형식 정보를 포함할지 여부를 제어하는 NoTypeInformation [switch] 매개 변수가 있는 함수가 있다고 해 볼게요. 그 동작을 기본값으로 만들고 함수에서 매개 변수를 제거하고 싶은데, 기존 스크립트를 깨뜨리고 싶지는 않아요. 이럴 때 매개 변수를 사용되지 않음(obsolete)으로 표시하고 변경 내용을 설명하는 메시지를 추가하면 돼요.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[switch]$NoTypeInformation
)
SupportsWildcards 속성
SupportsWildcards 속성은 매개 변수가 와일드카드 값을 받는다는 것을 나타내는 데 사용돼요. 다음 예시는 와일드카드 값을 지원하는 필수 Path 매개 변수의 선언을 보여줘요.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
이 속성을 사용한다고 해서 와일드카드 지원이 자동으로 켜지지는 않아요. 와일드카드 입력을 처리하는 코드는 cmdlet 개발자가 구현해야 해요. 지원되는 와일드카드는 기반이 되는 API나 PowerShell 공급자에 따라 달라질 수 있어요. 자세한 내용은 about_Wildcards 문서를 참고해 주세요.
인자 완성 속성
ArgumentCompletions 속성
ArgumentCompletions 속성은 특정 매개 변수에 탭 완성 값을 추가할 수 있게 해 줘요. 탭 완성이 필요한 각 매개 변수마다 ArgumentCompletions 속성을 정의해야 해요. ArgumentCompletions 속성은 ValidateSet과 비슷한데요, 두 속성 모두 매개 변수 이름 다음에 사용자가 Tab을 누를 때 제시할 값 목록을 받아요. 다만 ValidateSet과 달리 값이 검증되지는 않아요.
이 속성은 PowerShell 6.0에서 도입됐어요.
자세한 내용은 about_Functions_Argument_Completion 문서를 참고해 주세요.
ArgumentCompleter 속성
ArgumentCompleter 속성은 특정 매개 변수에 탭 완성 값을 추가할 수 있게 해 줘요. 탭 완성이 필요한 각 매개 변수마다 ArgumentCompleter 속성을 정의해야 해요. 동적 매개 변수처럼, 사용 가능한 값은 매개 변수 이름 다음에 사용자가 Tab을 누를 때 런타임에 계산돼요.
자세한 내용은 about_Functions_Argument_Completion 문서를 참고해 주세요.
매개 변수 및 변수 유효성 검사 속성
유효성 검사 속성은 사용자가 고급 함수를 호출할 때 제출한 매개 변수 값을 PowerShell이 테스트하도록 지시해요. 매개 변수 값이 테스트를 통과하지 못하면 오류가 생성되고 함수가 호출되지 않아요. 매개 변수 유효성 검사는 제공된 입력에만 적용되며, 기본값 같은 다른 값은 검증되지 않아요.
또한 유효성 검사 속성을 사용해서 사용자가 변수에 지정할 수 있는 값을 제한할 수도 있어요.
[AllowNull()] [int]$number = 7
유효성 검사 속성은 매개 변수뿐 아니라 모든 변수에 적용할 수 있어요. 스크립트 안의 어떤 변수에든 유효성 검사를 정의할 수 있어요.
참고: 형식 지정 변수에서 어떤 속성을 사용하든, 속성을 형식 앞에 선언하는 것이 모범 사례예요.
속성과 변수 이름 앞에 줄 바꿈을 두고 형식을 선언하면, 그 형식 자체가 독립된 문으로 취급돼요.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
형식 뒤에 유효성 검사 속성을 선언하면, 할당되는 값이 형식 변환 전에 검증되어 예상치 못한 유효성 검사 실패가 발생할 수 있어요.
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
AllowNull 유효성 검사 속성
AllowNull 속성은 필수 매개 변수의 값이 $null이 될 수 있게 해 줘요. 다음 예시는 null 값을 가질 수 있는 hashtable ComputerInfo 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
참고: AllowNull 속성은 형식 변환기가 문자열로 설정된 경우에는 동작하지 않아요. 문자열 형식은 null 값을 받아들이지 않기 때문이에요. 이런 상황에서는 AllowEmptyString 속성을 사용하면 돼요.
AllowEmptyString 유효성 검사 속성
AllowEmptyString 속성은 필수 매개 변수의 값이 빈 문자열("")이 될 수 있게 해 줘요. 다음 예시는 빈 문자열 값을 가질 수 있는 ComputerName 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]$ComputerName
)
AllowEmptyCollection 유효성 검사 속성
AllowEmptyCollection 속성은 필수 매개 변수의 값이 빈 컬렉션 @()이 될 수 있게 해 줘요. 다음 예시는 빈 컬렉션 값을 가질 수 있는 ComputerName 매개 변수를 선언하고 있어요.
param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]$ComputerName
)
ValidateCount 유효성 검사 속성
ValidateCount 속성은 매개 변수가 받는 매개 변수 값의 최소 및 최대 개수를 지정해요. 함수를 호출하는 명령 안의 매개 변수 값 개수가 그 범위를 벗어나면 PowerShell이 오류를 생성해요.
다음 매개 변수 선언은 1개에서 5개까지의 매개 변수 값을 받는 ComputerName 매개 변수를 만들어요.
param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]$ComputerName
)
ValidateLength 유효성 검사 속성
ValidateLength 속성은 매개 변수나 변수 값의 최소 및 최대 문자 수를 지정해요. 매개 변수나 변수에 지정된 값의 길이가 범위를 벗어나면 PowerShell이 오류를 생성해요.
다음 예시에서 각 컴퓨터 이름은 1자에서 10자 사이여야 해요.
param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]$ComputerName
)
다음 예시에서 변수 $text의 값은 최소 1자, 최대 10자여야 해요.
[ValidateLength(1,10)] [string] $text = 'valid'
ValidatePattern 유효성 검사 속성
ValidatePattern 속성은 매개 변수나 변수 값과 비교할 정규식을 지정해요. 값이 정규식 패턴과 일치하지 않으면 PowerShell이 오류를 생성해요.
다음 예시에서 매개 변수 값은 네 자리 숫자를 포함해야 하고, 각 자릿수는 0부터 9까지의 숫자여야 해요.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
다음 예시에서 변수 $ticketID의 값은 정확히 네 자리 숫자여야 하고, 각 자릿수는 0부터 9까지의 숫자여야 해요.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
ValidateRange 유효성 검사 속성
ValidateRange 속성은 각 매개 변수나 변수 값에 대한 숫자 범위 또는 ValidateRangeKind 열거형 값을 지정해요. 값이 그 범위를 벗어나면 PowerShell이 오류를 생성해요.
ValidateRangeKind 열거형은 다음 값을 허용해요.
Positive- 0보다 큰 숫자예요.Negative- 0보다 작은 숫자예요.NonPositive- 0보다 작거나 같은 숫자예요.NonNegative- 0보다 크거나 같은 숫자예요.
다음 예시에서 Attempts 매개 변수의 값은 0과 10 사이여야 해요.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[int]$Attempts
)
다음 예시에서 변수 $number의 값은 0과 10 사이여야 해요.
[ValidateRange(0,10)] [int]$number = 5
다음 예시에서 변수 $number의 값은 0보다 커야 해요.
[ValidateRange("Positive")] [int]$number = 1
참고: 숫자 범위를 검증할 때는 범위 안의 값들이 매개 변수나 변수의 형식과 같도록 해야 해요. 다음 예시에서 범위 값은 정수인데 변수는 double이에요. 검증할 때 값이 정수(10)로 변환되기 때문에, 10.5라는 값이 0
10 범위를 벗어남에도 유효한 값이 돼요. 10.6도 정수로 변환되는데, 11이라는 값이 되면 010 범위를 벗어나서 오류가 생성돼요.
PS> [ValidateRange(0,10)] [double]$number = 10.5
PS> $number
10.5
PS> [ValidateRange(0,10)] [double]$number = 10.6
MetadataError: The variable cannot be validated because the value 10.6 is not a
valid value for the number variable.
형식 변환 시 발생하는 반올림 문제를 피하려면, 범위 값의 형식을 매개 변수나 변수의 형식과 일치하도록 지정할 수 있어요. 다음 예시에서는 범위 값이 double이어서 반올림 문제를 피할 수 있어요.
PS> [ValidateRange([double]0,[double]10)] [double]$number = 10.5
MetadataError: The variable cannot be validated because the value 10.5 is not a
valid value for the number variable.
ValidateScript 유효성 검사 속성
ValidateScript 속성은 매개 변수나 변수 값을 검증하는 데 사용할 스크립트를 지정해요. PowerShell이 값을 스크립트로 파이프하고, 스크립트가 $false를 반환하거나 예외를 던지면 오류를 생성해요.
ValidateScript 속성을 사용하면, 검증 중인 값이 $_ 변수에 매핑돼요. $_ 변수를 사용해서 스크립트 안에서 그 값을 참조할 수 있어요.
다음 예시에서 EventDate 매개 변수의 값은 현재 날짜보다 크거나 같아야 해요.
param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[datetime]$EventDate
)
다음 예시에서 변수 $date의 값은 현재 날짜 및 시간보다 작거나 같아야 해요.
[ValidateScript({$_ -le (Get-Date)})] [datetime]$date = (Get-Date)
참고: ValidateScript를 사용하면 매개 변수에
$null값을 전달할 수 없어요. null 값을 전달하면 ValidateScript가 인자를 검증할 수 없어요.
기본 오류 메시지 재정의
PowerShell 6부터는 지정된 값이 잘못된 경우 생성되는 기본 오류 메시지를 ErrorMessage 인자로 재정의할 수 있어요. 복합 형식 문자열을 지정하면 돼요. 0 인덱스 구성 요소는 입력 값을 사용하고, 1 인덱스 구성 요소는 입력 값을 검증하는 데 사용된 ScriptBlock을 사용해요.
다음 예시에서 EventDate 매개 변수의 값은 현재 날짜 및 시간보다 크거나 같아야 해요. 값이 잘못되면 오류 메시지가 지정된 날짜 및 시간이 너무 오래됐다고 알려줘요.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[datetime]$EventDate
)
지정된 값이 과거 날짜이면 사용자 지정 오류 메시지가 반환돼요.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
문자열에 선택적인 형식 문자열 구성 요소를 사용해서 추가 서식을 적용할 수 있어요.
다음 예시에서 EventDate 매개 변수의 값은 현재 날짜 및 시간보다 크거나 같아야 해요. 값이 잘못되면 오류 메시지가 지정된 날짜가 너무 오래됐다고 알려줘요.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[datetime]$EventDate
)
지정된 값이 과거 날짜이면 사용자 지정 오류 메시지가 반환돼요.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
ValidateSet 속성
ValidateSet 속성은 매개 변수나 변수에 허용되는 값 집합을 지정하고 탭 완성을 활성화해요. 매개 변수나 변수 값이 집합 안의 값과 일치하지 않으면 PowerShell이 오류를 생성해요. 다음 예시에서 Detail 매개 변수의 값은 Low, Average, High 중 하나만 될 수 있어요.
param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]$Detail
)
다음 예시에서 변수 $flavor의 값은 Chocolate, Strawberry, Vanilla 중 하나여야 해요.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
유효성 검사는 스크립트 안에서도 그 변수에 값을 할당할 때마다 발생해요. 예를 들어 다음 코드는 런타임에 오류를 발생시켜요.
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
이 예시는 런타임에 다음과 같은 오류를 반환해요.
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
ValidateSet을 사용하면 해당 매개 변수 값의 탭 확장도 활성화돼요. 자세한 내용은 about_Tab_Expansion 문서를 참고해 주세요.
클래스를 사용한 동적 ValidateSet 값
class를 사용해서 ValidateSet의 값을 런타임에 동적으로 생성할 수 있어요. 다음 예시에서는 세 개의 파일 시스템 경로에서 사용 가능한 사운드 파일을 확인하는 SoundNames라는 class를 통해 변수 $Sound의 유효한 값을 생성해요.
class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds','~/Library/Sounds'
$SoundNames = foreach ($SoundPath in $SoundPaths) {
if (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
그런 다음 [SoundNames] 클래스를 다음과 같이 동적 ValidateSet 값으로 구현해요.
param(
[ValidateSet([SoundNames])]
[string]$Sound
)
참고:
IValidateSetValuesGenerator클래스는 PowerShell 6.0에서 도입됐어요.
ValidateNotNull 유효성 검사 속성
ValidateNotNull 속성은 매개 변수 값이 $null이 될 수 없음을 지정해요. 값이 $null이면 PowerShell이 예외를 발생시켜요.
ValidateNotNull 속성은 매개 변수가 선택 사항이고 형식이 정의되지 않았거나, object처럼 null 값을 암시적으로 변환할 수 없는 형식 변환기를 가질 때 사용하도록 설계됐어요. string처럼 null 값을 암시적으로 변환하는 형식을 지정하면, ValidateNotNull 속성을 사용해도 null 값이 빈 문자열로 변환돼요. 이런 상황에서는 ValidateNotNullOrEmpty 속성을 사용하세요.
다음 예시에서 Id 매개 변수의 값은 $null이 될 수 없어요.
param(
[Parameter()]
[ValidateNotNull()]
$Id
)
ValidateNotNullOrEmpty 유효성 검사 속성
ValidateNotNullOrEmpty 속성은 할당된 값이 다음 값 중 어떤 것도 될 수 없음을 지정해요.
$null- 빈 문자열(
"") - 빈 배열(
@())
값이 잘못되면 PowerShell이 예외를 발생시켜요.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
ValidateNotNullOrWhiteSpace 유효성 검사 속성
ValidateNotNullOrWhiteSpace 속성은 할당된 값이 다음 값 중 어떤 것도 될 수 없음을 지정해요.
$null- 빈 문자열(
"") - 빈 배열
@() - 탭, 공백, 캐리지 리턴, 줄 바꿈처럼 공백 문자만 포함하는 문자열
- 빈 문자열이거나 공백 문자만 포함하는 문자열을 담은 배열
값이 잘못되면 PowerShell이 예외를 발생시켜요.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[string[]]$UserName
)
ValidateDrive 유효성 검사 속성
ValidateDrive 속성은 매개 변수 값이 허용된 드라이브만을 가리키는 경로를 나타내야 함을 지정해요. 매개 변수 값이 허용된 드라이브가 아닌 다른 드라이브를 가리키면 PowerShell이 오류를 생성해요. 드라이브 자체를 제외한 경로의 존재 여부는 확인되지 않아요.
상대 경로를 사용하면 현재 드라이브가 허용된 드라이브 목록에 있어야 해요.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
ValidateUserDrive 유효성 검사 속성
ValidateUserDrive 속성은 매개 변수 값이 User 드라이브를 나타내야 함을 지정해요. 경로가 다른 드라이브를 가리키면 PowerShell이 오류를 생성해요. 이 유효성 검사 속성은 경로의 드라이브 접두사 존재 여부만 테스트해요.
상대 경로를 사용하면 현재 드라이브가 User여야 해요.
function Test-UserDrivePath{
[OutputType([bool])]
param(
[Parameter(Mandatory, Position=0)]
[ValidateUserDrive()]
[string]$Path
)
$true
}
Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.
User 드라이브는 JEA(Just Enough Administration) 세션 구성에서 정의할 수 있어요. 이 예시에서는 User: 드라이브를 만들어 볼게요.
New-PSDrive -Name 'User' -PSProvider FileSystem -Root $Env:HOMEPATH
Name Used (GB) Free (GB) Provider Root
---- --------- --------- -------- ----
User 75.76 24.24 FileSystem C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
ValidateTrustedData 유효성 검사 속성
이 속성은 PowerShell 자체가 내부적으로 사용하며, 외부 사용을 위한 것이 아니에요.
이 속성은 PowerShell 6.1.1에서 추가됐어요.