about_Functions_Advanced_Parameters
업데이트 날짜: 2014년 5월
적용 대상: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
항목
여기에 섹션 본문을 삽입합니다.
간단한 설명
고급 함수에 매개 변수를 추가하는 방법을 설명합니다.
자세한 설명
작성한 고급 함수에 매개 변수를 추가하고 매개 변수 특성 및 인수를 사용하여 함수 사용자가 매개 변수와 함께 제출하는 매개 변수 값을 제한할 수 있습니다.
Windows PowerShell®에서 모든 cmdlet 및 고급 함수에 자동으로 추가하는 공통 매개 변수 이외에 함수에 추가하는 매개 변수가 사용자에게 제공됩니다. Windows PowerShell 공통 매개 변수에 대한 자세한 내용은 about_CommonParameters(https://go.microsoft.com/fwlink/?LinkID=113216)(영문)를 참조하세요.
Windows PowerShell 3.0부터 스플랫(splat)을 @Args와 함께 사용하여 명령에서 매개 변수를 나타낼 수 있습니다. 이 방법은 간단한 함수와 고급 함수에서 유효합니다. 자세한 내용은 about_Functions(https://go.microsoft.com/fwlink/?LinkID=113231)(영문) 및 about_Splatting(https://go.microsoft.com/fwlink/?LinkID=262720)(영문)을 참조하세요.
정적 매개 변수
정적 매개 변수는 함수에서 항상 사용할 수 있습니다. Windows PowerShell cmdlet 및 스크립트의 대부분 매개 변수는 정적 매개 변수입니다.
다음 예제에서는 다음과 같은 특성이 포함된 ComputerName 매개 변수의 선언을 보여 줍니다.
이 매개 변수는 필수입니다.
파이프라인에서 입력을 받아들입니다.
문자열 배열을 입력으로 받아들입니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
매개 변수 특성
이 섹션에서는 함수 매개 변수에 추가할 수 있는 특성을 설명합니다.
모든 특성은 선택 사항입니다. 하지만 CmdletBinding 특성을 생략할 경우 고급 함수로 인식되려면 함수에 Parameter 특성을 포함해야 합니다.
각 매개 변수 선언에 하나 이상의 특성을 추가할 수 있습니다. 매개 변수 선언에 추가할 수 있는 특성 수에는 제한이 없습니다.
PARAMETER 특성
Parameter 특성은 함수 매개 변수의 특성을 선언하는 데 사용됩니다.
Parameter 특성은 선택 사항이고 함수의 매개 변수에 특성이 필요하지 않으면 이 특성을 생략할 수 있지만, 간단한 함수가 아닌 고급 함수로 인식되려면 함수에 CmdletBinding attribute 또는 Parameter 특성을 포함하거나 두 특성을 모두 포함해야 합니다.
Parameter 특성에는 매개 변수가 필수 또는 선택 사항인지 여부 등의 매개 변수 특성을 정의하는 인수가 있습니다.
다음 구문을 사용하여 Parameter 특성, 인수 및 인수 값을 선언합니다. "Parameter" 뒤에 공백 없이 인수와 해당 값을 묶는 괄호가 추가되어야 합니다.
Param
(
[parameter(Argument=value)]
$ParameterName
)
쉼표를 사용하여 괄호 내에서 인수를 구분합니다. 다음 구문을 사용하여 Parameter 특성의 인수 두 개를 선언합니다.
Param
(
[parameter(Argument1=value1,
Argument2=value2)]
)
CmdletBinding 특성을 사용하지 않고 Parameter 특성을 매개 변수 없이 사용해도 특성 이름 뒤에 괄호가 필요합니다.
Param
(
[parameter()]
$ParameterName
)
Mandatory 인수
Mandatory 인수는 매개 변수가 필수임을 나타냅니다. 이 인수를 지정하지 않으면 매개 변수가 선택적 매개 변수입니다.
다음 예제에서는 ComputerName 매개 변수를 선언합니다. Mandatory 인수를 사용하여 매개 변수를 필수로 설정합니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Position 인수
Position 인수는 명령에서 매개 변수가 사용될 때 매개 변수 이름이 필수인지를 결정합니다. 매개 변수 선언에 Position 인수가 포함되면 매개 변수 이름을 생략할 수 있고 Windows PowerShell은 명령의 명명되지 않은 매개 변수 값 목록에서 명명되지 않은 매개 변수 값을 위치(또는 순서)로 식별합니다.
Position 인수를 지정하지 않으면 매개 변수가 명령에서 사용될 때마다 매개 변수 이름이나 매개 변수 이름 별칭 또는 약어가 매개 변수 값 앞에 추가되어야 합니다.
기본적으로 모든 함수 매개 변수는 위치 특징을 가집니다. Windows PowerShell에서는 함수에서 매개 변수가 선언되는 순서대로 매개 변수에 위치 번호를 할당합니다. 이 기능을 사용하지 않도록 설정하려면 CmdletBinding 특성의 PositionalBinding 인수 값을 $False로 설정합니다. Position 인수는 인수가 선언된 매개 변수에 대한 PositionalBinding 인수 값보다 우선합니다. 자세한 내용은 about_Functions_CmdletBindingAttribute에서 PositionalBinding을 참조하세요.
Position 인수 값은 정수로 지정됩니다. 위치 값 0은 명령에서 첫 번째 위치를 나타내고 위치 값 1은 명령에서 두 번째 위치를 나타냅니다.
함수에 위치 매개 변수가 없으면 Windows PowerShell에서는 매개 변수가 선언된 순서에 따라 각 매개 변수에 위치를 할당합니다. 그러나 이 인수에 의존하지 않는 것이 좋습니다. 매개 변수에 위치 특징을 사용하려면 Position 인수를 사용합니다.
다음 예제에서는 ComputerName 매개 변수를 선언합니다. Position 인수를 값 0과 함께 사용합니다. 따라서 명령에서 "-ComputerName"을 생략하면 해당 값은 명령에서 첫 번째의 유일한 명명되지 않은 매개 변수 값이어야 합니다.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
참고:
Get-Help cmdlet이 해당 "Position?" 매개 변수 특성을 표시하면 위치 값은 1씩 증분됩니다. 예를 들어 Position 인수 값이 0인 매개 변수에는 "Position? 1"의 매개 변수 특성이 있습니다.
ParameterSetName 인수
ParameterSetName 인수는 매개 변수가 속한 매개 변수 집합을 지정합니다. 매개 변수 집합을 지정하지 않으면 매개 변수가 함수에서 정의된 모든 매개 변수 집합에 속합니다. 따라서 매개 변수가 고유하려면 각 매개 변수 집합에는 다른 매개 변수 집합의 멤버가 아닌 하나 이상의 매개 변수가 있어야 합니다.
다음 예제에서는 Computer 매개 변수 집합의 ComputerName 매개 변수, User 매개 변수 집합의 UserName 매개 변수, 두 매개 변수 집합의 Summary 매개 변수를 선언합니다.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName,
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName,
[parameter(Mandatory=$false)]
[Switch]
$Summary
)
각 인수에서 ParameterSetName 값을 하나만 지정하고 각 Parameter 특성에서 ParameterSetName 인수를 하나만 지정할 수 있습니다. 매개 변수가 하나 이상의 매개 변수 집합에 나타나도록 지정하려면 또 다른 Parameter 특성을 추가합니다.
다음 예제에서는 Computer 및 User 매개 변수 집합에 Summary 매개 변수를 명시적으로 추가합니다. Summary 매개 변수는 한 매개 변수 집합에서 필수이고 다른 매개 변수 집합에서 선택 사항입니다.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName,
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName,
[parameter(Mandatory=$false, ParameterSetName="Computer")]
[parameter(Mandatory=$true, ParameterSetName="User")]
[Switch]
$Summary
)
매개 변수 집합에 대한 자세한 내용은 MSDN Library에서 "Cmdlet 매개 변수 집합"(https://go.microsoft.com/fwlink/?LinkId=142183)(영문)을 참조하세요.
ValueFromPipeline 인수
ValueFromPipeline 인수는 매개 변수가 파이프라인 개체에서 입력을 받아들이도록 지정합니다. 함수가 개체 속성이 아닌 전체 개체를 받아들이면 이 인수를 지정합니다.
다음 예제에서는 필수인 ComputerName 매개 변수를 선언하고 파이프라인에서 함수에 전달되는 개체를 받아들입니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
ValueFromPipelineByPropertyName 인수
valueFromPipelineByPropertyName 인수는 매개 변수가 파이프라인 개체의 속성에서 입력을 받아들이도록 지정합니다. 개체 속성은 매개 변수와 같은 이름 또는 별칭을 가집니다.
예를 들어 함수에 ComputerName 매개 변수가 있고 파이프된 개체에 ComputerName 속성이 있으면 ComputerName 속성 값이 함수의 ComputerName 매개 변수에 할당됩니다.
다음 예제에서는 필수인 ComputerName 매개 변수를 선언하고 파이프라인을 통해 함수에 전달되는 개체의 ComputerName 속성에서 입력을 받아들입니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)
ValueFromRemainingArguments 인수
ValueFromRemainingArguments 인수는 매개 변수가 함수의 다른 매개 변수에 할당되지 않은 명령의 모든 매개 변수 값을 받아들이도록 지정합니다.
다음 예제에서는 필수인 ComputerName 매개 변수를 선언하고 함수에 전송되지 않은 나머지 매개 변수 값을 모두 받아들입니다.
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)
HelpMessage 인수
HelpMessage 인수는 매개 변수 또는 해당 값의 간략한 설명이 포함된 문자열을 지정합니다. Windows PowerShell은 명령에서 필수 매개 변수 값이 누락될 때 나타나는 프롬프트에 이 메시지를 표시합니다. 이 인수는 선택적 매개 변수에 영향을 주지 않습니다.
다음 예제에서는 필수 ComputerName 매개 변수 및 예상 매개 변수 값을 설명하는 도움말 메시지를 선언합니다.
Param
(
[parameter(mandatory=$true,
HelpMessage="Enter one or more computer names separated by commas.")]
[String[]]
$ComputerName
)
ALIAS 특성
Alias 특성은 매개 변수의 대체 이름을 설정합니다. 매개 변수에 할당할 수 있는 별칭 수에는 제한이 없습니다.
다음 예제에서는 필수 ComputerName 매개 변수에 "CN" 및 "MachineName" 별칭을 추가하는 매개 변수 선언을 보여 줍니다.
Param
(
[parameter(Mandatory=$true)]
[alias("CN","MachineName")]
[String[]]
$ComputerName
)
매개 변수 및 변수 유효성 검사 특성
유효성 검사 특성은 Windows PowerShell에 사용자가 고급 함수를 호출할 때 전송하는 매개 변수 값을 테스트하도록 지시합니다. 매개 변수 값이 테스트에 실패하면 오류가 생성되고 함수가 호출되지 않습니다. 일부 유효성 검사 특성을 사용하여 사용자가 변수에 대해 지정할 수 있는 값을 제한할 수도 있습니다.
AllowNull 유효성 검사 특성
AllowNull 특성을 사용하여 필수 매개 변수 값을 null($null)로 설정할 수 있습니다. 다음 예제에서는 Null 값을 가질 수 있는 ComputerName 매개 변수를 선언합니다.
Param
(
[parameter(Mandatory=$true)]
[AllowNull()]
[String]
$ComputerName
)
AllowEmptyString 유효성 검사 특성
AllowEmptyString 특성을 사용하여 필수 매개 변수 값을 빈 문자열("")로 설정할 수 있습니다. 다음 예제에서는 빈 문자열 값을 가질 수 있는 ComputerName 매개 변수를 선언합니다.
Param
(
[parameter(Mandatory=$true)]
[AllowEmptyString()]
[String]
$ComputerName
)
AllowEmptyCollection 유효성 검사 특성
AllowEmptyCollection 특성을 사용하여 필수 매개 변수 값을 빈 컬렉션(@())으로 설정할 수 있습니다. 다음 예제에서는 빈 컬렉션 값을 가질 수 있는 ComputerName 매개 변수를 선언합니다.
Param
(
[parameter(Mandatory=$true)]
[AllowEmptyCollection()]
[String[]]
$ComputerName
)
ValidateCount 유효성 검사 특성
ValidateCount 특성은 매개 변수가 받아들이는 매개 변수 값의 최소 및 최대 개수를 지정합니다. Windows PowerShell에서는 함수를 호출하는 명령의 매개 변수 값 수가 해당 범위를 벗어나면 오류를 생성합니다.
다음 매개 변수 선언에서는 1~5개 매개 변수 값을 받아들이는 ComputerName 매개 변수를 만듭니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateCount(1,5)]
[String[]]
$ComputerName
)
ValidateLength 유효성 검사 특성
ValidateLength 특성은 매개 변수 또는 변수 값의 최소 및 최대 특성 수를 지정합니다. Windows PowerShell에서는 매개 변수 또는 변수에 대해 지정된 값의 길이가 범위를 벗어나면 오류를 생성합니다.
다음 예제에서 각 컴퓨터 이름에는 1~10자를 사용해야 합니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateLength(1,10)]
[String[]]
$ComputerName
)
다음 예제에서 $number 변수 값의 최소 길이는 1자이고 최대 길이는 10자입니다.
[Int32][ValidateLength(1,10)]$number = 01
ValidatePattern 유효성 검사 특성
ValidatePattern 특성은 매개 변수 또는 변수 값에 비교되는 정규식을 지정합니다. Windows PowerShell에서는 값이 정규식 패턴과 일치하지 않으면 오류를 생성합니다.
다음 예제에서는 매개 변수 값이 4자리 숫자여야 하고 각 숫자는 수 0~9의 하나여야 합니다.
Param
(
[parameter(Mandatory=$true)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[String[]]
$ComputerName
)
다음 예제에서는 $number 변수 값이 4자리 숫자여야 하고 각 숫자는 수 0~9의 하나여야 합니다.
[Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111
ValidateRange 유효성 검사 특성
ValidateRange 특성은 각 매개 변수 또는 변수 값의 숫자 범위를 지정합니다. Windows PowerShell에서는 값이 해당 범위를 벗어나면 오류를 생성합니다. 다음 예제에서는 Attempts 매개 변수 값이 0~10 사이여야 합니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
다음 예제에서는 $number 변수 값이 0~10 사이여야 합니다.
[Int32][ValidateRange(0,10)]$number = 5
ValidateScript 유효성 검사 특성
ValidateScript 특성은 매개 변수 또는 변수 값의 유효성을 검사하는 데 사용되는 스크립트를 지정합니다. Windows PowerShell에서는 값을 스크립트로 파이프하고 스크립트가 "false"를 반환하거나 스크립트가 예외를 throw하면 오류를 생성합니다.
ValidateScript 특성을 사용하면 유효성 검사되는 값이 $_ variable로 매핑됩니다. $_ 변수를 사용하여 스크립트에서 값을 참조할 수 있습니다.
다음 예제에서 EventDate 매개 변수 값은 현재 날짜보다 크거나 같아야 합니다.
Param
(
[parameter()]
[ValidateScript({$_ -ge (get-date)})]
[DateTime]
$EventDate
)
다음 예제에서 $date 변수 값은 현재 날짜 및 시간보다 크거나 같아야 합니다.
[DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)
ValidateSet 특성
ValidateSet 특성은 매개 변수 또는 변수에 대해 유효한 값 집합을 지정합니다. Windows PowerShell에서는 매개 변수 또는 변수 값이 집합의 값과 일치하지 않으면 오류를 생성합니다. 다음 예제에서는 Detail 매개 변수 값으로 "Low," "Average" 또는 "High"를 사용할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateSet("Low", "Average", "High")]
[String[]]
$Detail
)
다음 예제에서 $flavor 변수 값은 Chocolate, Strawberry 또는 Vanilla여야 합니다.
[String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry
ValidateNotNull 유효성 검사 특성
ValidateNotNull 특성은 매개 변수 값이 null($null)일 수 없도록 지정합니다. Windows PowerShell에서는 매개 변수 값이 null이면 오류를 생성합니다.
ValidateNotNull 특성은 매개 변수 값 형식을 지정하지 않거나 지정된 형식이 Null 값을 받아들일 때 사용되도록 디자인되었습니다. 문자열과 같은 null 값을 받아들이지 않는 형식을 지정할 경우 ValidateNotNull 특성이 없으면 지정된 형식과 일치하지 않으므로 null 값이 거부됩니다.
다음 예제에서 ID 매개 변수 값은 null일 수 없습니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateNotNull()]
$ID
)
ValidateNotNullOrEmpty 유효성 검사 특성
ValidateNotNullOrEmpty 특성은 매개 변수 값이 null($null)일 수 없고 빈 문자열("")일 수 없도록 지정합니다. Windows PowerShell에서는 매개 변수가 함수 호출에서 사용되지만 해당 값이 null, 빈 문자열 또는 빈 배열이면 오류를 생성합니다.
Param
(
[parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[String[]]
$UserName
)
동적 매개 변수
동적 매개 변수는 특정 조건에서만 사용할 수 있는 cmdlet, 함수 또는 스크립트의 매개 변수입니다.
예를 들어 여러 공급자 cmdlet에는 공급자 드라이브 또는 공급자 드라이브의 특정 경로에서 cmdlet이 사용될 때만 사용할 수 있는 매개 변수가 있습니다. 예를 들어 Encoding 매개 변수는 파일 시스템 드라이브에서 사용될 때만 Add-Content, Get-Content 및 Set-Content cmdlet에서 사용할 수 있습니다.
함수 명령에서 또 다른 매개 변수가 사용되거나 또 다른 매개 변수에 특정 값이 있을 때만 나타나는 매개 변수를 만들 수도 있습니다.
동적 매개 변수는 매우 유용하지만 사용자가 검색하기 어려울 수 있으므로 필요할 때만 사용할 수 있습니다. 동적 매개 변수를 찾으려면 사용자가 공급자 경로에 있고 Get-Command cmdlet의 ArgumentList 매개 변수를 사용하거나 Get-Help의 Path 매개 변수를 사용해야 합니다.
함수나 스크립트에 대한 동적 매개 변수를 만들려면 DynamicParam 키워드를 사용합니다.
구문은 다음과 같습니다.
DynamicParam {<statement-list>}
문 목록에서 If 문을 사용하여 함수에서 매개 변수를 사용할 수 있는 조건을 지정합니다.
New-Object cmdlet을 사용하여 매개 변수를 나타내는 System.Management.Automation.RuntimeDefinedParameter 개체를 만들고 이름을 지정합니다.
New-Object 명령을 사용하여 Mandatory, Position 또는 ValueFromPipeline과 같은 매개 변수 특성이나 매개 변수 집합을 나타내는 System.Management.Automation.ParameterAttribute 개체를 만들 수도 있습니다.
다음 예제에서는 Name 및 Path라는 표준 매개 변수와 DP1이라는 선택적 동적 매개 변수가 포함된 샘플 함수를 보여 줍니다. DP1 매개 변수는 PSet1 매개 변수 집합에 속하고 Int32 형식을 가집니다. Path 매개 변수 값에 HKEY_LOCAL_MACHINE 레지스트리 드라이브에서 사용 중임을 나타내는 "HKLM:"이 포함될 때만 DP1 매개 변수를 Sample 함수에서 사용할 수 있습니다.
function Get-Sample {
[CmdletBinding()]
Param ([String]$Name, [String]$Path)
DynamicParam
{
if ($path -match ".*HKLM.*:")
{
$attributes = new-object System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = "__AllParameterSets"
$attributes.Mandatory = $false
$attributeCollection = new-object `
-Type System.Collections.ObjectModel.Collection[System.Attribute]
$attributeCollection.Add($attributes)
$dynParam1 = new-object `
-Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
$paramDictionary = new-object `
-Type System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
return $paramDictionary
}
}
}
자세한 내용은 MSDN(Microsoft Developer Network) Library에서 "RuntimeDefinedParameter 클래스"(https://go.microsoft.com/fwlink/?LinkID=145130)(영문)를 참조하세요.
Switch 매개 변수
Switch 매개 변수는 매개 변수 값이 없는 매개 변수입니다. 이들 매개 변수는 사용될 때만 유효하고 한 가지 효과만 있습니다.
예를 들어 PowerShell.exe의 -NoProfile 매개 변수는 switch 매개 변수입니다.
함수에서 switch 매개 변수를 만들려면 매개 변수 정의에서 Switch 형식을 지정합니다.
For example:
Param ([Switch]<ParameterName>)
-or-
Param
(
[parameter(Mandatory=$false)]
[Switch]
$<ParameterName>
)
Switch 매개 변수는 사용하기 쉽고 더 어려운 구문이 포함된 Boolean 매개 변수보다 더 널리 사용됩니다.
예를 들어 switch 매개 변수를 사용하려면 사용자가 명령에 매개 변수를 입력합니다.
-IncludeAll
Boolean 매개 변수를 사용하려면 사용자가 매개 변수 및 Boolean 값을 입력합니다.
-IncludeAll:$true
switch 매개 변수를 만들 때 매개 변수 이름을 주의해서 선택합니다. 매개 변수 이름이 매개 변수의 효과를 사용자에게 전달하는지 확인하고 값이 필수임을 의미할 수 있는 Filter 또는 Maximum과 같은 모호한 용어를 사용하지 마세요.
참고 항목
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute