Acerca da Funções

Breve descrição

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

Longa descrição

Uma função é uma lista de declarações powerShell que tem um nome que você atribui. Quando executar uma função, digite o nome da função. As declarações na lista são como se as tivesses dactilografado na ordem do comando.

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

function Get-PowerShellProcess { Get-Process PowerShell }

Uma função também pode ser tão complexa como um cmdlet ou um programa de aplicação.

Tal como os cmdlets, as funções podem ter parâmetros. Os parâmetros podem ser nomeados, posicionais, comutadores ou parâmetros dinâmicos. Os parâmetros de função podem ser lidos a partir da linha de comando ou do oleoduto.

As funções podem devolver valores que podem ser exibidos, atribuídos a variáveis ou passados a outras funções ou cmdlets. Também pode especificar um valor de devolução utilizando a return palavra-chave. A return palavra-chave não afeta nem suprimi outra saída devolvida da sua função. No entanto, a return palavra-chave sai da função nessa linha. Para mais informações, consulte about_Return.

A lista de declaração da função pode conter diferentes tipos de listas de declaração com as palavras-chave Begin Process , e End . Estas listas de declaração lidam com a entrada do gasoduto de forma diferente.

Um filtro é um tipo especial de função que usa a Filter palavra-chave.

As funções também podem agir como cmdlets. Pode criar uma função que funciona como um cmdlet sem utilizar C# a programação. Para mais informações, consulte about_Functions_Advanced.

Syntax

Segue-se a sintaxe para uma função:

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

Uma função inclui os seguintes itens:

Uma Function palavra-chave
Um âmbito (opcional)
Um nome que seleciona
Qualquer número de parâmetros nomeados (opcional)
Um ou mais comandos PowerShell incluídos em aparelhos{}

Para obter mais informações sobre as Dynamicparam palavras-chave e parâmetros dinâmicos em funções, consulte about_Functions_Advanced_Parameters.

Funções Simples

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

function <function-name> {statements}

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

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

Para utilizar a função, escreva:Start-PSAdmin

Para adicionar declarações à função, digite cada declaração numa linha separada ou utilize um ponto e vírgula ; para separar as declarações.

Por exemplo, a seguinte função encontra todos os .jpg ficheiros nos diretórios do utilizador 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}
}

Pode criar uma caixa de ferramentas de pequenas funções úteis. Adicione estas funções ao seu perfil PowerShell, conforme descrito em about_Profiles e mais tarde neste tópico.

Nomes de funções

Pode atribuir qualquer nome a uma função, mas as funções que partilha com os outros devem seguir as regras de nomeação estabelecidas para todos os comandos PowerShell.

Os nomes das funções devem consistir num par de 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 a sua ação.

As funções devem utilizar os verbos padrão que foram aprovados para todos os comandos PowerShell. Estes verbos ajudam-nos a manter os nossos nomes de comando simples, consistentes e fáceis de entender.

Para obter mais informações sobre os verbos padrão powerShell, consulte Verbos Aprovados nos Microsoft Docs.

Funções com Parâmetros

Pode utilizar parâmetros com funções, incluindo parâmetros nomeados, parâmetros posicionais, parâmetros de comutação 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

Pode definir qualquer número de parâmetros nomeados. Pode incluir um valor predefinido para parâmetros nomeados, como descrito mais tarde neste tópico.

Pode definir parâmetros dentro dos aparelhos utilizando a palavra-chave Param, como mostra a seguinte sintaxe da amostra:

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

Também pode definir parâmetros fora dos aparelhos sem a Param palavra-chave, como mostra a seguinte sintaxe da amostra:

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

Abaixo está um exemplo desta sintaxe alternativa.

Function Add-Numbers($one, $two) {
    $one + $two
}

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

Quando executam a função, o valor que fornece 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 ficheiros 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, pode utilizar a $size variável, que é o nome definido para o parâmetro.

Para utilizar esta função, digite o seguinte comando:

Get-SmallFiles -Size 50

Também pode introduzir um valor para um parâmetro nomeado sem o nome do parâmetro. Por exemplo, o seguinte comando dá o mesmo resultado que um comando que dá nomes ao parâmetro Tamanho:

Get-SmallFiles 50

Para definir um valor predefinido para um parâmetro, digite um sinal igual e o valor após o nome do parâmetro, como mostra a seguinte variação do Get-SmallFiles exemplo:

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

Se escrever Get-SmallFiles sem valor, a função atribui 100 a $size . Se fornecer um valor, a função utiliza esse valor.

Opcionalmente, pode fornecer uma breve cadeia de ajuda que descreve o valor padrão do seu parâmetro, adicionando o atributo PSDefaultValue à descrição do seu parâmetro, e especificando a propriedade de ajuda do PSDefaultValue. Para fornecer uma cadeia de ajuda que descreva o valor padrão (100) do parâmetro Tamanho na Get-SmallFiles função, adicione o atributo PSDefaultValue como mostrado no exemplo seguinte.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $size = 100
  )
}

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

Parâmetros posicionais

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

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

A seguinte Get-Extension função adiciona a extensão do nome do .txt ficheiro a um nome de ficheiro que fornece:

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

Get-Extension myTextFile

myTextFile.txt

Mudar parâmetros

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

Para definir um parâmetro de comutação, especifique o tipo [switch] antes do nome do parâmetro, como mostra o seguinte exemplo:

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

Quando digita o parâmetro do On interruptor após o nome da função, a função apresenta "Ligar". Sem o parâmetro do interruptor, apresenta "Desligar".

Switch-Item -on

Switch on

Switch-Item

Switch off

Também pode atribuir um valor Boolean a um interruptor quando executar a função, como mostra o exemplo seguinte:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Usando splatting para representar parâmetros de comando

Pode utilizar a splatting para representar os parâmetros de um comando. Esta funcionalidade é introduzida no Windows PowerShell 3.0.

Utilize esta técnica em funções que chamem comandos na sessão. Não é necessário declarar ou enumerar os parâmetros de comando, nem alterar a função quando os parâmetros de comando mudarem.

A seguinte função de amostra chama o Get-Command cmdlet. O comando utiliza @Args para representar os parâmetros de Get-Command .

function Get-MyCommand { Get-Command @Args }

Pode utilizar todos os parâmetros de Get-Command quando chamar a Get-MyCommand função. Os parâmetros e os valores dos parâmetros são transmitidos ao comando utilizando @Args .

Get-MyCommand -Name Get-ChildItem

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

A @Args função utiliza o $Args parâmetro automático, que representa parâmetros e valores de cmdlet não declarados dos restantes argumentos.

Para obter mais informações sobre a splating, consulte about_Splatting.

Objetos de tubagem para funções

Qualquer função pode tirar a entrada do gasoduto. Pode controlar como uma função processa a entrada do gasoduto utilizando Begin , Process e End palavras-chave. A seguinte sintaxe da amostra mostra as três palavras-chave:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

A Begin lista de declaração é executado apenas uma vez, no início da função.

Importante

Se a sua função definir um Begin , Process ou End bloquear, todo o seu código deve residir dentro de um dos blocos.

A Process lista de declaração é uma vez para cada objeto no oleoduto. Enquanto o Process bloco está em funcionamento, cada objeto de gasoduto é atribuído à $_ variável automática, um objeto de pipeline de cada vez.

Depois de a função receber todos os objetos do oleoduto, a End lista de declaração é executado uma vez. Se não Begin forem Process utilizadas , ou End palavras-chave, todas as declarações são tratadas como uma End lista de declaração.

A seguinte função utiliza a Process palavra-chave. A função apresenta exemplos do oleoduto:

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

Para demonstrar esta função, introduza uma lista de números separados por vírgulas, como mostra o seguinte exemplo:

1,2,4 | Get-Pipeline

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

Quando utiliza uma função num oleoduto, os objetos canalizados para a função são atribuídos à $input variável automática. A função executa declarações com a Begin palavra-chave antes de quaisquer objetos virem do oleoduto. A função executa declarações com a End palavra-chave depois de todos os objetos terem sido 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 esta função for executada utilizando o gasoduto, apresenta os seguintes resultados:

1,2,4 | Get-PipelineBeginEnd

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

Quando a Begin declaração é escora, a função não tem a entrada do oleoduto. A End declaração é executado após a função ter os valores.

Se a função tiver uma Process palavra-chave, cada objeto $input é removido e atribuído a $input $_ . O exemplo a seguir tem uma Process lista de declaração:

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

Neste exemplo, cada objeto que é canalizado para a função é enviado para a Process lista de declaração. As Process declaraçõ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

Filtros

Um filtro é um tipo de função que funciona em cada objeto na tubagem. Um filtro assemelha-se a uma função com todas as suas declarações num Process bloco.

A sintaxe de um filtro é a seguinte:

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

O seguinte filtro retira entradas de registo do pipeline e, em seguida, exibe toda a entrada ou apenas a parte da mensagem da entrada:

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

Âmbito de função

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

Se uma função fizer parte de um script, a função está disponível para declarações dentro desse script. Por predefinição, uma função num script não está disponível na origem do comando.

Pode especificar o âmbito de uma função. Por exemplo, a função é adicionada ao âmbito global no seguinte exemplo:

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

Quando uma função está no âmbito global, pode utilizar a função em scripts, funções e na linha de comando.

As funções normalmente criam um âmbito. Os itens criados numa função, como variáveis, existem apenas no âmbito da função.

Para obter mais informações sobre o âmbito de aplicação da PowerShell, consulte about_Scopes.

Encontrar e Gerir Funções Utilizando a Função: Conduzir

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

Quando se referir à Function: unidade, digite um cólon após função, tal como faria ao fazer referência à C ou unidade de um D computador.

O comando a seguir mostra 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 de definição da função. Por exemplo, para exibir os comandos na função Ajuda que vem com PowerShell, escreva:

(Get-ChildItem function:help).Definition

Também pode utilizar a seguinte sintaxe.

$function:help

Para obter mais informações sobre a Function: unidade, consulte o tópico de ajuda para o provedor de Função. Digite Get-Help Function.

Reutilização de Funções em Novas Sessões

Quando digita uma função no pedido de comando PowerShell, a função torna-se parte da sessão atual. Está disponível até ao final da sessão.

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

Também pode guardar a sua função num ficheiro de script PowerShell. Digite a sua função num ficheiro de texto e, em seguida, guarde o ficheiro com a extensão do nome do .ps1 ficheiro.

Ajuda de escrita para funções

O Get-Help cmdlet recebe ajuda para funções, bem como para cmdlets, provedores e scripts. Para obter ajuda para uma função, Get-Help escreva seguido pelo nome da função.

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

Get-Help Get-MyDisks

Pode escrever ajuda para uma função utilizando qualquer um dos dois métodos seguintes:

Ajuda baseada em comentários para funções

Crie um tópico de ajuda utilizando palavras-chave especiais nos comentários. Para criar uma ajuda baseada em comentários para uma função, os comentários devem ser colocados no início ou no fim do corpo da função ou nas linhas que precedem a palavra-chave da função. Para obter mais informações sobre 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 que é tipicamente criado para cmdlets. A ajuda baseada em XML é necessária se estiver a loisar tópicos de ajuda em vários idiomas.

Para associar a função ao tópico de ajuda baseado em XML, utilize a .ExternalHelp palavra-chave de ajuda baseada em comentários. Sem esta Get-Help palavra-chave, não é possível encontrar o tópico de ajuda da função e apela à Get-Help devolução da função apenas ajuda gerada automaticamente.

Para mais informações sobre a ExternalHelp palavra-chave, consulte about_Comment_Based_Help. Para obter mais informações sobre a ajuda baseada em XML, consulte Como Escrever a Ajuda de Cmdlet na biblioteca MSDN.