sobre_Funções

Descrição curta

Descreve como criar e usar funções no PowerShell.

Descrição longa

Uma função é uma lista de instruções do PowerShell que tem um nome que você atribui. Ao executar uma função, digite o nome da função.

O PowerShell define dois tipos de funções:

• Uma função é um bloco de código que pode ser chamado pelo nome. Ele pode usar a entrada e retornar a saída. As funções são definidas usando a function palavra-chave.
• Um filtro é um tipo de função projetada para processar dados do pipeline. Os filtros são definidos usando a filter palavra-chave.

Você pode agrupar as instruções em uma função em um dos quatro blocos de instrução predefinidos diferentes. Esses blocos de instrução são nomeados beginusando as palavras-chave , processende clean. Se você não usar essas palavras-chave, o PowerShell colocará as instruções no bloco de código apropriado.

As funções também podem agir como cmdlets. Você pode criar uma função que funciona exatamente como um cmdlet sem usar C# programação. Para obter mais informações, consulte about_Functions_Advanced.

Importante

Dentro de arquivos de script e módulos baseados em script, as funções devem ser definidas antes de serem chamadas.

Sintaxe da função

As funções são definidas usando a seguinte sintaxe:

function [<scope:>]<name> {
  param([type]$Parameter1 [,[type]$Parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Uma função inclui os seguintes itens:

• Uma palavra-chave function
• Um escopo (opcional)
• Um nome selecionado
• Qualquer número de parâmetros nomeados (opcional), incluindo parâmetros dinâmicos
• Uma ou mais instruções do PowerShell entre chaves {}

Se você não usar uma das palavras-chave (begin, process, , endclean) em uma function definição, o PowerShell colocará as instruções no end bloco.

Para obter mais informações sobre a palavra-chave dynamicparam e parâmetros dinâmicos em funções, consulte about_Functions_Advanced_Parameters.

Uma função pode ser tão simples quanto:

function Get-PowerShellProcess { Get-Process pwsh }

Depois que uma função é definida, você pode usá-la como os cmdlets internos. Por exemplo, para chamar a função de Get-PowerShellProcess recém-definida:

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

Uma função também pode ser tão complexa quanto um cmdlet.

As funções podem retornar valores que podem ser exibidos, atribuídos a variáveis ou passados para outras funções ou cmdlets. Você pode usar a return palavra-chave para retornar a saída. A palavra-chave return não afeta nem suprime outra saída retornada da função. No entanto, a palavra-chave return sai da função nessa linha. Para obter mais informações, consulte about_Return.

Sintaxe de filtro

A intenção da filter função é fornecer uma maneira abreviada de definir uma função que é executada em cada objeto no pipeline.

A sintaxe de um filtro é a seguinte:

filter [<scope:>]<name> {<statement list>}

Para simplificar a sintaxe para filter funções, omita a palavra-chave de bloco de instrução (begin, , process, end). clean O PowerShell coloca as instruções no process bloco. Você pode usar qualquer um dos outros blocos em uma função de filtro, mas a intenção era fornecer uma maneira abreviada de definir uma função que tem a única finalidade de processar cada objeto no pipeline.

O filtro a seguir usa entradas de log do pipeline e, em seguida, exibe toda a entrada ou apenas a parte da mensagem da entrada:

filter Get-EventMessage ([switch]$MessageOnly) {
  if ($MessageOnly) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Ele pode ser usado da seguinte maneira:

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

Métodos de processamento de entrada

Os métodos descritos nesta seção são chamados de métodos de processamento de entrada. Para funções, esses três métodos nomeados usando o begin, processe end blocos da função. O PowerShell 7.3 adiciona um método de processo de bloco clean.

Você não precisa usar nenhum desses blocos em suas funções. Se você não usar um bloco nomeado, o PowerShell colocará o código no bloco end da função. No entanto, se você usar qualquer um desses blocos nomeados ou definir um bloco dynamicparam, deverá colocar todo o código em um bloco nomeado.

O exemplo a seguir mostra a estrutura de tópicos de uma função que contém um begin bloco para pré-processamento único, um process bloco de dados do pipeline e um end bloco para pós-processamento único.

Function Test-ScriptCmdlet {
    [CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
}

begin

Esse bloco é usado para fornecer pré-processamento único opcional para a função. O runtime do PowerShell usa o código neste bloco uma vez para cada instância da função no pipeline.

process

Esse bloco é usado para fornecer processamento de registro por registro para a função. Você pode usar um bloco de process sem definir os outros blocos. O número de execuções de bloco process depende de como você usa a função e qual entrada a função recebe.

A variável automática $_ ou $PSItem contém o objeto atual no pipeline para uso no bloco process. A $input variável automática contém um enumerador que só está disponível para funções e scriptblocks. Para obter mais informações, consulte about_Automatic_Variables.

• Se a função for invocada sem entrada de pipeline, o PowerShell executará o process bloco apenas uma vez.
• Em um pipeline, o bloco process é executado uma vez para cada objeto de entrada que atinge a função.
• Se a entrada de pipeline que atinge a função estiver vazia, o process bloco não será executado.
  • Os blocos begin, ende clean ainda são executados.

Importante

Se um parâmetro de função aceitar a entrada do pipeline e um process bloco não for definido, o processamento de registro por registro falhará. Nesse caso, sua função só é executada uma vez, independentemente da entrada.

end

Use esse bloco para fornecer pós-processamento único opcional para a função.

clean

O bloco clean foi adicionado no PowerShell 7.3.

O bloco clean é uma maneira conveniente para os usuários limparem os recursos que se estendem pelos blocos begin, processe end. É semanticamente semelhante a um bloco de finally que abrange todos os outros blocos nomeados de uma função de script ou um cmdlet de script. A limpeza de recursos é imposta para os seguintes cenários:

1. quando a execução do pipeline for concluída sem encerrar o erro
2. quando a execução do pipeline é interrompida devido ao erro de encerramento
3. quando o pipeline é truncado, por exemplo: Select-Object -First
4. quando o pipeline é interrompido por Ctrl+c ou StopProcessing()

O bloco limpo descarta qualquer saída gravada no fluxo de Sucesso .

Cuidado

Adicionar o bloco clean é uma alteração significativa. Como clean é analisada como uma palavra-chave, ela impede que os usuários chamem diretamente um comando nomeado clean como a primeira instrução em um scriptblock. No entanto, não é provável que seja um problema. Você ainda pode invocar o comando usando o operador de chamada (& clean).

Funções simples

As funções não precisam ser complicadas para serem úteis. As funções mais simples têm o seguinte formato:

function <function-name> { statements }

Por exemplo, a função a seguir inicia o PowerShell com a opção Executar como Administrador.

function Start-PSAdmin { Start-Process PowerShell -Verb RunAs }

Para usar a função, digite: Start-PSAdmin

Para adicionar instruções à função, digite cada instrução em uma linha separada ou use um ponto-e-vírgula (;) para separar as instruções.

Por exemplo, a função a seguir localiza todos os arquivos .jpg nos diretórios do usuário atual que foram alterados após a data de início.

function Get-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | Where-Object {$_.LastWriteTime -gt $Start}
}

Você pode criar uma caixa de ferramentas de funções pequenas úteis. Adicione essas funções ao seu perfil do PowerShell, conforme descrito em about_Profiles e posterior neste artigo.

Nomes de função

Você pode atribuir qualquer nome a uma função. No entanto, para funções que você compartilha com outras pessoas, você deve seguir as regras de nomenclatura padrão do PowerShell.

• Os nomes devem consistir em um par verbo-substantivo em que o verbo identifica a ação executada pela função e o substantivo identifica o item no qual o cmdlet executa a ação.
• Os nomes devem usar os verbos aprovados para todos os comandos do PowerShell. O uso de verbos aprovados cria consistência para os usuários.

Para obter mais informações sobre os verbos padrão do PowerShell, consulte Verbos Aprovados.

Funções com parâmetros

Você pode usar parâmetros com funções, incluindo parâmetros nomeados, parâmetros posicionais, parâmetros de comutador e parâmetros dinâmicos. Para obter mais informações sobre parâmetros dinâmicos em funções, consulte about_Functions_Advanced_Parameters.

Parâmetros nomeados

Você pode definir qualquer número de parâmetros nomeados. Você pode incluir um valor padrão para parâmetros nomeados, conforme descrito posteriormente neste artigo.

Você pode definir parâmetros dentro das chaves usando a palavra-chave param, conforme mostrado na sintaxe de exemplo a seguir:

function <name> {
  param ([type]$Parameter1 [,[type]$Parameter2])
  <statement list>
}

Você também pode definir parâmetros fora das chaves sem a palavra-chave param, conforme mostrado na sintaxe de exemplo a seguir:

function <name> [([type]$Parameter1[,[type]$Parameter2])] {
  <statement list>
}

Por exemplo, a função a seguir usa a sintaxe alternativa para definir dois parâmetros:

function Add-Numbers([int]$One, [int]$Two) {
    $One + $Two
}

Embora o primeiro método seja preferencial, não há diferença entre esses dois métodos.

Quando você executa a função, o valor fornecido para um parâmetro é atribuído a uma variável que contém o nome do parâmetro. O valor dessa variável pode ser usado na função.

O exemplo a seguir é uma função chamada Get-SmallFiles. Essa função tem um parâmetro $Size. A função exibe todos os arquivos menores que o valor do parâmetro $Size e exclui diretórios:

function Get-SmallFiles {
  param ($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Na função, você pode usar a variável $Size, que é o nome definido para o parâmetro.

Para usar essa função, digite o seguinte comando:

Get-SmallFiles -Size 50

Você também pode inserir um valor para um parâmetro nomeado sem o nome do parâmetro. Por exemplo, o comando a seguir fornece o mesmo resultado de um comando que nomeia o parâmetro tamanho:

Get-SmallFiles 50

Para definir um valor padrão para um parâmetro, digite um sinal de igual e o valor após o nome do parâmetro, conforme mostrado na seguinte variação do exemplo de Get-SmallFiles:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Se você digitar Get-SmallFiles sem um valor, a função atribuirá 100 a $size. Se você fornecer um valor, a função usará esse valor.

Opcionalmente, você pode fornecer uma breve cadeia de caracteres de ajuda que descreve o valor padrão do parâmetro, adicionando o atributo PSDefaultValue à descrição do parâmetro e especificando a propriedade Help de PSDefaultValue. Para fornecer uma cadeia de caracteres de ajuda que descreve o valor padrão (100) do parâmetro Size na função Get-SmallFiles, adicione o atributo PSDefaultValue, conforme mostrado no exemplo a seguir.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Para obter mais informações sobre a classe de atributo PSDefaultValue, consulte membros do atributo PSDefaultValue.

Parâmetros posicionais

Um parâmetro posicional é um parâmetro sem um nome de parâmetro. O PowerShell usa a ordem de valor do parâmetro para associar cada valor de parâmetro a um parâmetro na função.

Ao usar parâmetros posicionais, digite um ou mais valores após o nome da função. Os valores de parâmetro posicional são atribuídos à variável de matriz $args. O valor que segue o nome da função é atribuído à primeira posição na matriz $args, $args[0].

A função Get-Extension a seguir adiciona a extensão de nome de arquivo .txt a um nome de arquivo que você fornece:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Alternar parâmetros

Uma opção é um parâmetro que não requer um valor. Em vez disso, digite o nome da função seguido pelo nome do parâmetro switch.

Para definir um parâmetro de comutador, especifique o tipo [switch] antes do nome do parâmetro, conforme mostrado no exemplo a seguir:

function Switch-Item {
  param ([switch]$On)
  if ($On) { "Switch on" }
  else { "Switch off" }
}

Quando você digita o parâmetro de opção On após o nome da função, a função exibe Switch on. Sem o parâmetro switch, ele exibe Switch off.

Switch-Item -On

Switch on

Switch-Item

Switch off

Você também pode atribuir um valor de booliano a um comutador ao executar a função, conforme mostrado no exemplo a seguir:

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Usar o splatting para passar valores de parâmetro

Você pode usar o splatting para representar os parâmetros de um comando. Esse recurso é introduzido no Windows PowerShell 3.0.

Use essa técnica em funções que chamam comandos na sessão. Você não precisa declarar ou enumerar os parâmetros de comando ou alterar a função quando os parâmetros de comando forem alterados.

A função de exemplo a seguir chama o cmdlet Get-Command. O comando usa @args para representar os parâmetros de Get-Command.

function Get-MyCommand { Get-Command @args }

Você pode usar todos os parâmetros de Get-Command ao chamar a função Get-MyCommand. Os parâmetros e os valores de parâmetro são passados para o comando usando @args.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

O recurso @args usa o parâmetro automático $args, que representa parâmetros e valores de cmdlet não declarados dos argumentos restantes.

Para obter mais informações, consulte about_Splatting.

Objetos de tubulação para funções

Qualquer função pode receber entrada do pipeline. Você pode controlar como uma função processa a entrada do pipeline usando palavras-chave begin, process, ende clean. A sintaxe de exemplo a seguir mostra estas palavras-chave:

A lista de instruções process é executada uma vez para cada objeto no pipeline. Enquanto o bloco process está em execução, cada objeto de pipeline é atribuído à variável automática $_, um objeto de pipeline por vez.

A função a seguir usa a palavra-chave process. A função exibe valores do pipeline:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1, 2, 4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Se você quiser uma função que possa receber entrada ou entrada de pipeline de um parâmetro, o bloco process precisará lidar com ambos os casos. Por exemplo:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($MyInvocation.ExpectingInput) {
           "Pipeline input: $_"
           $retValue += $_
        } else {
           foreach ($n in $Numbers) {
               "Command line input: $n"
               $retValue += $n
           }
        }
    }

    end { "Sum = $retValue" }
}


PS> 1,2,3,4 | Get-SumOfNumbers
Pipeline input: 1
Pipeline input: 2
Pipeline input: 3
Pipeline input: 4
Sum = 10
PS> Get-SumOfNumbers 1,2,3,4
Command line input: 1
Command line input: 2
Command line input: 3
Command line input: 4
Sum = 10

Quando você usa uma função em um pipeline, os objetos canalizados para a função são atribuídos à variável automática $input. A função executa instruções com o bloco de begin instrução antes que os objetos venham do pipeline. A função executa instruções com o bloco de end instrução quando não há mais objetos no pipeline.

O exemplo a seguir mostra a $input variável automática usada nos blocos de instrução e end intbegin.

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Quando você executa a função com entrada de pipeline, ela exibe os seguintes resultados:

1, 2, 4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Quando a instrução begin é executada, a função não tem a entrada do pipeline. A instrução end é executada depois que a função tem os valores.

Se a função tiver uma palavra-chave process, cada objeto em $input será removido do $input e atribuído a $_. O exemplo a seguir tem uma lista de instruções process:

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

Neste exemplo, cada objeto canalizado para a função é enviado para a process lista de instruções. As instruções process são executadas em cada objeto, um objeto por vez. A variável automática $input fica vazia quando a função atinge a palavra-chave end.

1, 2, 4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Para obter mais informações, consulte Usando enumeradores

O PowerShell 7.3 adicionou o bloco de clean. O bloco clean é uma maneira conveniente para os usuários limparem os recursos criados e usados nos blocos begin, processe end. É semanticamente semelhante a um bloco de finally que abrange todos os outros blocos nomeados de uma função de script ou um cmdlet de script. A limpeza de recursos é imposta para os seguintes cenários:

1. quando a execução do pipeline é concluída normalmente sem encerrar o erro
2. quando a execução do pipeline é interrompida devido ao erro de encerramento
3. quando o pipeline é truncado, por exemplo: Select-Object -First
4. quando o pipeline é interrompido por Ctrl+C ou StopProcessing()

Cuidado

Adicionar o bloco clean é uma alteração significativa. Como clean é analisada como uma palavra-chave, ela impede que os usuários chamem diretamente um comando nomeado clean como a primeira instrução em um scriptblock. No entanto, não é provável que seja um problema. O comando ainda pode ser invocado usando o operador de chamada (& clean).

Escopo da função

Existe uma função no escopo no qual você a cria.

Se uma função fizer parte de um script, a função estará disponível para instruções dentro desse script. Por padrão, uma função em um script não está disponível fora desse script.

Você pode especificar o escopo de uma função. Por exemplo, a função é adicionada ao escopo global no exemplo a seguir:

function Global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Quando uma função está no escopo global, você pode usar a função em scripts, em funções e na linha de comando.

As funções criam um novo escopo. Os itens criados em uma função, como variáveis, existem apenas no escopo da função.

Para obter mais informações, consulte about_Scopes.

Localizar e gerenciar funções usando a Function: unidade

Todas as funções e filtros no PowerShell são armazenados automaticamente na unidade Function:. Essa unidade é exposta pelo provedor de de funções do PowerShell.

Ao se referir à unidade de Function:, digite dois-pontos após Function, exatamente como faria ao referenciar a unidade C ou D de um computador.

O comando a seguir exibe todas as funções na sessão atual do PowerShell:

Get-ChildItem Function:

Os comandos na função são armazenados como um scriptblock na propriedade de definição da função. Por exemplo, para exibir os comandos na função de Ajuda que vem com o PowerShell, digite:

(Get-ChildItem Function:help).Definition

Você também pode usar a sintaxe a seguir.

$Function:help

Para obter mais informações, consulte about_Function_Provider.

Reutilizar funções em novas sessões

Quando você digita uma função no prompt de comando do PowerShell, a função se torna parte da sessão atual. A função fica disponível até que a sessão seja encerrada.

Para usar sua função em todas as sessões do PowerShell, adicione a função ao seu perfil do PowerShell. Para obter mais informações sobre perfis, consulte about_Profiles.

Você também pode salvar sua função em um arquivo de script do PowerShell. Digite sua função em um arquivo de texto e salve o arquivo com a extensão de nome de arquivo .ps1.

Criar ajuda para funções

O Get-Help cmdlet obtém ajuda para funções, cmdlets, provedores e scripts. Para obter ajuda para uma função, digite Get-Help seguido pelo nome da função.

Por exemplo, para obter ajuda para a função Get-MyDisks, digite:

Get-Help Get-MyDisks

Você pode escrever ajuda para uma função usando um dos dois métodos a seguir:

• Ajuda Comment-Based para funções

  Crie ajuda usando palavras-chave especiais nos comentários. Para criar ajuda baseada em comentários para uma função, os comentários devem ser colocados no início, no final ou no corpo da função. Para obter mais informações sobre ajuda baseada em comentários, consulte about_Comment_Based_Help.

• Ajuda XML-Based para funções

  A ajuda baseada em XML será necessária se você precisar localizar o conteúdo da ajuda em vários idiomas. Para associar a função ao arquivo de ajuda baseado em XML, use a .EXTERNALHELP palavra-chave de ajuda baseada em comentário. Sem essa palavra-chave, Get-Help não é possível localizar o arquivo de ajuda da função e retorna apenas a ajuda gerada automaticamente.

  Para obter mais informações sobre a palavra-chave .EXTERNALHELP, consulte about_Comment_Based_Help. Para obter mais informações sobre a ajuda baseada em XML, consulte How to Write Cmdlet Help.

Consulte também

• about_Automatic_Variables
• about_Ajuda_Baseada_em_Comentário
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• sobre_Parâmetros
• about_Profiles
• about_Scopes
• about_Script_Blocks