about_Functions

Breve descrição

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. As instruções na lista são executadas como se você as tivesse digitado no prompt de comando.

As funções podem ser tão simples como:

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 recém-definida Get-PowerShellProcess :

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 ou um aplicativo.

Como cmdlets, as funções podem ter parâmetros. Os parâmetros podem ser nomeados, posicionais, interruptores ou parâmetros dinâmicos. Os parâmetros da função podem ser lidos a partir da linha de comando ou do pipeline.

As funções podem retornar valores que podem ser exibidos, atribuídos a variáveis ou passados para outras funções ou cmdlets. Você também pode especificar um valor de retorno usando a palavra-chave return . A return palavra-chave não afeta ou suprime outras saídas retornadas da sua função. No entanto, a return palavra-chave sai da função nessa linha. Para obter mais informações, consulte about_Return.

A lista de instruções da função pode conter diferentes tipos de listas de instruções com as palavras-chave begin, process, end, e clean. Essas listas de instruções manipulam a entrada do pipeline de forma diferente.

A palavra-chave filter é usada para criar um tipo de função que é executada em cada objeto no pipeline. Um filtro se assemelha a uma função com todas as suas instruções em um process bloco.

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

Sintaxe

A sintaxe de uma função é a seguinte:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

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 function palavra-chave
• Um âmbito (opcional)
• Um nome selecionado
• Qualquer número de parâmetros nomeados (opcional)
• Um ou mais comandos do PowerShell entre chaves {}

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

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 são representados pelo begin, processe end blocos da função. O PowerShell 7.3 adiciona um método de clean processo de bloco.

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

O exemplo a seguir mostra o contorno de uma função que contém um begin bloco para pré-processamento único, um process bloco para processamento de vários registros e um end bloco para pós-processamento único.

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

begin

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

process

Este bloco é usado para fornecer processamento registro a registro para a função. Você pode usar um process bloco sem definir os outros blocos. O número de execuções em bloco depende de process 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 process bloco . A $input variável automática contém um enumerador que só está disponível para funções e blocos de script. Para obter mais informações, consulte about_Automatic_Variables.

• Chamar a função no início, ou fora de um pipeline, executa o process bloco uma vez.
• Dentro de um pipeline, o process bloco é executado uma vez para cada objeto de entrada que atinge a função.
• Se a entrada do pipeline que atinge a função estiver vazia, o process bloco não será executado.
  • Os beginblocos , end, e clean ainda são executados.

end

Este bloco é usado para fornecer pós-processamento único opcional para a função.

clean

O clean bloco foi adicionado no PowerShell 7.3.

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

1. quando a execução do pipeline termina normalmente sem erro de encerramento
2. quando a execução do pipeline é interrompida devido a um erro de encerramento
3. quando o gasoduto é interrompido por Select-Object -First
4. quando o pipeline está sendo interrompido por Ctrl+c ou StopProcessing()

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

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 .jpg arquivos nos diretórios do usuário atual que foram alterados após a data de início.

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

Você pode criar uma caixa de ferramentas de pequenas funções úteis. Adicione essas funções ao seu perfil do PowerShell, conforme descrito no about_Profiles e posteriormente neste tópico.

Nomes de funções

Você pode atribuir qualquer nome a uma função, mas as funções que você compartilha com outras pessoas devem seguir as regras de nomenclatura que foram estabelecidas para todos os comandos do PowerShell.

Os nomes das funções devem consistir em um par verbo-substantivo em que o verbo identifica a ação que a função executa e o substantivo identifica o item no qual o cmdlet executa sua ação.

As funções devem usar os verbos padrão que foram aprovados para todos os comandos do PowerShell. Esses verbos nos ajudam a manter nossos nomes de comando consistentes e fáceis de entender 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 switch 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 tópico.

Você pode definir parâmetros dentro das chaves usando a param palavra-chave, 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 Param palavra-chave, conforme mostrado na sintaxe de exemplo a seguir:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Segue-se um exemplo desta sintaxe alternativa.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

Embora o primeiro método seja preferido, 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. Esta função tem um $Size parâmetro. A função exibe todos os arquivos que são menores do que o valor do $Size parâmetro 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 $Size variável, 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 dá o mesmo resultado que um comando que nomeia o parâmetro Size :

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 Get-SmallFiles exemplo:

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 descreva o valor padrão (100) do parâmetro Size na Get-SmallFiles função, 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 dos $args parâmetros posicionais são atribuídos à variável de matriz. O valor que segue o nome da função é atribuído à primeira posição na $args matriz, $args[0].

A função a seguir Get-Extension adiciona a extensão de nome de .txt arquivo a um nome de arquivo fornecido:

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

Get-Extension myTextFile

myTextFile.txt

Parâmetros do interruptor

Um switch é 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 switch, 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 On parâmetro switch após o nome da função, a função é exibida 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 booleano a um switch ao executar a função, conforme mostrado no exemplo a seguir:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Usando o splatting para representar parâmetros de comando

Você pode usar 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 são alterados.

A função de exemplo a seguir chama o Get-Command cmdlet. 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 quando você chama a Get-MyCommand função. Os parâmetros e valores de parâmetros são passados para o comando usando @Args.

Get-MyCommand -Name Get-ChildItem

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

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

Para obter mais informações, consulte about_Splatting.

Canalização de objetos para funções

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

A process lista de instruções é executada uma vez para cada objeto no pipeline. Enquanto o process bloco está em execução, cada objeto de pipeline é atribuído à $_ variável automática, um objeto de pipeline de cada 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 de pipeline ou entrada de um parâmetro, o process bloco precisa lidar com ambos os casos. Por exemplo:

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

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

Quando você usa uma função em um pipeline, os objetos canalizados para a função são atribuídos à $input variável automática. A função executa instruções com a begin palavra-chave antes que qualquer objeto venha do pipeline. A função executa instruções com a end palavra-chave depois que todos os objetos foram recebidos do pipeline.

O exemplo a seguir mostra a $input variável automática com begin e end palavras-chave.

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

Se essa função for executada usando o pipeline, ela exibirá os seguintes resultados:

1,2,4 | Get-PipelineBeginEnd

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

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

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

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 process instruções são executadas em cada objeto, um objeto de cada vez. A $input variável automática fica vazia quando a função atinge a end palavra-chave.

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 clean bloco. O clean bloco é uma maneira conveniente para os usuários limparem os recursos criados e usados nos beginblocos , processe end . É semanticamente semelhante a um finally bloco que abrange todos os outros blocos nomeados de uma função de script ou de um cmdlet de script. A limpeza de recursos é imposta para os seguintes cenários:

1. quando a execução do pipeline termina normalmente sem erro de encerramento
2. quando a execução do pipeline é interrompida devido a um erro de encerramento
3. quando o gasoduto é interrompido por Select-Object -First
4. quando o pipeline está sendo interrompido por Ctrl+C ou StopProcessing()

Filtros

Um filtro é um tipo de função que é executado em cada objeto no pipeline. Um filtro se assemelha a uma função com todas as suas instruções em um process bloco.

A sintaxe de um filtro é a seguinte:

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

O filtro a seguir obtém entradas de log do pipeline e, em seguida, exibe a entrada inteira ou apenas a parte da mensagem da entrada:

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

Pode ser utilizado da seguinte forma:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Escopo da função

Existe uma função no âmbito em que é criada.

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 usá-la 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.

Localizando e gerenciando funções usando a função: Drive

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

Ao se referir à Function: unidade, digite dois pontos após Função, assim como faria ao fazer referência à C unidade 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 bloco de script na propriedade definition da função. Por exemplo, para exibir os comandos na função 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 sobre a Function: unidade, consulte o tópico de ajuda do provedor de funções . Escreva Get-Help Function.

Reutilizando 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 termine.

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, em seguida, salve o arquivo com a extensão de nome de .ps1 arquivo.

Escrevendo ajuda para funções

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

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

Get-Help Get-MyDisks

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

• Ajuda baseada em comentários para funções

  Crie um tópico de 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 ou no final do corpo da função ou nas linhas que precedem a palavra-chave da função. Para obter mais informações sobre a ajuda baseada em comentários, consulte about_Comment_Based_Help.

• Ajuda baseada em XML para funções

  Crie um tópico de ajuda baseado em XML, como o tipo normalmente criado para cmdlets. A ajuda baseada em XML é necessária se você estiver localizando tópicos de ajuda em vários idiomas.

  Para associar a função ao tópico de ajuda baseado em XML, use a palavra-chave de ajuda baseada em .EXTERNALHELP comentários. Sem essa palavra-chave, Get-Help não é possível encontrar o tópico de ajuda da função e as chamadas para Get-Help a função retornam 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_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks