about_Functions_Advanced_Parameters
간단한 설명
고급 함수에 매개 변수를 추가하는 방법을 설명합니다.
자세한 설명
작성하는 고급 함수에 매개 변수를 추가하고 매개 변수 특성 및 인수를 사용하여 함수 사용자가 매개 변수로 제출하는 매개 변수 값을 제한할 수 있습니다.
함수에 추가하는 매개 변수는 PowerShell이 모든 cmdlet 및 고급 함수에 자동으로 추가하는 일반적인 매개 변수 외에도 사용자가 사용할 수 있습니다. PowerShell 일반 매개 변수에 대한 자세한 내용은 about_CommonParameters 참조하세요.
PowerShell 3.0부터 스플래팅을 @Args 사용하여 명령의 매개 변수를 나타낼 수 있습니다. 스플래팅은 단순 및 고급 함수에서 유효합니다. 자세한 내용은 about_Functions 및 about_Splatting 참조하세요.
매개 변수 값의 형식 변환
문자열을 다른 형식을 예상하는 매개 변수에 인수로 제공하는 경우 PowerShell은 문자열을 매개 변수 대상 형식으로 암시적으로 변환합니다. 고급 함수는 매개 변수 값의 문화권 고정 구문 분석을 수행합니다.
반면, 컴파일된 cmdlet에 대한 매개 변수 바인딩 중에 문화권 구분 변환이 수행됩니다.
이 예제에서는 매개 변수를 사용하는 cmdlet 및 스크립트 함수를 만듭니다 [datetime] . 현재 문화권은 독일어 설정을 사용하도록 변경됩니다.
독일어 형식의 날짜가 매개 변수에 전달됩니다.
# 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."
정적 매개 변수
정적 매개 변수는 함수에서 항상 사용할 수 있는 매개 변수입니다. PowerShell cmdlet 및 스크립트의 대부분의 매개 변수는 정적 매개 변수입니다.
다음 예제에서는 다음과 같은 특성을 가진 ComputerName 매개 변수의 선언을 보여 줍니다.
- 필수(필수)입니다.
- 파이프라인에서 입력을 받습니다.
- 문자열 배열을 입력으로 사용합니다.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Switch 매개 변수
스위치 매개 변수는 매개 변수 값을 사용하지 않는 매개 변수입니다. 대신, 해당 존재 또는 부재를 통해 부울 true 또는 false 값을 전달하므로 스위치 매개 변수가 있을 때 실제 값이 있고 없는 경우 false 값이 있습니다.
예를 들어 Recurse 매개 변수는 Get-ChildItem switch 매개 변수입니다.
함수에서 switch 매개 변수를 만들려면 매개 변수 정의에 형식을 지정 switch 합니다.
예를 들어 함수에는 데이터를 바이트 배열로 출력하는 옵션이 있을 수 있습니다.
param([switch]$AsByteArray)
스위치 매개 변수는 사용하기 쉽고 PowerShell에 대한 덜 자연스러운 구문이 있는 부울 매개 변수보다 선호됩니다.
예를 들어 switch 매개 변수를 사용하려면 사용자가 명령에 매개 변수를 형식화합니다.
-IncludeAll
부울 매개 변수를 사용하려면 사용자가 매개 변수와 부울 값을 형식화합니다.
-IncludeAll $true
스위치 매개 변수를 만들 때 매개 변수 이름을 신중하게 선택합니다. 매개 변수 이름이 매개 변수의 효과를 사용자에게 전달해야 합니다. 값이 필요함을 암시할 수 있는 필터 또는 최대값과 같은 모호한 용어를 사용하지 않습니다.
매개 변수 디자인 고려 사항 전환
스위치 매개 변수는 기본값을 지정해서는 안 됩니다. 항상 false로 기본 설정해야 합니다.
스위치 매개 변수는 기본적으로 위치 매개 변수에서 제외됩니다. 다른 매개 변수가 암시적으로 위치가 있는 경우에도 스위치 매개 변수는 그렇지 않습니다. 매개 변수 특성에서 재정의할 수 있지만 사용자를 혼동합니다.
스위치 매개 변수를 설정하면 명령이 기본 동작에서 덜 일반적이거나 더 복잡한 모드로 이동되도록 디자인해야 합니다. 명령의 가장 간단한 동작은 스위치 매개 변수를 사용할 필요가 없는 기본 동작이어야 합니다.
스위치 매개 변수는 필수가 되어서는 안 됩니다. 스위치 매개 변수를 필수로 설정해야 하는 유일한 경우는 매개 변수 집합을 구분해야 하는 경우입니다.
부울
-MySwitch:$boolValue$params = @{ MySwitch = $boolValue }에서 스위치를 명시적으로 설정하는 작업은 .스위치 매개 변수는 암시적으로 부울로 변환되는 형식
SwitchParameter입니다. 매개 변수 변수는 조건식에서 직접 사용할 수 있습니다. 예시:if ($MySwitch) { ... }쓸 필요가 없습니다.
if ($MySwitch.IsPresent) { ... }
동적 매개 변수
동적 매개 변수는 특정 조건에서만 사용할 수 있는 cmdlet, 함수 또는 스크립트의 매개 변수입니다.
예를 들어 여러 공급자 cmdlet에는 공급자 드라이브 또는 공급자 드라이브의 특정 경로에서 cmdlet을 사용하는 경우에만 사용할 수 있는 매개 변수가 있습니다. 예를 들어 인코딩 매개 변수는 파일 시스템 드라이브에서 Add-Content사용되는 경우에만 , Get-Content및 Set-Content cmdlet에서 사용할 수 있습니다.
함수 명령에서 다른 매개 변수를 사용하거나 다른 매개 변수에 특정 값이 있는 경우에만 나타나는 매개 변수를 만들 수도 있습니다.
동적 매개 변수는 유용할 수 있지만 사용자가 검색하기 어려울 수 있으므로 필요한 경우에만 사용할 수 있습니다. 동적 매개 변수를 찾으려면 사용자가 공급자 경로에 있거나, cmdlet의 ArgumentList 매개 변수를 Get-Command 사용하거나, 의 Path 매개 변수Get-Help를 사용해야 합니다.
함수 또는 스크립트에 대한 동적 매개 변수를 만들려면 키워드(keyword) 사용합니다 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 특성이 포함되어야 합니다.
각 매개 변수 선언에 하나 이상의 특성을 추가할 수 있습니다. 매개 변수 선언에 추가할 수 있는 특성 수에는 제한이 없습니다.
매개 변수 특성
매개 변수 특성은 함수 매개 변수의 특성을 선언하는 데 사용됩니다.
매개 변수 특성은 선택 사항이며 함수의 매개 변수에 특성이 필요하지 않은 경우 생략할 수 있습니다. 그러나 단순 함수가 아닌 고급 함수로 인식되려면 함수에 CmdletBinding 특성 또는 매개 변수 특성 또는 둘 다 있어야 합니다.
매개 변수 특성에는 매개 변수의 특성(예: 매개 변수가 필수인지 선택 사항인지 여부)을 정의하는 인수가 있습니다.
다음 구문을 사용하여 매개 변수 특성, 인수 및 인수 값을 선언합니다. 인수와 해당 값을 묶는 괄호는 중간 공백 없이 Parameter를 따라야 합니다.
param(
[Parameter(Argument=value)]
$ParameterName
)
쉼표로 괄호 안의 인수를 구분합니다. 다음 구문을 사용하여 매개 변수 특성의 두 인수를 선언합니다.
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
매개 변수 특성에서 생략하면 매개 변수 특성의 부울 인수 형식이 기본적으로 False로 설정됩니다. 인수 값을 $true 이름으로 설정하거나 인수를 나열합니다. 예를 들어 다음 매개 변수 특성은 동일합니다.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
CmdletBinding 특성을 사용하는 대신 인수 없이 Parameter 특성을 사용하는 경우 특성 이름을 따르는 괄호는 여전히 필요합니다.
param(
[Parameter()]
$ParameterName
)
필수 인수
인수는 Mandatory 매개 변수가 필요하다는 것을 나타냅니다. 이 인수를 지정하지 않으면 매개 변수는 선택 사항입니다.
다음 예제에서는 ComputerName 매개 변수를 선언합니다. 인수를 Mandatory 사용하여 매개 변수를 필수로 만듭니다.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
위치 인수
인수는 Position 명령에서 매개 변수를 사용할 때 매개 변수 이름이 필요한지 여부를 결정합니다. 매개 변수 선언에 인수가 포함된 Position 경우 매개 변수 이름을 생략하고 PowerShell은 명령의 명명되지 않은 매개 변수 값 목록에서 이름 없는 매개 변수 값을 위치 또는 순서로 식별합니다.
인수를 Position 지정하지 않으면 매개 변수 이름 또는 매개 변수 이름 별칭 또는 약어가 명령에 매개 변수를 사용할 때마다 매개 변수 값 앞에 와야 합니다.
기본적으로 모든 함수 매개 변수는 위치입니다. PowerShell은 매개 변수가 함수에서 선언되는 순서대로 매개 변수에 위치 번호를 할당합니다.
이 기능을 사용하지 않도록 설정하려면 CmdletBinding 특성$False의 인수 값을 PositionalBinding .로 설정합니다. 인수는 Position CmdletBinding 특성의 PositionalBinding인수 값보다 우선합니다. 자세한 내용은 PositionalBindingabout_Functions_CmdletBindingAttribute 참조하세요.
인수의 Position 값은 정수로 지정됩니다. 위치 값 0 은 명령의 첫 번째 위치를 나타내고 위치 값 1 은 명령의 두 번째 위치를 나타냅니다.
함수에 위치 매개 변수가 없는 경우 PowerShell은 매개 변수가 선언된 순서에 따라 각 매개 변수에 위치를 할당합니다. 그러나 모범 사례로 이 할당에 의존하지 마세요. 매개 변수를 위치로 지정하려면 인수를 Position 사용합니다.
다음 예제에서는 ComputerName 매개 변수를 선언합니다. 값이 Position 0인 인수를 사용합니다. 따라서 -ComputerName 명령에서 생략된 경우 해당 값은 명령의 첫 번째 또는 명명되지 않은 매개 변수 값이어야 합니다.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName 인수
인수는 ParameterSetName 매개 변수가 속한 매개 변수 집합을 지정합니다. 매개 변수 집합이 지정되지 않은 경우 매개 변수는 함수에서 정의한 모든 매개 변수 집합에 속합니다. 고유하려면 각 매개 변수 집합에 다른 매개 변수 집합의 멤버가 아닌 매개 변수가 하나 이상 있어야 합니다.
참고 항목
cmdlet 또는 함수의 경우 매개 변수 집합이 32개로 제한됩니다.
다음 예제에서는 매개 변수 집합에서 ComputerName 매개 변수, 매개 변수 집합의 User UserName 매개 변수 및 두 매개 변수 집합의 Summary 매개 변수를 선언합니다.Computer
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
각 인수에 하나의 ParameterSetName 값만 지정하고 각 매개 변수 특성에 하나의 ParameterSetName 인수만 지정할 수 있습니다. 둘 이상의 매개 변수 집합에 매개 변수를 포함하려면 매개 변수 특성을 추가합니다.
다음 예제에서는 Summary 매개 변수를 명시적으로 및 User 매개 변수 집합에 Computer 추가합니다. 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
)
매개 변수 집합에 대한 자세한 내용은 매개 변수 집합 정보를 참조 하세요.
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 Valueby PropertyName)를 허용하는 형식화된 매개 변수를 사용하면 매개 변수에서 지연 바인딩 스크립트 블록을 사용할 수 있습니다.
지연 바인딩 스크립트 블록은 ParameterBinding 중에 자동으로 실행됩니다. 결과는 매개 변수에 바인딩됩니다. ScriptBlock 또는 System.Object 형식으로 정의된 매개 변수에는 지연 바인딩이 작동하지 않습니다. 스크립트 블록은 호출되지 않고 전달됩니다. 지연 바인딩 스크립트 블록에 대한 자세한 내용은 about_Script_Blocks 참조하세요.
ValueFromRe기본ingArguments 인수
인수는 ValueFromRemainingArguments 매개 변수가 함수의 다른 매개 변수에 할당되지 않은 명령의 모든 매개 변수 값을 허용한다는 것을 나타냅니다.
다음 예제에서는 필수 값 매개 변수와 함수에 제출된 모든 다시 기본 매개 변수 값을 허용하는 Re기본ing 매개 변수를 선언합니다.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$Remaining
)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
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 표시됩니다.
이 인수는 선택적 매개 변수에 영향을 주지 않습니다.
별칭 특성
별칭 특성은 매개 변수의 대체 이름을 설정합니다. 매개 변수에 할당할 수 있는 별칭 수에는 제한이 없습니다.
다음 예제에서는 필수 ComputerName 매개 변수에 CN 및 MachineName 별칭을 추가하는 매개 변수 선언을 보여 줍니다.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
자격 증명 특성
자격 증명 특성은 매개 변수가 자격 증명을 허용함을 나타내는 데 사용됩니다. 다음 예제에서는 자격 증명 특성을 사용하는 매개 변수 선언을 보여줍니다.
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
실험적 특성
실험적 특성을 사용하여 일부 코드를 실험적 코드로 선언합니다. 특성에 대한 전체 설명은 about_Experimental_Features 참조하세요.
PSDefaultValue 특성
PSDefaultValue는 스크립트에서 명령 매개 변수의 기본값을 지정합니다. 이 정보는 cmdlet에 Get-Help 의해 표시됩니다. 기본값 정보를 보려면 함수에 주석 기반 도움말이 포함되어야 합니다. 예시:
<#
.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 특성에는 두 개의 인수가 있습니다.
- 도움말 - 기본값을 설명하는 문자열입니다. 이 정보는 cmdlet에
Get-Help의해 표시됩니다. - 값 - 매개 변수의 기본값입니다.
두 인수는 모두 선택 사항입니다. 인수 Get-Help 를 지정하지 않으면 매개 변수에 할당된 값을 표시합니다.
PSTypeName 특성
형식 선언에서는 확장 형식 이름을 사용할 수 없습니다. PSTypeName* 특성을 사용하면 매개 변수의 형식을 확장된 형식으로 제한할 수 있습니다.
이 예제에서 cmdlet은 Test-Connection 확장 형식을 반환합니다. 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 스위치 매개 변수가 있는 함수를 고려해 보세요. 해당 동작을 기본값으로 만들고 함수에서 매개 변수를 제거하려고 합니다. 그러나 함수를 사용하는 기존 스크립트는 중단하지 않습니다. 매개 변수를 사용되지 않는 것으로 표시하고 변경 사항을 설명하는 메시지를 추가할 수 있습니다.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
SupportsWild카드s 특성
SupportsWild카드s 특성은 매개 변수가 wild카드 값을 허용함을 나타내는 데 사용됩니다. 다음 예제에서는 wild카드 값을 지원하는 필수 Path 매개 변수에 대한 매개 변수 선언을 보여 줍니다.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
이 특성을 사용하면 wild카드 지원이 자동으로 활성화되지 않습니다. cmdlet 개발자는 wild카드 입력을 처리하는 코드를 구현해야 합니다. 지원되는 야생 카드 기본 API 또는 PowerShell 공급자에 따라 달라질 수 있습니다. 자세한 내용은 about_Wild카드 참조하세요.
인수 완성 특성
ArgumentCompletions 특성
ArgumentCompletions 특성을 사용하면 탭 완성 값을 특정 매개 변수에 추가할 수 있습니다. Tab 완성이 필요한 각 매개 변수에 대해 ArgumentCompletions 특성을 정의해야 합니다. ArgumentCompletions 특성은 ValidateSet과 유사합니다. 두 특성 모두 사용자가 매개 변수 이름 뒤의 Tab 키를 누를 때 표시할 값 목록을 사용합니다. 그러나 ValidateSet과 달리 값의 유효성은 검사되지 않습니다.
이 특성은 PowerShell 6.0에서 도입되었습니다.
자세한 내용은 about_Functions_Argument_Completion 참조하세요.
ArgumentCompleter 특성
ArgumentCompleter 특성을 사용하면 탭 완성 값을 특정 매개 변수에 추가할 수 있습니다. Tab 완성이 필요한 각 매개 변수에 대해 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 값을 가질 수 있는 해시 테이블 ComputerInfo 매개 변수를 선언합니다.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
참고 항목
문자열 형식이 null 값을 허용하지 않으므로 형식 변환기가 문자열로 설정된 경우 AllowNull 특성이 작동하지 않습니다. 이 시나리오에서는 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에서 오류를 생성합니다.
다음 예제에서 매개 변수 값은 4자리 숫자를 포함해야 하며 각 숫자는 0에서 9까지여야 합니다.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
다음 예제에서 변수 $ticketID 값은 정확히 4자리 숫자여야 하며 각 숫자는 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
ValidateScript 유효성 검사 특성
ValidateScript 특성은 매개 변수 또는 변수 값의 유효성을 검사하는 데 사용되는 스크립트를 지정합니다. PowerShell은 값을 스크립트로 파이프하고 스크립트가 반환 $false 되거나 스크립트에서 예외를 throw하는 경우 오류를 생성합니다.
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 매개 변수의 값은 낮음, 평균 또는 높음일 수 있습니다.
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 값
클래스를 사용하여 런타임에 ValidateSet에 대한 값을 동적으로 생성할 수 있습니다. 다음 예제에서 변수 $Sound 의 유효한 값은 사용 가능한 사운드 파일에 대한 세 개의 파일 시스템 경로를 검사 SoundNames라는 클래스를 통해 생성됩니다.
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수 없음을 지정합니다. 값이면 $nullPowerShell에서 예외가 발생합니다.
ValidateNotNull 특성은 매개 변수가 선택 사항이고 형식이 정의되지 않았거나 개체와 같은 null 값을 암시적으로 변환할 수 없는 형식 변환기가 있을 때 사용하도록 설계되었습니다. 문자열과 같이 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.
JEA(Just Enough 관리istration) 세션 구성에서 드라이브를 정의 User 할 수 있습니다. 이 예제에서는 User: drive를 만듭니다.
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 6.1.1에 추가되었습니다.
현재 이 특성은 PowerShell 자체에서 내부적으로 사용되며 외부 사용을 위한 것이 아닙니다.
참고 항목
PowerShell
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기