Sobre parâmetros avançados do Functions
Descrição breve
Explica como adicionar parâmetros a funções avançadas.
Descrição longa
Você pode adicionar parâmetros às funções avançadas que você escreve e usar atributos de parâmetro e argumentos para limitar os valores de parâmetro que os usuários da função enviam com o parâmetro .
Os parâmetros que você adiciona à sua função estão disponíveis para os usuários, além dos parâmetros comuns que o PowerShell adiciona automaticamente a todos os cmdlets e funções avançadas. Para obter mais informações sobre os parâmetros comuns do PowerShell, consulte about_CommonParameters.
A partir do PowerShell 3.0, você pode usar o splatting com @Args para representar os parâmetros em um comando. A modelagem é válida em funções simples e avançadas. Para obter mais informações, consulte about_Functions e about_Splatting.
Conversão de tipo de valores de parâmetro
Quando você fornece cadeias de caracteres como argumentos para parâmetros que esperam um tipo diferente, o PowerShell converte implicitamente as cadeias de caracteres no tipo de destino do parâmetro. As funções avançadas executam a análise invariável de cultura de valores de parâmetro.
Por outro lado, uma conversão sensível à cultura é executada durante a associação de parâmetros para cmdlets compilados.
Neste exemplo, criamos um cmdlet e uma função de script que usa um [datetime] parâmetro . A cultura atual é alterada para usar as configurações alemãs.
Uma data formatada em alemão é passada para o parâmetro .
# 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
Conforme mostrado acima, os cmdlets usam a análise sensível à cultura para converter a cadeia de caracteres.
# 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
As funções avançadas usam a análise invariável da cultura, o que resulta no erro a seguir.
Get-Date_Func : Cannot process argument transformation on parameter 'Date'. Cannot convert
value "19-06-2018" to type "System.DateTime". Error: "String was not recognized as a valid
DateTime."
At line:13 char:15
+ Get-Date_Func $dateStr
+ ~~~~~~~~
+ CategoryInfo : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
+ FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func
Parâmetros estáticos
Parâmetros estáticos são parâmetros que estão sempre disponíveis na função . A maioria dos parâmetros em cmdlets e scripts do PowerShell são parâmetros estáticos.
O exemplo a seguir mostra a declaração de um parâmetro ComputerName que tem as seguintes características:
- É obrigatório (obrigatório).
- Ele usa a entrada do pipeline.
- Ele usa uma matriz de cadeias de caracteres como entrada.
Param(
[Parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
Atributos de parâmetros
Esta seção descreve os atributos que você pode adicionar aos parâmetros de função.
Todos os atributos são opcionais. No entanto, se você omitir o atributo CmdletBinding , para ser reconhecido como uma função avançada, a função deverá incluir o atributo Parameter .
Você pode adicionar um ou vários atributos em cada declaração de parâmetro. Não há limite para o número de atributos que você pode adicionar a uma declaração de parâmetro.
Atributo de parâmetro
O atributo Parameter é usado para declarar os atributos dos parâmetros de função.
O atributo Parameter é opcional e você pode omitê-lo se nenhum dos parâmetros de suas funções precisar de atributos. Mas, para ser reconhecida como uma função avançada, em vez de uma função simples, uma função deve ter o atributo CmdletBinding ou o atributo Parameter ou ambos.
O atributo Parameter tem argumentos que definem as características do parâmetro, como se o parâmetro é obrigatório ou opcional.
Use a sintaxe a seguir para declarar o atributo Parameter , um argumento e um valor de argumento. Os parênteses que incluem o argumento e seu valor devem seguir Parâmetro sem espaço intermediário.
Param(
[Parameter(Argument=value)]
$ParameterName
)
Use vírgulas para separar argumentos entre parênteses. Use a sintaxe a seguir para declarar dois argumentos do atributo Parameter .
Param(
[Parameter(Argument1=value1,
Argument2=value2)]
)
Os tipos de argumento booliano do atributo Parameter são padrão para False quando omitidos do atributo Parameter . Defina o valor $true do argumento como ou apenas liste o argumento por nome. Por exemplo, os atributos Parameter a seguir são equivalentes.
Param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
Param(
[Parameter(Mandatory)]
)
Se você usar o atributo Parameter sem argumentos, como alternativa ao uso do atributo CmdletBinding , os parênteses que seguem o nome do atributo ainda serão necessários.
Param(
[Parameter()]
$ParameterName
)
Argumento obrigatório
O Mandatory argumento indica que o parâmetro é necessário. Se esse argumento não for especificado, o parâmetro será opcional.
O exemplo a seguir declara o parâmetro ComputerName . Ele usa o Mandatory argumento para tornar o parâmetro obrigatório.
Param(
[Parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Argumento Position
O Position argumento determina se o nome do parâmetro é necessário quando o parâmetro é usado em um comando. Quando uma declaração de parâmetro inclui o Position argumento , o nome do parâmetro pode ser omitido e o PowerShell identifica o valor do parâmetro sem nome por sua posição ou ordem, na lista de valores de parâmetro sem nome no comando.
Se o Position argumento não for especificado, o nome do parâmetro ou um alias ou abreviação de nome de parâmetro deverão preceder o valor do parâmetro sempre que o parâmetro for usado em um comando.
Por padrão, todos os parâmetros de função são posicionais. O PowerShell atribui números de posição a parâmetros na ordem em que os parâmetros são declarados na função. Para desabilitar esse recurso, defina o valor do PositionalBinding argumento do atributo CmdletBinding como $False. O Position argumento tem precedência sobre o valor do PositionalBinding argumento do atributo CmdletBinding . Para obter mais informações, consulte PositionalBinding em about_Functions_CmdletBindingAttribute.
O valor do Position argumento é especificado como um inteiro. Um valor de posição 0 representa a primeira posição no comando, um valor de posição de 1 representa a segunda posição no comando e assim por diante.
Se uma função não tiver parâmetros posicionais, o PowerShell atribuirá posições a cada parâmetro com base na ordem em que os parâmetros são declarados.
No entanto, como prática recomendada, não dependa dessa atribuição. Quando quiser que os parâmetros sejam posicionais, use o Position argumento .
O exemplo a seguir declara o parâmetro ComputerName . Ele usa o Position argumento com um valor de 0. Como resultado, quando -ComputerName é omitido do comando , seu valor deve ser o primeiro ou único valor de parâmetro sem nome no comando.
Param(
[Parameter(Position=0)]
[String[]]
$ComputerName
)
Argumento ParameterSetName
O ParameterSetName argumento especifica o conjunto de parâmetros ao qual um parâmetro pertence. Se nenhum conjunto de parâmetros for especificado, o parâmetro pertencerá a todos os conjuntos de parâmetros definidos pela função. Portanto, para ser exclusivo, cada conjunto de parâmetros deve ter pelo menos um parâmetro que não seja membro de nenhum outro conjunto de parâmetros.
Observação
Para um cmdlet ou função, há um limite de 32 conjuntos de parâmetros.
O exemplo a User seguir declara um parâmetro ComputerName no Computer conjunto de parâmetros, um parâmetro UserName no conjunto de parâmetros e um parâmetro Summary em ambos os conjuntos de parâmetros.
Param(
[Parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName,
[Parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName,
[Parameter(Mandatory=$false)]
[Switch]
$Summary
)
Você pode especificar apenas um ParameterSetName valor em cada argumento e apenas um ParameterSetName argumento em cada atributo Parameter . Para indicar que um parâmetro aparece em mais de um conjunto de parâmetros, adicione atributos parameter adicionais.
O exemplo a seguir adiciona explicitamente o parâmetro Summary aos Computer conjuntos de parâmetros e User . O parâmetro Summary é opcional no Computer conjunto de parâmetros e obrigatório no User conjunto de parâmetros.
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
)
Para obter mais informações sobre conjuntos de parâmetros, consulte Sobre conjuntos de parâmetros.
Argumento ValueFromPipeline
O ValueFromPipeline argumento indica que o parâmetro aceita a entrada de um objeto de pipeline. Especifique esse argumento se a função aceitar todo o objeto, não apenas uma propriedade do objeto .
O exemplo a seguir declara um parâmetro ComputerName obrigatório e aceita um objeto que é passado para a função do pipeline.
Param(
[Parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
Argumento ValueFromPipelineByPropertyName
O ValueFromPipelineByPropertyName argumento indica que o parâmetro aceita a entrada de uma propriedade de um objeto de pipeline. A propriedade do objeto deve ter o mesmo nome ou alias que o parâmetro .
Por exemplo, se a função tiver um parâmetro ComputerName e o objeto piped tiver uma propriedade ComputerName , o valor da propriedade ComputerName será atribuído ao parâmetro ComputerName da função.
O exemplo a seguir declara um parâmetro ComputerName obrigatório e aceita a entrada da propriedade ComputerName do objeto que é passada para a função por meio do pipeline.
Param(
[Parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)
Observação
Um parâmetro tipado que aceita entrada de pipeline (by Value) ou (by PropertyName) permite o uso de blocos de script de associação de atraso no parâmetro .
O bloco de script de associação de atraso é executado automaticamente durante ParameterBinding. O resultado está associado ao parâmetro . A associação de atraso não funciona para parâmetros definidos como tipo ScriptBlock ou System.Object. O bloco de script é passado sem ser invocado.
Você pode ler sobre blocos de script de associação de atraso aqui about_Script_Blocks.md.
Argumento ValueFromRemainingArguments
O ValueFromRemainingArguments argumento indica que o parâmetro aceita todos os valores do parâmetro no comando que não são atribuídos a outros parâmetros da função.
O exemplo a seguir declara um parâmetro Value obrigatório e um parâmetro Remaining que aceita todos os valores de parâmetro restantes que são enviados para a função.
function Test-Remainder
{
param(
[string]
[Parameter(Mandatory = $true, Position=0)]
$Value,
[string[]]
[Parameter(Position=1, ValueFromRemainingArguments)]
$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
Observação
Antes do PowerShell 6.2, a coleção ValueFromRemainingArguments era unida como uma única entidade no índice 0.
Argumento HelpMessage
O HelpMessage argumento especifica uma cadeia de caracteres que contém uma breve descrição do parâmetro ou seu valor. O PowerShell exibe essa mensagem no prompt que aparece quando um valor de parâmetro obrigatório está ausente de um comando. Esse argumento não tem efeito sobre parâmetros opcionais.
O exemplo a seguir declara um parâmetro ComputerName obrigatório e uma mensagem de ajuda que explica o valor esperado do parâmetro.
Se não houver outra sintaxe de ajuda baseada em comentário para a função (por exemplo, .SYNOPSIS), essa mensagem também aparecerá na Get-Help saída.
Param(
[Parameter(Mandatory=$true,
HelpMessage="Enter one or more computer names separated by commas.")]
[String[]]
$ComputerName
)
Atributo de alias
O atributo Alias estabelece um nome alternativo para o parâmetro . Não há limite para o número de aliases que você pode atribuir a um parâmetro.
O exemplo a seguir mostra uma declaração de parâmetro que adiciona os aliases CN e MachineName ao parâmetro ComputerName obrigatório.
Param(
[Parameter(Mandatory=$true)]
[Alias("CN","MachineName")]
[String[]]
$ComputerName
)
Atributo SupportsWildcards
O atributo SupportsWildcards é usado para indicar que o parâmetro aceita valores curinga. O exemplo a seguir mostra uma declaração de parâmetro para um parâmetro Path obrigatório que dá suporte a valores curinga.
Param(
[Parameter(Mandatory=$true)]
[SupportsWildcards()]
[String[]]
$Path
)
O uso desse atributo não habilita automaticamente o suporte a curingas. O desenvolvedor de cmdlets deve implementar o código para lidar com a entrada curinga. Os curingas com suporte podem variar de acordo com a API subjacente ou o provedor do PowerShell. Para obter mais informações, consulte about_Wildcards.
Atributos de validação de parâmetro e variável
Os atributos de validação direcionam o PowerShell para testar os valores de parâmetro que os usuários enviam quando chamam a função avançada. Se os valores de parâmetro falharem no teste, um erro será gerado e a função não será chamada. A validação de parâmetro só é aplicada à entrada fornecida e quaisquer outros valores, como valores padrão, não são validados.
Você também pode usar os atributos de validação para restringir os valores que os usuários podem especificar para variáveis. Quando você usa um conversor de tipo junto com um atributo de validação, o conversor de tipo deve ser definido antes do atributo .
[int32][AllowNull()] $number = 7
Atributo de validação AllowNull
O atributo AllowNull permite que o valor de um parâmetro obrigatório seja $null. O exemplo a seguir declara um parâmetro ComputerInfo que pode ter um valor nulo .
Param(
[Parameter(Mandatory=$true)]
[AllowNull()]
[hashtable]
$ComputerInfo
)
Observação
O atributo AllowNull não funcionará se o conversor de tipo estiver definido como cadeia de caracteres, pois o tipo de cadeia de caracteres não aceitará um valor nulo. Você pode usar o atributo AllowEmptyString para esse cenário.
Atributo de validação AllowEmptyString
O atributo AllowEmptyString permite que o valor de um parâmetro obrigatório seja uma cadeia de caracteres vazia (""). O exemplo a seguir declara um parâmetro ComputerName que pode ter um valor de cadeia de caracteres vazio.
Param(
[Parameter(Mandatory=$true)]
[AllowEmptyString()]
[String]
$ComputerName
)
Atributo de validação AllowEmptyCollection
O atributo AllowEmptyCollection permite que o valor de um parâmetro obrigatório seja uma coleção @()vazia. O exemplo a seguir declara um parâmetro ComputerName que pode ter um valor de coleção vazio.
Param(
[Parameter(Mandatory=$true)]
[AllowEmptyCollection()]
[String[]]
$ComputerName
)
Atributo de validação ValidateCount
O atributo ValidateCount especifica o número mínimo e máximo de valores de parâmetro que um parâmetro aceita. O PowerShell gerará um erro se o número de valores de parâmetro no comando que chama a função estiver fora desse intervalo.
A declaração de parâmetro a seguir cria um parâmetro ComputerName que usa de um a cinco valores de parâmetro.
Param(
[Parameter(Mandatory=$true)]
[ValidateCount(1,5)]
[String[]]
$ComputerName
)
Atributo de validação ValidateLength
O atributo ValidateLength especifica o número mínimo e máximo de caracteres em um valor de parâmetro ou variável. O PowerShell gerará um erro se o comprimento de um valor especificado para um parâmetro ou uma variável estiver fora do intervalo.
No exemplo a seguir, cada nome de computador deve ter de um a dez caracteres.
Param(
[Parameter(Mandatory=$true)]
[ValidateLength(1,10)]
[String[]]
$ComputerName
)
No exemplo a seguir, o valor da variável $number deve ter no mínimo um caractere de comprimento e um máximo de dez caracteres.
[Int32][ValidateLength(1,10)]$number = '01'
Observação
Neste exemplo, o valor de 01 é encapsulado entre aspas simples. O atributo ValidateLength não aceitará um número sem ser encapsulado entre aspas.
Atributo de validação ValidatePattern
O atributo ValidatePattern especifica uma expressão regular que é comparada com o parâmetro ou o valor da variável. O PowerShell gerará um erro se o valor não corresponder ao padrão de expressão regular.
No exemplo a seguir, o valor do parâmetro deve conter um número de quatro dígitos e cada dígito deve ser um número de zero a nove.
Param(
[Parameter(Mandatory=$true)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[String[]]
$ComputerName
)
No exemplo a seguir, o valor da variável $number deve ser exatamente um número de quatro dígitos e cada dígito deve ser um número de zero a nove.
[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111
Atributo de validação ValidateRange
O atributo ValidateRange especifica um intervalo numérico ou um valor de enumeração ValidateRangeKind para cada parâmetro ou valor de variável. O PowerShell gerará um erro se algum valor estiver fora desse intervalo.
A enumeração ValidateRangeKind permite os seguintes valores:
- Positivo – um número maior que zero.
- Negativo – um número menor que zero.
- Não Positivo – um número menor ou igual a zero.
- NonNegative - um número maior ou igual a zero.
No exemplo a seguir, o valor do parâmetro Attempts deve estar entre zero e dez.
Param(
[Parameter(Mandatory=$true)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
No exemplo a seguir, o valor da variável $number deve estar entre zero e dez.
[Int32][ValidateRange(0,10)]$number = 5
No exemplo a seguir, o valor da variável $number deve ser maior que zero.
[Int32][ValidateRange("Positive")]$number = 1
Atributo de validação ValidateScript
O atributo ValidateScript especifica um script que é usado para validar um parâmetro ou valor de variável. O PowerShell redireciona o valor para o script e gera um erro se o script retorna $false ou se o script gera uma exceção.
Quando você usa o atributo ValidateScript , o valor que está sendo validado é mapeado para a $_ variável . Você pode usar a $_ variável para se referir ao valor no script.
No exemplo a seguir, o valor do parâmetro EventDate deve ser maior ou igual à data atual.
Param(
[Parameter(Mandatory=$true)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]
$EventDate
)
No exemplo a seguir, o valor da variável $date deve ser maior ou igual à data e hora atuais.
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
Observação
Se você usar ValidateScript, não poderá passar um $null valor para o parâmetro . Quando você passa um valor nulo , ValidateScript não pode validar o argumento.
Atributo ValidateSet
O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável e habilita o preenchimento de tabulação. O PowerShell gerará um erro se um parâmetro ou valor de variável não corresponder a um valor no conjunto. No exemplo a seguir, o valor do parâmetro Detail só pode ser Baixo, Médio ou Alto.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet("Low", "Average", "High")]
[String[]]
$Detail
)
No exemplo a seguir, o valor da variável $flavor deve ser Chocolate, Morango ou Baunilha.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[String]$flavor = "Strawberry"
A validação ocorre sempre que essa variável é atribuída mesmo dentro do script. Por exemplo, o seguinte resulta em um erro em runtime:
Param(
[ValidateSet("hello", "world")]
[String]$Message
)
$Message = "bye"
Valores de validateSet dinâmicos
Você pode usar uma Classe para gerar dinamicamente os valores de ValidateSet em runtime. No exemplo a seguir, os valores válidos para a variável $Sound são gerados por meio de uma Classe chamada SoundNames que verifica três caminhos de sistema de arquivos para arquivos de som disponíveis:
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
}
}
Em [SoundNames] seguida, a classe é implementada como um valor validateSet dinâmico da seguinte maneira:
Param(
[ValidateSet([SoundNames])]
[String]$Sound
)
Atributo de validação ValidateNotNull
O atributo ValidateNotNull especifica que o valor do parâmetro não pode ser $null. O PowerShell gerará um erro se o valor do parâmetro for $null.
O atributo ValidateNotNull foi projetado para ser usado quando o parâmetro é opcional e o tipo é indefinido ou tem um conversor de tipo que não pode converter implicitamente um valor nulo como o objeto . Se você especificar um tipo que converterá implicitamente um valor nulo , como uma cadeia de caracteres, o valor nulo será convertido em uma cadeia de caracteres vazia mesmo ao usar o atributo ValidateNotNull . Para este cenário, use ValidateNotNullOrEmpty
No exemplo a seguir, o valor do parâmetro ID não pode ser $null.
Param(
[Parameter(Mandatory=$false)]
[ValidateNotNull()]
$ID
)
Atributo de validação ValidateNotNullOrEmpty
O atributo ValidateNotNullOrEmpty especifica que o valor do parâmetro não pode ser $null e não pode ser uma cadeia de caracteres vazia (""). O PowerShell gerará um erro se o parâmetro for usado em uma chamada de função, mas seu valor for $null, uma cadeia de caracteres vazia ("") ou uma matriz @()vazia .
Param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[String[]]
$UserName
)
Atributo de validação ValidateDrive
O atributo ValidateDrive especifica que o valor do parâmetro deve representar o caminho, que está se referindo apenas a unidades permitidas. O PowerShell gerará um erro se o valor do parâmetro se referir a unidades diferentes das permitidas. A existência do caminho, exceto pela própria unidade, não é verificada.
Se você usar o caminho relativo, a unidade atual deverá estar na lista de unidade permitida.
Param(
[ValidateDrive("C", "D", "Variable", "Function")]
[String]$Path
)
Atributo de validação ValidateUserDrive
O atributo ValidateUserDrive especifica que o valor do parâmetro deve representar o caminho, que está se referindo à User unidade. O PowerShell gerará um erro se o caminho se referir a uma unidade diferente. O atributo de validação só testa a existência da parte da unidade do caminho.
Se você usar o caminho relativo, a unidade atual deverá ser 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.
Você pode definir User a unidade em configurações de sessão JEA (Administração Just Enough). Para este exemplo, criamos a unidade Usuário: .
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
```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
Atributo de validação ValidateTrustedData
Esse atributo foi adicionado ao PowerShell 6.1.1.
Neste momento, o atributo é usado internamente pelo próprio PowerShell e não se destina ao uso externo.
Parâmetros dinâmicos
Parâmetros dinâmicos são parâmetros de um cmdlet, função ou script que estão disponíveis somente em determinadas condições.
Por exemplo, vários cmdlets de provedor têm parâmetros disponíveis somente quando o cmdlet é usado na unidade do provedor ou em um caminho específico da unidade do provedor. Por exemplo, o parâmetro Decodificação está disponível nos Add-Contentcmdlets , Get-Contente Set-Content somente quando é usado em uma unidade do sistema de arquivos.
Você também pode criar um parâmetro que aparece somente quando outro parâmetro é usado no comando de função ou quando outro parâmetro tem um determinado valor.
Os parâmetros dinâmicos podem ser úteis, mas usá-los somente quando necessário, pois podem ser difíceis de descobrir pelos usuários. Para encontrar um parâmetro dinâmico, o usuário deve estar no caminho do provedor, usar o parâmetro ArgumentList do Get-Command cmdlet ou usar o parâmetro Path de Get-Help.
Para criar um parâmetro dinâmico para uma função ou script, use o DynamicParam palavra-chave.
A sintaxe é mostrada a seguir:
DynamicParam {<statement-list>}
Na lista de instruções, use uma instrução If para especificar as condições sob as quais o parâmetro está disponível na função.
Use o New-Object cmdlet para criar um objeto System.Management.Automation.RuntimeDefinedParameter para representar o parâmetro e especificar seu nome.
Você pode usar um New-Object comando para criar um objeto System.Management.Automation.ParameterAttribute para representar atributos do parâmetro, como Mandatory, Position ou ValueFromPipeline ou seu conjunto de parâmetros.
O exemplo a seguir mostra uma função de exemplo com parâmetros padrão chamados Nome e Caminho e um parâmetro dinâmico opcional chamado DP1. O parâmetro DP1 está no PSet1 conjunto de parâmetros e tem um tipo de Int32.
O parâmetro DP1 está disponível na Get-Sample função somente quando o valor do parâmetro Path começa com HKLM:, indicando que ele está sendo usado na unidade do HKEY_LOCAL_MACHINE Registro.
function Get-Sample {
[CmdletBinding()]
Param([String]$Name, [String]$Path)
DynamicParam
{
if ($Path.StartsWith("HKLM:"))
{
$attributes = New-Object -Type `
System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = "PSet1"
$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
}
}
}
Para obter mais informações, consulte RuntimeDefinedParameter.
Parâmetros de opção
Parâmetros de comutador são parâmetros sem valor de parâmetro. Eles são eficazes somente quando são usados e têm apenas um efeito.
Por exemplo, o parâmetro NoProfile de powershell.exe é um parâmetro de comutador.
Para criar um parâmetro switch em uma função, especifique o Switch tipo na definição de parâmetro.
Por exemplo:
Param([Switch]<ParameterName>)
Ou você pode usar outro método:
Param(
[Parameter(Mandatory=$false)]
[Switch]
$<ParameterName>
)
Os parâmetros de comutador são fáceis de usar e são preferenciais em relação aos parâmetros boolianos, que têm uma sintaxe mais difícil.
Por exemplo, para usar um parâmetro de opção, o usuário digita o parâmetro no comando .
-IncludeAll
Para usar um parâmetro booliano, o usuário digita o parâmetro e um valor booliano.
-IncludeAll:$true
Ao criar parâmetros de comutador, escolha o nome do parâmetro com cuidado. Verifique se o nome do parâmetro comunica o efeito do parâmetro para o usuário. Evite termos ambíguos, como Filtro ou Máximo , o que pode implicar que um valor é necessário.
Atributo ArgumentCompleter
O atributo ArgumentCompleter permite que você adicione valores de conclusão de guia a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que precisa de conclusão da guia. Semelhante a DynamicParameters, os valores disponíveis são calculados em runtime quando o usuário pressiona Tab após o nome do parâmetro.
Para adicionar um atributo ArgumentCompleter , você precisa definir um bloco de script que determina os valores. O bloco de script deve usar os seguintes parâmetros na ordem especificada abaixo. Os nomes do parâmetro não importam, pois os valores são fornecidos posicionalmente.
A sintaxe é mostrada a seguir:
Param(
[Parameter(Mandatory)]
[ArgumentCompleter({
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
# Perform calculation of tab completed values here.
})]
)
Bloco de script ArgumentCompleter
Os parâmetros de bloco de script são definidos com os seguintes valores:
$commandName(Posição 0) – Esse parâmetro é definido como o nome do comando para o qual o bloco de script está fornecendo a conclusão da guia.$parameterName(Posição 1) – esse parâmetro é definido como o parâmetro cujo valor requer a conclusão da guia.$wordToComplete(Posição 2) – esse parâmetro é definido como valor que o usuário forneceu antes de pressionar Tab. O bloco de script deve usar esse valor para determinar os valores de conclusão da guia.$commandAst(Posição 3) – esse parâmetro é definido como AST (Árvore de Sintaxe Abstrata) para a linha de entrada atual. Para obter mais informações, consulte Classe Ast.$fakeBoundParameters(Posição 4) – esse parâmetro é definido como um hashtable que contém o$PSBoundParameterspara o cmdlet, antes que o usuário pressione Tab. Para obter mais informações, consulte about_Automatic_Variables.
O bloco de script ArgumentCompleter deve cancelar o registro dos valores usando o pipeline, como ForEach-Object, Where-Objectou outro método adequado.
Retornar uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão de guia.
O exemplo a seguir adiciona o preenchimento de guia ao parâmetro Value . Se apenas o parâmetro Value for especificado, todos os valores ou argumentos possíveis para Value serão exibidos. Quando o parâmetro Type é especificado, o parâmetro Value exibe apenas os valores possíveis para esse tipo.
Além disso, o -like operador garante que, se o usuário digitar o comando a seguir e usar a conclusão da guia, somente a Apple será retornada.
Test-ArgumentCompleter -Type Fruits -Value A
function Test-ArgumentCompleter {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ValidateSet('Fruits', 'Vegetables')]
$Type,
[Parameter(Mandatory=$true)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
$possibleValues = @{
Fruits = @('Apple', 'Orange', 'Banana')
Vegetables = @('Tomato', 'Squash', 'Corn')
}
if ($fakeBoundParameters.ContainsKey('Type'))
{
$possibleValues[$fakeBoundParameters.Type] | Where-Object {
$_ -like "$wordToComplete*"
}
}
else
{
$possibleValues.Values | ForEach-Object {$_}
}
} )]
$Value
)
}
Confira também
about_Functions_Advanced_Methods