Carregando
0xA0Lição 11 de 25

Funções e parâmetros

Escreva suas próprias funções no estilo cmdlet com parâmetros tipados e validados e entrada de pipeline.

32 min Questionário com 7 perguntas 2 exercícios de código
Ao final desta lição, você saberá
  • Defina funções com blocos, tipos, padrões e opções param()
  • Valide a entrada com atributos Mandatory e Validate*
  • Aceite a entrada do pipeline com início/processo/fim e evite saída acidental

Uma função é um bloco de script nomeado. Dê a ele um nome Verb-Noun e um bloco param(), e ele funciona como um cmdlet integrado - parâmetros nomeados, preenchimento de tabulação e tudo:

1function Get-FeedingAmount {
2  param(
3    [int]$Wingspan,
4    [switch]$Hungry,
5    [string]$Food = 'goats'
6  )
7  $kg = $Wingspan * 3
8  if ($Hungry) { $kg *= 2 }
9  "$kg kg of $Food"
10}
11Get-FeedingAmount -Wingspan 12 -Hungry      # 72 kg of goats

Chame-o como um cmdlet - sem parênteses, sem vírgulas. Get-FeedingAmount(12, $true) passa um único array para o primeiro parâmetro, um erro clássico.

functions.ps1
1function Get-FeedingAmount {
2  param(
3    [int]$Wingspan,
4    [switch]$Hungry,
5    [string]$Food = 'goats'
6  )
7  $kg = $Wingspan * 3
8  if ($Hungry) { $kg *= 2 }
9  "$kg kg of $Food"
10}
11Get-FeedingAmount -Wingspan 12
12Get-FeedingAmount -Wingspan 12 -Hungry
13Get-FeedingAmount 2 -Food 'lantern moths'
Saída
36 kg of goats
72 kg of goats
6 kg of lantern moths

Tudo é saída

Aqui está o que há de mais surpreendente sobre as funções do PowerShell: cada valor que não é capturado torna-se parte do resultado, não apenas o que segue return. return simplesmente sai mais cedo (opcionalmente gerando mais um valor).

Portanto, uma chamada de método perdida que retorna algo - $list.Add('x') retorna o novo índice, por exemplo - vaza na sua saída. Silencie-o com $null = ..., [void](...) ou | Out-Null.

output-leak.ps1
1function Get-Names {
2  $list = [System.Collections.ArrayList]::new()
3  $list.Add('Ember')
4  $list.Add('Glim')
5  return $list
6}
7function Get-NamesQuietly {
8  $list = [System.Collections.ArrayList]::new()
9  $null = $list.Add('Ember')
10  [void]$list.Add('Glim')
11  $list
12}
13(Get-Names) -join ','
14(Get-NamesQuietly) -join ','
Saída
0,1,Ember,Glim
Ember,Glim

Funções avançadas

Adicione [CmdletBinding()] acima de param() para transformar sua função em uma função avançada. Ela passa a aceitar parâmetros comuns, como -Verbose e -ErrorAction, e atributos de parâmetros:

AtributoEfeito
[Parameter(Mandatory)]Exige um valor
[Parameter(ValueFromPipeline)]Recebe objetos do pipeline
[ValidateSet('Wyrm', 'Wisp')]Aceita apenas esses valores e oferece preenchimento com Tab
[ValidateRange(1, 30)]Exige um número dentro do intervalo
[ValidateNotNullOrEmpty()]Rejeita $null e ''
[ValidatePattern('^DRG-\d{4}$')]Exige correspondência com a expressão regular

Para receber entrada do pipeline, marque um parâmetro com ValueFromPipeline e faça o trabalho em process {}. Esse bloco roda uma vez por objeto recebido. begin {} roda antes do primeiro; end {} roda após o último.

advanced.ps1
1function New-DragonTag {
2  [CmdletBinding()]
3  param(
4    [Parameter(Mandatory, ValueFromPipeline)]
5    [ValidateNotNullOrEmpty()]
6    [string]$Name,
7    [ValidateRange(1, 9999)]
8    [int]$Start = 1
9  )
10  begin   { $number = $Start }
11  process {
12    'DRG-{0:D4} {1}' -f $number, $Name
13    $number++
14  }
15  end     { Write-Verbose "Tagged up to $number" }
16}
17'Ember', 'Glim', 'Skyla' | New-DragonTag -Start 40
18try { New-DragonTag -Name 'Pebble' -Start 0 } catch { 'Rejected: Start must be 1 to 9999' }
Saída
DRG-0040 Ember
DRG-0041 Glim
DRG-0042 Skyla
Rejected: Start must be 1 to 9999

Principais conclusões

  • As funções recebem um bloco param() com tipos, padrões e parâmetros [switch]; chame-os de cmdlets.

  • Cada valor não capturado é gerado - silencie chamadas barulhentas com $null = ou [void].

  • [CmdletBinding()] mais atributos [Parameter()] e [Validate*()] fornecem entrada robusta de nível de cmdlet.

  • ValueFromPipeline com begin/process/end faz uma função funcionar em pipelines.

Quiz da aula

7 perguntas · aprovação com 5 acertos · até 50 XP

Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.

Pratique: escreva código em scripts PowerShell

Escreva um script no editor e execute-o de verdade com entradas de exemplo, que chegam ao script como $input. Os scripts rodam no PowerShell 6.2 pelo Try It Online (tio.run), um serviço público gratuito, então estes exercícios evitam sintaxe exclusiva do PowerShell 7; seu script e a entrada de teste são enviados para lá.

Exercício 1

Calculadora de alimentação

+25 XP

Escreva Get-FeedingAmount com os parâmetros -Wingspan (um [int], que deve ser de 1 a 30 - use [ValidateRange]) e uma chave -Hungry. Um dragão come 3 kg por metro de envergadura, o dobro quando está com fome. Ele retorna apenas o número.

Cada linha de entrada é uma envergadura, opcionalmente seguida por hungry. O starter divide a linha para você; chame sua função e imprima 12 m: 36 kg ou 12 m (hungry): 72 kg.

  • Três dragões
  • Um grande problema
script.ps1
Carregando editor…

As aulas ensinam PowerShell 7; seu script roda no PowerShell 6.2 pelo Try It Online (tio.run), um serviço público gratuito, então use uma sintaxe que funcione lá. A entrada de teste chega ao script como $input. Seu script e a entrada de teste são enviados a esse serviço.

Exercício 2

Identifique-os por meio do pipeline

+25 XP

Escreva uma função avançada New-DragonTag que pega nomes de dragões do pipeline e gera DRG-0001 Ember, DRG-0002 Glim, ... numeração de 1 com quatro dígitos. Quando o pipeline for concluído, ele gerará tagged 2 dragons. O starter canaliza a entrada para ele.

Use begin, process e end, e o formato {0:D4}.

  • Dois dragões
  • Quatro dragões
script.ps1
Carregando editor…

As aulas ensinam PowerShell 7; seu script roda no PowerShell 6.2 pelo Try It Online (tio.run), um serviço público gratuito, então use uma sintaxe que funcione lá. A entrada de teste chega ao script como $input. Seu script e a entrada de teste são enviados a esse serviço.

Dúvidas sobre esta lição

Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.

Carregando publicações…