About Functions Advanced Parameters (Português)

• 10/27/2020
• 20 minutes to read
• • S
  • s
  • s
  • c
  • g

Short description

Explains how to add parameters to advanced functions.,

descrição longa

pode adicionar parâmetros às funções avançadas que escreve, e atributos e argumentos do useparameter para limitar os valores dos parâmetros que os utilizadores do functionusers submetem com o parâmetro.

os parâmetros que adiciona à sua função estão disponíveis para os utilizadores, para além dos parâmetros comuns que o PowerShell adiciona automaticamente a todos os cmdlets e funções avançadas. Para mais informações sobre o PowerShell commonparameters, consulte about_ CommonParameters.

começando em PowerShell 3.,0, você pode usar splatting com @Args para representar os parâmetros em um comando. Splatting é válido em funções simples e avançadas. Para mais informações, consulte about_Functions eabout_splatting.

tipo de conversão dos valores dos parâmetros

quando você fornece strings como argumentos para parâmetros que esperam um tipo diferente, PowerShell implicitamente converte as strings para o tipo alvo do parâmetro.Funções avançadas executam análise invariante de cultura dos valores dos parâmetros.

Por outro lado, uma conversão sensível à cultura é realizada durante a parameterbinding para cmdlets compilados.,

neste exemplo, criamos um cmdlet e uma função de script que tomam um parâmetro. A cultura atual é alterada para usar configurações em alemão.Uma data formatada em alemão é passada para o parâmetro.

Dienstag, 19. Juni 2018 00:00:00

conforme mostrado acima, cmdlets usam análise sensível à cultura para converter a cadeia de caracteres.

funções avançadas usam análise de cultura invariante, o que resulta no seguinte erro.

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 PowerShell cmdlets e scripts são parâmetros estáticos.

o exemplo seguinte mostra a declaração de um parametro Computacional que tem as seguintes características:

• É obrigatório (obrigatório).
• recebe entrada do gasoduto.
• É necessário um array de strings como entrada.

Param( ] $ComputerName)

atributos dos parâmetros

Esta secção descreve os atributos que pode adicionar aos parâmetros da função.

todos os atributos são facultativos., No entanto, se você omitir o CmdletBindingattribute, então para ser reconhecido como uma função avançada, a função deve incluir o atributo parâmetro.

pode adicionar um ou vários atributos em cada declaração de parâmetros. Não há limite para o número de atributos que você pode adicionar a uma parameterdeclaração.

atributo do parâmetro

o atributo do parâmetro é utilizado para declarar os atributos dos functionparameters.

o atributo do parâmetro é opcional, e você pode omiti-lo se nenhum dos parâmetros das suas funções necessitar de atributos., Mas, para ser reconhecida como uma função avançada, ao invés de uma função simples, uma função deve ter o atributo CmdletBinding ou o atributo parâmetro, ou ambos.

o atributo do parâmetro tem argumentos que definem as características do parâmetro, tais como se o parâmetro é obrigatório ou facultativo.

Use a seguinte sintaxe para declarar o atributo do parâmetro, um argumento e um valor de argumento. Os parênteses que encerram o argumento e o seu valor devem seguir o parâmetro sem espaço de intervenção.,

Param( $ParameterName)

Use vírgulas para separar os argumentos entre parênteses. Use o followingsyntax para declarar dois argumentos do atributo parâmetro.

Param( )

the boolean argument types of the Parameter attribute default to Falsewhen omitted from the Parameter attribute. Definir o valor do argumento para$true ou simplesmente listar o argumento pelo nome. Por exemplo, os atributos followingParameter são equivalentes.,

Se você usar o atributo do parâmetro sem argumentos, como uma alternativa para usar o atributo CmdletBinding, os parêntesis que seguem o nome do theatrtribute ainda são necessários.

Param( $ParameterName)

argumento Obrigatório

Mandatory argumento indica que o parâmetro é necessário. Se este documento não for especificado, o parâmetro é opcional.

o exemplo seguinte declara o parâmetro ComputerName. Ele usa o argumentoMandatory para tornar o parâmetro obrigatório.,

Param( ] $ComputerName)

argumento da posição

o Position argumento determina se o nome do parâmetro é necessário quando o parâmetro é usado num comando. Quando uma declaração de parâmetro inclui o argumentoPosition, o nome do parâmetro pode ser omitido e PowerShell identifica o valor do parâmetro sem nome pela sua posição, ou ordem, na lista de valores do parâmetro sem nome no comando.,

Se o argumento Position não for especificado, o nome do parâmetro, ou uma alcunha parametername ou abreviatura, deve preceder o valor do parâmetro sempre que o Parameter for usado num comando.

Por padrão, todos os parâmetros da função são posicionais. PowerShell atribui números de posicões a Parâmetros na ordem em que os parâmetros são declarados na função. Para desactivar esta funcionalidade, defina o valor do PositionalBindingargumento do atributo CmdletBinding para$False., O argumento Positiontem precedência sobre o valor do PositionalBinding argumento do atributo CmdletBinding. Para mais informações, ver PositionalBindingin about_Functions_CmdletBindingAttribute.

o valor do argumento Position é especificado como um inteiro. Um valor de posição de 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 tem parâmetros posicionais, PowerShell atribui posições a cada parâmetro com base na ordem em que os parâmetros são declarados.No entanto, como uma boa prática, não confie nesta missão. Quando quiser que os parâmetros sejam posicionais, use o argumento Position.

o exemplo seguinte declara o parâmetro ComputerName. Ele usa o argumentoPosition com um valor de 0. Como resultado, quando -ComputerName isomited from command, its value must be the first or only unnamed parametervalue in the command.,

Param( ] $ComputerName)

ParameterSetName argumento

ParameterSetName argumento especifica o conjunto de parâmetro para que aparameter pertence. Se nenhum conjunto de Parâmetros for especificado, o parâmetro pertence a todos os conjuntos de parâmetros definidos pela função. Portanto, para ser único, o conjunto eachparameter deve ter pelo menos um parâmetro que não é um membro de qualquer outro conjunto parameter.

O exemplo a seguir declara um parâmetro ComputerName Computerparâmetro definido um parâmetro de nome de usuário User conjunto de parâmetros, e aSummary parâmetro em ambos os conjuntos de parâmetros.

pode indicar apenas umParameterSetName valor em cada argumento e apenas umParameterSetName argumento em cada atributo do parâmetro. Para indicar que aparameter aparece em mais de um conjunto de parâmetros, adicione parâmetros adicionais.,

o exemplo seguinte adiciona explicitamente o parâmetro resumo aos conjuntos de parâmetrosComputer e User. O parâmetro de resumo é opcional no parâmetro Computer conjunto de parâmetros e obrigatório no parâmetro User conjunto de parâmetros.

para mais informações sobre conjuntos de parâmetros, veja sobre Conjuntos de Parâmetros.

ValueFromPipeline argumento

ValueFromPipeline argumento indica que o parâmetro aceita inputfrom um objeto de pipeline., Especifique este argumento se a função aceita o objeto principal, não apenas uma propriedade do objeto.

o seguinte exemplo declara um parâmetro Computacional que é mandatoria e aceita um objeto que é passado para a função a partir do pipeline.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argumento

ValueFromPipelineByPropertyName argumento indica que o parameteraccepts de entrada de uma propriedade de um objeto de pipeline. A propriedade objeto mosthave o mesmo nome ou alias que o parâmetro.,

Por exemplo, se a função tem um parâmetro Computacional, e o pipedobject tem uma propriedade computacional, o valor do Computameproperty é atribuído ao parâmetro ComputerName da função.

o exemplo seguinte declara um parâmetro Computacional que é mandatoria e aceita entrada da propriedade computacional do objeto que é passada para a função através do pipeline.,

Param( ] $ComputerName)

ValueFromRemainingArguments argumento

ValueFromRemainingArguments argumento indica que o parâmetro acceptsall o parâmetro valores no comando que não são atribuídas a otherparameters da função.

o exemplo seguinte declara um parâmetro de valor que é obrigatório e um parâmetro em curso que aceita todos os restantes valores dos parâmetros que são submetidos à função.

HelpMessage argumento

HelpMessage argumento especifica uma cadeia de caracteres que contém uma breve descriptionof o parâmetro ou o seu valor. PowerShell mostra esta mensagem no prompt que aparece quando falta um valor de parâmetro obrigatório num comando. Este documento não tem qualquer efeito nos parâmetros opcionais.

o exemplo seguinte declara um parâmetro computacional obrigatório e uma mensagem ahelp que explica o valor esperado do parâmetro.,

Se não houver nenhum outro comentário em ajudar syntaxfor a função (por exemplo, .SYNOPSIS), então, esta mensagem aparece, também, naGet-Help saída.

Param( ] $ComputerName)

Alias atributo

o atributo “Alias” estabelece um nome alternativo para o parâmetro.Não há limite para o número de nomes falsos que você pode atribuir a um parâmetro.

o exemplo seguinte mostra uma declaração de parâmetros que adiciona os pseudónimos CN e macachinename ao parâmetro ComputerName obrigatório.,

Param( ] $ComputerName)

SupportsWildcards attribute

The SupportsWildcards attribute is used to indicate that the parameteracepts wildcard values. O exemplo seguinte mostra uma declaração de parâmetros para um parâmetro Path obrigatório que suporta valores de caracteres especiais.

Param( ] $Path)

usar este atributo não activa automaticamente o Suporte de caracteres especiais. O desenvolvimento de cmdlet deve implementar o código para lidar com a entrada de caracteres especiais. O wildcardsupported pode variar de acordo com a API ou provedor PowerShell subjacente. Formore information, see about_Wildcards.,

parâmetro e atributos de validação das variáveis

validação atributos “PowerShell” directos para testar os valores dos parâmetros que os utilizadores apresentam quando chamam a função avançada. Se os valores dos parâmetros falharem, um erro é gerado e a função não é chamada. A validação do parâmetro só é aplicada à entrada fornecida e quaisquer outros valores como valores por defeito não são validados.

Você também pode usar os atributos de validação para restringir os valores que os utilizadores podem especificar para variáveis., Quando você usa um conversor de tipo junto com o atributo avalidation, o Conversor de tipo tem que ser definido antes do atributo.

 $number = 7

AllowNull validação atributo

O AllowNull atributo permite que o valor de um parâmetro obrigatório para ser$null. O exemplo seguinte declara um parameter de informação computacional com hashtable que pode ter um valor nulo.

Param( $ComputerInfo)

AllowEmptyString validation attribute

The AllowEmptyString attribute allows the value of a mandatory parameter to be an empty string (""). O exemplo seguinte declara um ComputerNameparameter que pode ter um valor de cadeia vazia.

Param( $ComputerName)

AllowEmptyCollection validação atributo

O AllowEmptyCollection atributo permite que o valor de um mandatoryparameter para ser uma coleção vazia @()., O seguinte exemplo declara um parâmetro deomputername que pode ter um valor de coleção vazio.

Param( ] $ComputerName)

ValidateCount validação atributo

O ValidateCount atributo especifica o número mínimo e máximo ofparameter valores de um parâmetro aceita. PowerShell gera um erro se o número de valores de parâmetro no comando que chama a função está fora do intervalo.

a seguinte declaração de parâmetro cria um parâmetro de computador que toma um a cinco valores de parâmetro.,

Param( ] $ComputerName)

validatelength validatelength validation attribute

o atributo ValidateLength especifica o número mínimo e máximo de caracteres num parâmetro ou valor variável. PowerShell gera um erro se o comprimento de um valor especificado para um parâmetro ou uma variável está fora da variação.

no exemplo seguinte, cada nome de computador deve ter um a dez caracteres.

Param( ] $ComputerName)

No exemplo a seguir, o valor da variável $number deve ser um minimumof um caractere de comprimento e um máximo de dez caracteres.,

$number = '01'

validatepattern valid attribute

o atributo ValidatePattern especifica uma expressão regular que ‘ corresponde ao parâmetro ou valor variável. PowerShell gera 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 zero a nove.

Param( ")] ] $ComputerName)

No exemplo a seguir, o valor da variável $number deve ser exatamente afour dígitos do número, e cada dígito deve ser um número de zero a nove.

$")]$number = 1111

validaterange validation attribute

o atributo ValidateRange especifica uma gama numérica ou um valor aValidateRangeKind enum para cada parâmetro ou valor variável.PowerShell gera um erro se algum valor estiver fora desse intervalo.,

o enum ValidateRangeKind permite os seguintes valores:

• positivo – um número superior a zero.negativo-um número inferior a zero.
• Não-positivo-um número inferior ou igual a zero.
• Nnegativo-um número maior ou igual a zero.

no exemplo seguinte, o valor do parâmetro tentativas deve estar entre zero e dez.

Param( $Attempts)

No exemplo seguinte, o valor da variável $number deve ser entreenzero e dez.,

$number = 5

No exemplo a seguir, o valor da variável $number deve ser maior-que zero.

$number = 1

validatescript validation attribute

o atributo ValidateScript especifica um programa que é usado para validar um aparameter ou um valor variável. PowerShell canaliza o valor para o script, e torna-se um erro se o script retorna $false ou se o script lança uma excepção.,

Quando você usa o atributo ValidateScript, o valor que está sendo validatis 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 do que ou igual à data atual.

Param( $EventDate)

no exemplo seguinte, o valor da variável $date deve ser maior do que a data e hora atuais.,

$date = (Get-Date)

validateset atributo

o atributo ValidateSet especifica um conjunto de valores válidos para uma variável parameteror e activa a completação da página. PowerShell gera um erro se um aparameter ou valor variável não corresponder a um valor no conjunto. No exemplo seguinte, o valor do parâmetro de detalhe só pode ser baixo, médio ou elevado.,

Param( ] $Detail)

No exemplo a seguir, o valor da variável $flavor deve ser eitherChocolate, Morango ou Baunilha.

$flavor = "Strawberry"

a validação ocorre sempre que essa variável é atribuída mesmo dentro do script. Por exemplo, os seguintes resultados em um erro no tempo de execução:

Param( $Message)$Message = "bye"

valores de validateSet dinâmicos

você pode usar uma classe para gerar dinamicamente os valores para a execução de ValidateSetat., No exemplo a seguir, os valores válidos para a variável$Sound são gerados através de uma Classe chamada SoundNames que verifica threefilesystem caminhos disponíveis para arquivos de som:

classe é então implementado como uma dinâmica ValidateSet valueas seguinte:

Param( )] $Sound)

ValidateNotNull validação atributo

O ValidateNotNull atributo especifica que o valor do parâmetro não pode ser$null. PowerShell gera um erro se o valor do parâmetro for $null.,

o atributo ValidateNotNull foi concebido para ser usado quando o parâmetro é opcional e o tipo não está definido ou tem um conversor de tipo que pode ‘ simplesmente converter um valor nulo como um objecto. Se você especificar um tipo que irá converter implicitamente um valor nulo como uma string, o valor nulo é convertido para uma string vazia, mesmo quando se usa o ValidateNotNullattribute. Para este cenário, use a Validatenotnullorearmpty

no exemplo seguinte, o valor do parâmetro ID não pode ser $null.,

Param( $ID)

ValidateNotNullOrEmpty validação atributo

O ValidateNotNullOrEmpty atributo especifica que o parâmetro valuecan não ser $null e não pode ser uma cadeia de caracteres vazia (""). PowerShell gera umnerro se o parâmetro for usado em uma chamada de função, mas seu valor é $null, anempty string (""), ou uma matriz vazia @().,

Param( ] $UserName)

validatedrive validation attribute

o atributo ValidateDrive especifica que o valor do parâmetro deve representar o path, isto é, apenas as unidades autorizadas. PowerShellgenerates an error if the parameter value refers to drives other than theallowed. A existência do caminho, exceto a própria unidade, não é verificada.

Se você usar caminho relativo, a unidade atual deve estar na lista de unidades permitidas.,

Param( $Path)

ValidateUserDrive validação atributo

O ValidateUserDrive atributo especifica que o valor do parâmetro mustrepresent o caminho, que está se referindo User unidade. PowerShell gera anerror se o caminho se refere a uma unidade diferente. O atributo de validação apenas menciona a existência da parte do percurso.

Se você usar o caminho relativo, a unidade atual deve ser User.,

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument 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'. Cannotfind drive. A drive with the name 'User' does not exist.

Você pode definir User unidade em Apenas Suficiente Administração (JEA) sessionconfigurations. Para este exemplo, criamos o Usuário: drive.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH

True

ValidateTrustedData validação atributo

Este atributo foi adicionado em PowerShell 6.1.1.

neste momento, o atributo é usado internamente pelo próprio PowerShell e não é pretendido para uso externo.,

parâmetros dinâmicos

parâmetros dinâmicos são parâmetros de um cmdlet, função ou script que só podem ser encontrados sob certas condições.

por exemplo, vários cmdlets do provedor têm parâmetros que estão disponíveis apenas quando o cmdlet é usado na unidade do provedor, ou em um caminho particular da unidade provider. Por exemplo, o parâmetro de Codificação está disponível noAdd-Content Get-Content e Set-Content cmdlets apenas quando é usado ina unidade de sistema de arquivo.,

Você também pode criar um parâmetro que aparece apenas quando outro parâmetro é usado no comando da função ou quando outro parâmetro tem um certo valor.

parâmetros dinâmicos podem ser úteis, mas usá-los apenas quando necessário, porque podem ser difíceis de descobrir para os usuários. Para encontrar um parâmetro dinâmico, o Usuário deve estar no caminho do provedor, usar o parâmetro ArgumentList doGet-Command cmdlet, ou usar o parâmetro Path de Get-Help.

para criar um parâmetro dinâmico para uma função ou programa, use a palavra-chave DynamicParam.,

A sintaxe é a seguinte:

DynamicParam {<statement-list>}

Na lista de instrução, use um If instrução para especificar as condições underwhich o parâmetro está disponível na função.

Use the New-Object cmdlet to create aSystem.Gestao.Automacao.Objeto definido de execução para representar o parâmetro e especificar o seu nome.

pode usar um comando New-Object para criar o sistema.Gestao.Automacao.,Objeto parametrizado para representar contribuições do parâmetro, tais como obrigatório, posição, ouvalor deompipelina ou seu conjunto de parâmetros.

o exemplo seguinte mostra uma função de exemplo com os parâmetros padrão nomedname e Path, e um parâmetro dinâmico opcional chamado DP1. Thedp1 parameter is in the PSet1 parameter set and has a type of Int32.,O parâmetro DP1 está disponível na função Get-Sample apenas quando o valor do parâmetro Path começa com HKLM:, indicando que é utilizado na unidade HKEY_LOCAL_MACHINE registry drive.

para mais informações, veja um parâmetro definido a tempo.

os parâmetros de comutação

os parâmetros de comutação são parâmetros sem valor de parâmetro. São eficazes apenas quando são usados e têm apenas um efeito.

Por exemplo, o parâmetro NoProfile de powershell.o exe é um interruptor.,

para criar um parâmetro de comutação numa função, especifique o Switch tipo na definição do parâmetro.

Por exemplo:

Param(<ParameterName>)

Ou, você pode usar um outro método:

Param( $<ParameterName>)

os parâmetros de opção são fáceis de usar e têm preferência sobre os parâmetros Booleanos,que têm mais dificuldade de sintaxe.

Por exemplo, para usar um parâmetro de comutação,o usuário digita o parâmetro no comando.

-IncludeAll

para utilizar um parâmetro booleano, o utilizador escreve o parâmetro e um valor booleano.,

-IncludeAll:$true

ao criar parâmetros de comutação, escolha cuidadosamente o nome do parâmetro. Seja certo que o nome do parâmetro comunica o efeito do parâmetro ao usuário.Evite Termos ambíguos, tais como filtro ou máximo que pode implicar avalue é necessário.

atributo ArgumentCompleter

o atributo ArgumentCompleter permite-lhe adicionar valores de completação de tabelas a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que necessita de completação de tabelas., À semelhança do DynamicParameters, os valores disponíveis são calculados em tempo de execução, quando o utilizador carrega em Tab após o nome do parâmetro.

para adicionar um atributo argument completo, você precisa definir um bloco de script que determina os valores. O bloco de script deve tomar os seguintes parâmetros na ordem indicada abaixo. Os nomes dos parâmetros não importam pois os valores são fornecidos de forma posicional.,

A sintaxe é a seguinte:

ArgumentCompleter bloco de script

O bloco de script parâmetros são definidos para os seguintes valores:

• $commandName (Posição 0) – Este parâmetro é definido para o nome de thecommand para que o bloco de script está fornecendo a conclusão de tabulação.
• $parameterName (posição 1) – este parâmetro é definido como o parâmetro em que o valor de avaliação requer a completação de tabelas.
• $wordToComplete (posição 2) – este parâmetro é definido para valorizar o Utilizador fornecido antes de carregar em Tab., O seu bloco de script deverá usar este valor para determinar os valores de completação de tabulações.
• $commandAst (posição 3) – Este parâmetro é definido para o SyntaxTree Abstrato (AST) para a linha de entrada atual. Para mais informações, a classe seeAst.
• $fakeBoundParameters (Posição 4) – Este parâmetro é definido para um hashtablecontaining $PSBoundParameters para o cmdlet, antes de o usuário pressedTab. Para mais informações, verabout_automatic_variables.,

o bloco de script Argumentocompleter deve desenrolar os valores usando a frase, como ForEach-Object, Where-Object, ou outro método adequado.Retornando um conjunto de Valores faz com que o PowerShell trate a matriz inteira como um valor de completação de tabulação.

o exemplo seguinte adiciona completação de tabulações ao parâmetro valor. Se apenas o parâmetro do valor é especificado, todos os valores possíveis, ou argumentos, forValue são apresentados. Quando o parâmetro do tipo é especificado, o parâmetro do valor apenas exibe os valores possíveis para esse tipo.,

além disso, o operador -like garante que se o utilizador digitar o comando seguinte e usar a completação da tabulação, apenas a Apple é devolvida.

Test-ArgumentCompleter -Type Fruits -Value A

Veja também:

about_Automatic_Variables

about_functions_advanced

about_functions_cmdletbindingattributes

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute