항목
about_Functions_Advanced_Parameters
간단한 설명
CmdletBinding 특성을 선언하는 함수에 정적 및 동적 매개 변수를 추가하는 방법을 설명합니다.
자세한 설명
함수를 작성할 때 매개 변수를 직접 선언할 수 있으며, 컴파일된 cmdlet에 사용할 수 있는 일반 매개 변수에
액세스할 수 있도록 함수를 작성할 수 있습니다. Windows PowerShell 일반 매개 변수에 대한 자세한
내용은 about_CommonParameters를 참조하십시오.
정적 매개 변수
다음 예에서는 ComputerName 매개 변수를 정의하는 매개 변수 선언을 보여 줍니다. 이 매개 변수는
다음과 같은 특징이 있습니다.
- 필수 매개 변수입니다.
- 파이프라인으로부터 입력을 받습니다.
- 문자열 배열을 입력으로 받습니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
매개 변수를 선언할 때 반드시 사용해야 하는 유일한 필수 특성은 Parameter 특성입니다. 그러나 Alias
특성과 여러 개의 유효성 검사 인수를 선언할 수도 있습니다. 매개 변수 선언에 추가할 수 있는 특성 수에는
제한이 없습니다.
매개 변수 특성
Parameter 특성은 함수의 매개 변수를 선언할 때 사용합니다.
이 특성에는 매개 변수가 필수인지 아니면 선택 사항인지 여부와 같은 매개 변수의 특징을 정의하는 데
사용하는 다음과 같은 명명된 인수가 있습니다.
Mandatory 명명된 인수
Mandatory 인수는 함수가 실행될 때 매개 변수가 필수인지 여부를 나타냅니다. 이 인수를 지정하지
않으면 선택적 매개 변수가 됩니다. 다음 예에서는 함수가 실행될 때 필요한 매개 변수 선언을 보여
줍니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Position 명명된 인수
Position 인수는 매개 변수의 위치를 지정합니다. 이 인수를 지정하지 않은 경우에는 매개 변수를 설정할
때 매개 변수 이름이나 해당 별칭을 명시적으로 지정해야 합니다. 또한 함수의 매개 변수에 위치가 없는
경우 Windows PowerShell 런타임은 매개 변수를 받은 순서를 기준으로 각 매개 변수에 위치를 할당합니다.
다음 예에서는 cmdlet을 실행할 때 값을 첫 번째 인수로 지정해야 하는 매개 변수의 선언을 보여 줍니다.
매개 변수 이름을 지정하거나 지정하지 않고 이 함수를 실행할 수 있습니다.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
ParameterSetName 명명된 인수
ParameterSetName 인수는 매개 변수가 속하는 매개 변수 집합을 지정합니다. 지정된 매개 변수 집합이
없으면 매개 변수는 함수를 통해 정의된 모든 매개 변수 집합에 속하게 됩니다. 이 동작은 매개 변수
집합마다 다른 매개 변수 집합의 멤버가 아닌 고유한 매개 변수가 하나씩 있어야 함을 의미합니다. 다음
예에서는 서로 다른 두 매개 변수 집합에 속하는 두 매개 변수의 매개 변수 선언을 보여 줍니다.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName
)
Param
(
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName
)
매개 변수 집합에 대한 자세한 내용은 MSDN
라이브러리(https://go.microsoft.com/fwlink/?LinkId=142183)의 "Cmdlet
Parameter Sets(Cmdlet 매개 변수 집합)"를 참조하십시오.
ValueFromPipeline 명명된 인수
ValueFromPipeline 인수는 매개 변수가 파이프라인 개체로부터 입력을 받도록 지정합니다. Cmdlet이
개체의 속성이 아니라 전체 개체에 액세스하는 경우 이 인수를 지정합니다. 다음 예에서는
파이프라인에서 함수에 전달된 입력 개체를 받는 필수 ComputerName 매개 변수의 매개 변수 선언을 보여
줍니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
ValueFromPipelineByPropertyName 명명된 인수
valueFromPipelineByPropertyName 인수는 매개 변수가 파이프라인 개체의 속성으로부터
입력을 받도록 지정합니다. 다음 조건에 해당되는 경우 이 특성을 지정합니다.
- 매개 변수가 파이프된 개체의 속성에 액세스할 경우
- 속성이 매개 변수와 동일한 이름을 갖거나 매개 변수와 동일한 별칭을 가질 경우
예를 들어 함수에 ComputerName 매개 변수가 있고 파이프된 개체에 ComputerName 속성이 있을 경우
ComputerName 속성 값이 함수의 ComputerName 매개 변수에 할당됩니다.
다음 예에서는 cmdlet에 전달된 입력 개체의 ComputerName 속성으로부터 입력을 받는 ComputerName
매개 변수의 매개 변수 선언을 보여 줍니다.
Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)
ValueFromRemainingArguments 명명된 인수
ValueFromRemainingArguments 인수는 매개 변수가 함수의 매개 변수에 바인딩되지 않는 나머지 인수를
모두 받도록 지정합니다. 다음 예에서는 함수에 전달된 입력 개체의 나머지 인수를 모두 받는
ComputerName 매개 변수의 매개 변수 선언을 보여 줍니다.
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)
HelpMessage 명명된 인수
HelpMessage 인수는 매개 변수에 대한 간략한 설명이 포함된 메시지를 지정합니다. 다음 예에서는
매개 변수에 대해 설명하는 매개 변수 선언을 보여 줍니다.
Param
(
[parameter(Mandatory=$true,
HelpMessage=”An array of computer names.”)]
[String[]]
$ComputerName
)
별칭 특성
별칭 특성은 매개 변수에 대한 다른 이름을 지정합니다. 매개 변수에 할당할 수 있는 별칭 수에는 제한이
없습니다. 다음 예에서는 ComputerName 매개 변수에 "CN" 별칭을 추가하는 필수 매개 변수 선언을
보여 줍니다.
Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)
매개 변수 유효성 검사 특성
이러한 특성은 Windows PowerShell 런타임에서 고급 함수의 인수 유효성을 어떻게 검사하는지를
정의합니다.
AllowNull 유효성 검사 특성
AllowNull 특성을 사용하면 필수 cmdlet 매개 변수의 인수를 Null로 설정할 수 있습니다. 다음 예에서는
ComputerName 매개 변수가 필수 매개 변수이더라도 이 매개 변수에 Null 값을 포함할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowNull()]
$ComputerName
)
AllowEmptyString 유효성 검사 특성
AllowEmptyString 특성을 사용하면 빈 문자열을 필수 cmdlet 매개 변수의 인수로 사용할 수 있습니다.
다음 예에서는 ComputerName 매개 변수가 필수 매개 변수이더라도 이 매개 변수에 빈
문자열("")을 포함할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowEmptyString()]
$ComputerName
)
AllowEmptyCollection 유효성 검사 특성
AllowEmptyCollection 특성을 사용하면 빈 컬렉션을 필수 매개 변수의 인수로 사용할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[AllowEmptyCollection()]
$ComputerName
)
ValidateCount 유효성 검사 특성
ValidateCount 특성은 매개 변수가 받을 수 있는 인수의 최소 및 최대 개수를 지정합니다. 인수 개수가 이
범위를 초과하면 Windows PowerShell 런타임에서 오류를 생성합니다. 다음 예에서는 ComputerName 매개
변수에 1 - 5개의 인수를 사용할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)
ValidateLength 유효성 검사 특성
ValidateLength 특성은 매개 변수 인수의 최소 및 최대 길이를 지정합니다. 매개 변수 인수의 길이가 이
범위를 초과하면 Windows PowerShell 런타임에서 오류를 생성합니다.
다음 예에서 지정된 컴퓨터 이름은 1 - 10자여야 합니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateLength(1,10)]
$ComputerName
)
ValidatePattern 유효성 검사 특성
ValidatePattern 특성은 매개 변수 인수의 패턴에 대한 유효성을 검사하는 정규식을 지정합니다. 매개 변수
인수가 이 패턴과 일치하지 않으면 Windows PowerShell 런타임에서 오류를 생성합니다. 다음 예에서는
매개 변수의 인수가 4자리 숫자여야 하고, 각 자리는 0부터 9까지의 숫자여야 합니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
$ComputerName
)
ValidateRange 유효성 검사 특성
ValidateRange 특성은 매개 변수 인수의 최소값과 최대값을 지정합니다. 매개 변수 인수가 이 범위를
초과하면 Windows PowerShell 런타임에서 오류를 생성합니다. 다음 예에서는 매개 변수의 인수가
0보다 작거나 10보다 클 수 없습니다.
Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)
ValidateScript 유효성 검사 특성
ValidateScript 특성은 매개 변수 인수의 유효성을 검사하는 데 사용되는 스크립트를 지정합니다.
스크립트 결과가 false이거나 스크립트가 예외를 throw하면 Windows PowerShell 런타임에서
오류를 생성합니다. 다음 예에서는 Count 매개 변수의 값이 4보다 작아야 합니다.
Param
(
[parameter()]
[Int]
[ValidateScript({$_ -lt 4})]
$Count
)
ValidateSet 특성
ValidateSet 특성은 매개 변수의 인수에 대한 유효한 값 집합을 지정합니다. 매개 변수 인수가 집합의
값과 일치하지 않으면 Windows PowerShell 런타임에서 오류를 생성합니다.
다음 예에서는 매개 변수 인수에 Steve, Mary 및 Carl이라는 이름만 사용할 수 있습니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateRange(“Steve”, “Mary”, “Carl”)]
$UserName
)
ValidateNotNull 유효성 검사 특성
ValidateNotNull 특성은 매개 변수의 인수를 Null로 설정할 수 없도록 지정합니다. 매개 변수 값이
Null이면 Windows PowerShell 런타임에서 오류를 생성합니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNull()]
$UserName
)
ValidateNotNullOrEmpty 유효성 검사 특성
ValidateNotNullOrEmpty 특성은 매개 변수의 인수를 Null로 설정할 수 없거나 비워 둘 수 없도록
지정합니다. 매개 변수를 지정했지만 해당 값이 Null이거나, 빈 문자열이거나, 빈 배열인 경우 Windows
PowerShell 런타임은 오류를 생성합니다.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNullOrEmpty()]
$UserName
)
동적 매개 변수
동적 매개 변수는 특정 조건에서만 사용할 수 있는 cmdlet, 함수 또는 스크립트의 매개 변수입니다.
예를 들어, 일부 공급자 cmdlet에는 공급자 경로에서 cmdlet을 사용하는 경우에만 사용할 수 있는
매개 변수가 있습니다. 친숙한 동적 매개 변수 중 하나는 FileSystem 공급자 경로에서
Set-Item cmdlet을 사용하는 경우에만 사용할 수 있는 cmdlet인 Set-Item의 Encoding 매개 변수입니다.
함수 또는 스크립트에 대한 동적 매개 변수를 만들려면 DynamicParam 키워드를 사용하십시오.
구문은 다음과 같습니다.
DynamicParam {<statement-list>}
문 목록에서는 If 문을 사용하여 함수에 사용할 수 있는 매개 변수의 조건을 지정합니다.
New-Object cmdlet을 사용하여 System.Management.Automation.RuntimeDefinedParameter 개체를
만들어 매개 변수를 나타내고 이름을 지정합니다.
New-Object 명령을 사용하여 System.Management.Automation.ParameterAttribute 개체를 만들어
Mandatory, Position, ValueFromPipeline 또는 해당 매개 변수 집합과 같은 매개 변수의 특성을
나타낼 수도 있습니다.
다음 예제에서는 Name와 Path라는 표준 매개 변수 및 DP1이라는 선택적 동적 매개 변수를 포함하는
Sample 함수를 보여 줍니다. DP1 매개 변수는 PSet1 매개 변수 집합에 들어 있고 Int32 유형입니다.
DP1 매개 변수는 Path 매개 변수 값이 HKEY_LOCAL_MACHINE 레지스트리 드라이브에서 사용되고
있음을 나타내는 "HKLM:"을 포함하는 경우에만 Sample 함수에서 사용할 수 있습니다.
function Sample {
Param ([String]$Name, [String]$Path)
DynamicParam
{
if ($path -match "*HKLM*:")
{
$dynParam1 = new-object
System.Management.Automation.RuntimeDefinedParameter("dp1",
[Int32], $attributeCollection)
$attributes = new-object System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = 'pset1'
$attributes.Mandatory = $false
$attributeCollection = new-object
-Type System.Collections.ObjectModel.Collection``1[System.Attribute]
$attributeCollection.Add($attributes)
$paramDictionary = new-object
System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
return $paramDictionary
} End if
}
}
자세한 내용은 MSDN(Microsoft Developer Network) 라이브러리의 "RuntimeDefinedParameter Class
(RuntimeDefinedParameter 클래스)"(https://go.microsoft.com/fwlink/?LinkID=145130)를 참조하십시오.
참고 항목
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute