about_Functions
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0
TÓPICO
about_Functions
DESCRIÇÃO BREVE
Descreve como criar e usar funções no Windows PowerShell®.
DESCRIÇÃO LONGA
Uma função é uma lista de instruções do Windows PowerShell que tem um nome atribuído por você. Quando você executa uma função, você digita o nome da função. As instruções da lista são executadas como se você as tivesse digitado no prompt de comando.
As funções podem ser tão simples quanto:
function Get-PowerShellProcess {Get-Process PowerShell}
ou tão complexas quanto um cmdlet ou um programa aplicativo.
Como os cmdlets, as funções podem ter parâmetros. Os parâmetros podem ser nomeados, posicionais, dinâmicos ou de opção. Os parâmetros de função podem ser lidos na linha de comando ou no pipeline.
As funções podem retornar valores que podem ser exibidos, atribuídos a variáveis ou transferidos a outras funções ou cmdlets.
A lista de instruções da função pode conter diferentes tipos de listas de instrução com as palavras-chave Begin, Process e End. Essas listas de instrução manipulam a entrada do pipeline de maneira diferente.
Um filtro é um tipo especial de função que usa a palavra-chave Filter.
As funções também podem atuar como os cmdlets. Você pode criar uma função que funciona como um cmdlet sem usar a programação em C#. Para obter mais informações, consulte about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511).
Sintaxe
A seguir, apresentamos a sintaxe de 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:
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
Para obter mais informações sobre a palavra-chave Dynamicparam e os parâmetros dinâmicos das funções, consulte about_Functions_Advanced_Parameters.
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 seguinte função inicia o Windows 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, use um ponto e vírgula (;) para separar as instruções ou digite cada instrução em uma linha separada.
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-NewPix
{
$start = Get-Date -Month 1 -Day 1 -Year 2010
$allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
$allpix | where {$_.LastWriteTime -gt $Start}
}
Você pode criar uma caixa de ferramentas com pequenas funções úteis. Adicione essas funções a seu perfil do Windows PowerShell, conforme descrito em about_Profiles e mais adiante neste tópico.
Nomes das funções
Você pode atribuir qualquer nome a uma função, mas as funções que compartilhar com outras pessoas devem seguir as regras de nomenclatura que foram estabelecidas para todos os comandos do Windows PowerShell.
Os nomes das funções devem consistir em um par verbo-substantivo no qual o verbo identifica a ação que a função realiza e o substantivo identifica o item no qual o cmdlet realiza sua ação.
As funções devem usar os verbos padrão que foram aprovados para todos os comandos do Windows PowerShell. Esses verbos nos ajudam a manter nossos nomes de comando simples, consistentes e fáceis de entender para os usuários.
Para obter mais informações sobre os verbos padrão do Windows PowerShell, consulte "Verbos de cmdlets" na MSDN em https://go.microsoft.com/fwlink/?LinkID=160773.
FUNÇÕES COM PARÂMETROS
Você pode usar parâmetros com funções, incluindo parâmetros nomeados, parâmetros posicionais, parâmetros de opção e parâmetros dinâmicos. Para obter mais informações sobre parâmetros dinâmicos em funções, consulte about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).
Parâmetros nomeados
Você pode definir qualquer número de parâmetros nomeados. Você pode incluir um valor padrão para os parâmetros nomeados conforme descrito mais adiante neste tópico.
Você pode definir parâmetros dentro de chaves usando a palavra-chave Param, conforme exibido 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 exibido na sintaxe de exemplo a seguir:
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
Não há nenhuma diferença entre esses dois métodos. Use o método que preferir.
Ao executar 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 que são menores que o valor do parâmetro $size e exclui diretórios:
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.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:
C:\PS> function 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 que um comando que nomeia o parâmetro Size:
C:\PS> function 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 exibido na seguinte variação do exemplo Get-SmallFiles:
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Se você digitar "Get-SmallFiles" sem um valor, a função atribui 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 descreva o valor padrão de seu parâmetro, adicionando o atributo PSDefaultValue à descrição de seu parâmetro e especificando a propriedade Help do PSDefaultValue. Para fornecer uma cadeia de caracteres de ajuda que descreva o valor padrão (100) do parâmetro Size da função Get-SmallFiles, adicione o atributo PSDefaultValue conforme exibido no exemplo a seguir.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
Para obter mais informações sobre a classe de atributo PSDefaultValue, consulte Membros do atributo PSDefaultValue na MSDN. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx
Parâmetros posicionais
Um parâmetro posicional é um parâmetro sem um nome. O Windows PowerShell usa a ordem de valores do parâmetro para associar cada valor a um parâmetro da função.
Quando você usar 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 à variável de matriz $args. O valor que segue o nome da função é atribuído à primeira posição da matriz $args, $args[0].
A seguinte função Get-Extension adiciona a extensão de nome de arquivo .txt a um nome de arquivo fornecido por você:
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
PARÂMETROS DE OPÇÃO
Uma opção é um parâmetro que não exige um valor. Em vez disso, você pode digitar o nome da função seguido do nome do parâmetro de opção.
Para definir um parâmetro de opção, especifique o tipo [switch] antes do nome de parâmetro, conforme exibido 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 exibirá "Switch on". Sem o parâmetro de opção, ele exibe "Switch off".
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
Você também pode atribuir um valor booliano a uma opção quando executar a função, conforme exibido no exemplo a seguir:
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
Como usar Splatting para representar os parâmetros de comando
Você pode usar splatting para representar os parâmetros de um comando. Esse recurso foi 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, nem alterar a função quando os parâmetros do comando mudarem.
A função de exemplo a seguir chama o cmdlet Get-Command. O comando usa @Args para representar os parâmetros do 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 transferidos ao comando usando @Args.
PS C:\>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 os parâmetros e valores não declarados de cmdlet dos argumentos restantes.
Para obter mais informações sobre splatting, consulte about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720).
Como redirecionar objetos para funções
Qualquer função pode receber entradas do pipeline. Você pode controlar como uma função processa a entrada do pipeline usando as palavras-chave Begin, Process e End. A sintaxe de exemplo a seguir mostra as três palavras-chave:
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
A lista de instruções Begin é executada somente uma vez, no início da função.
A lista de instruções Process é executada uma vez para cada objeto do pipeline. Enquanto o bloco Process é executado, cada objeto de pipeline é atribuído à variável automática $_, um por vez.
Depois que a função receber todos os objetos do pipeline, a lista de instruções End é executada uma vez. Se nenhuma palavra-chave Begin, Process ou End for usada, todas as instruções serão tratadas como uma lista de instruções End.
A função a seguir usa a palavra-chave Process. A função exibe exemplos do pipeline:
function Get-Pipeline
{
process {"The value is: $_"}
}
Para demonstrar essa função, digite uma lista de números separados por vírgulas, como exibido no exemplo a seguir:
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Quando você usa uma função em um pipeline, os objetos redirecionados para a função são atribuídos à variável automática $input. A função executa instruções com a palavra-chave Begin antes que qualquer objeto venha do pipeline. A função executa instruções com a palavra-chave End depois que todos os objetos forem recebidos do pipeline.
O exemplo a seguir mostra a variável automática $input com as palavras-chave Begin e End.
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:
C:\PS> 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 tiver os valores.
Se a função tiver uma palavra-chave Process, ela lerá os dados em $input. 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 que é redirecionado para a função é enviado à lista de instruções Process. As instruções Process são executadas em cada objeto, um por vez. A variável automática $input fica vazia quando a função atinge a palavra-chave End.
C:\PS> 1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Filtros
Um filtro é um tipo de função que é executada em cada objeto do pipeline. Um filtro é semelhante a uma função com todas as suas instruções em um bloco Process.
A sintaxe de um filtro é a seguinte:
filter [<scope:>]<name> {<statement list>}
O seguinte filtro usa entradas de log do pipeline e, em seguida, exibe a entrada inteira ou apenas a parte de mensagem da entrada:
filter Get-ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Escopo da função
Uma função existe no escopo no qual ela foi criada.
Se uma função fizer parte de um script, a função estará disponível para as instruções desse script. Por padrão, uma função de um script não estará disponível no prompt de comando.
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 {$_.DependentServices} }
Quando uma função estiver no escopo global, você pode usar a função nos scripts, nas funções e na linha de comando.
Geralmente, as funções criam um escopo. Os itens criados em uma função, como variáveis, existem somente no escopo da função.
Para obter mais informações sobre escopo do Windows PowerShell, consulte about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260).
Como localizar e gerenciar funções usando a unidade function: Q:
Todas as funções e filtros do Windows PowerShell são armazenados automaticamente na unidade Function:. Essa unidade é exposta pelo provedor de Function do Windows PowerShell.
Ao fazer referência à unidade Function:, digite dois-pontos depois de Function, do mesmo modo que ao fazer referência à unidade C ou D de um computador.
O comando a seguir exibe todas as funções da sessão atual do Windows PowerShell:
Get-ChildItem function:
Os comandos da função são armazenados como um bloco de script na propriedade de definição da função. Por exemplo, para exibir os comandos da função Help que acompanham o Windows PowerShell, digite:
(Get-ChildItem function:help).Definition
Para obter mais informações sobre a unidade Function:, consulte o tópico de ajuda do provedor de Function. Digite "Get-Help Function" ou exiba-o na biblioteca do TechNet em https://go.microsoft.com/fwlink/?LinkID=113436.
Como reutilizar funções em novas sessões
Quando você digita uma função no prompt de comando do Windows PowerShell, ela se torna parte da sessão atual. Ela ficará disponível até que a sessão seja encerrada.
Para usar sua função em todas as sessões do Windows PowerShell, adicione a função a seu perfil do Windows PowerShell. Para obter mais informações sobre perfis, consulte about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729).
Você também pode salvar sua função em um arquivo de script do Windows PowerShell. Digite sua função em um arquivo de texto e, em seguida, salve o arquivo com a extensão de nome de arquivo .ps1.
Como escrever ajuda para funções
O cmdlet Get-Help obtém ajuda para as funções e para 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 qualquer 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 uma ajuda com base 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 function. Para obter mais informações sobre a ajuda baseada em comentários, consulte about_Comment_Based_Help.
Ajuda com base em XML para funções
Crie um tópico de ajuda baseado em XML, como o tipo que é criado geralmente para os 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 comentário ExternalHelp. Sem essa palavra-chave, o Get-Help não conseguirá localizar o tópico de ajuda da função e chamará o Get-Help para que a função retone 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 "Como escrever ajuda para cmdlets" na MSDN.
CONSULTE TAMBÉM
about_Automatic_Variables
about_Comment_Based_Help
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
Function (provedor)