TÓPICO
about_Functions
DESCRIÇÃO RESUMIDA
Descreve como criar e usar funções no Windows PowerShell.
DESCRIÇÃO LONGA
Uma função é uma lista de instruções que tem um nome atribuído
por você. Ao executar uma função, você digita o nome da função.
As instruções na lista são executadas como se você as tivesse
digitado no prompt de comando.
Como ocorre com os cmdlets, as funções podem ter parâmetros. Os
parâmetros podem ser nomeados, posicionais, de opção ou
dinâmicos. Os parâmetros de função podem ser lidos na linha de
comando ou no pipeline.
As funções retornam valores que podem ser exibidos, atribuídos a
variáveis ou passados a outras funções ou cmdlets.
A lista de instruções da função pode conter tipos diferentes de
listas de instruções com as palavras-chave Begin, Process e End.
Essas listas de instruções tratam as entradas provenientes do
pipeline de formas diferentes.
Um filtro é um tipo especial de função que usa a palavra-chave
Filtro.
Funções também podem se comportar como cmdlets. Você pode criar
uma função que funcione exatamente como um cmdlet sem usar
programação C#. Para obter mais informações, consulte
about_Functions_Advanced.
Sintaxe
Esta é a sintaxe de uma função:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<lista de instruções>}
begin {<lista de instruções>}
process {<lista de instruções>}
end {<lista de instruções>}
}
Uma função inclui os seguintes itens:
- Uma palavra-chave de Função
- Um escopo (opcional)
- Um nome que você seleciona
- Qualquer número de parâmetros nomeados (opcional)
- Um ou mais comandos do Windows PowerShell entre chaves ({})
Para obter mais informações sobre a palavra-chave Dynamicparam
e parâmetros dinâmicos em funções, consulte
about_Functions_Advanced_Parameters.
Funções simples
Funções não precisam ser complicadas para serem úteis. A função
a seguir obtém as variáveis de ambiente que não pertencem à
conta de Sistema do sistema atual:
função other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<System>"}
}
Para executar a função, digite "other_env".
Você pode criar uma caixa de ferramentas de 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.
Funções com parâmetros
Você pode usar parâmetros com funções, inclusive parâmetros
nomeados, posicionais, de opção e dinâmicos. Para obter mais
informações sobre parâmetros dinâmicos em funções, consulte
about_Functions_Advanced_Parameters.
Parâmetro nomeados
Você pode definir qualquer número de parâmetros nomeados. Você
pode incluir um valor padrão para parâmetros nomeados, conforme
descrito mais adiante neste tópico.
Você pode definir parâmetros dentro das chaves usando a
palavra-chave Param, conforme mostrado na seguinte sintaxe de
exemplo:
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 seguinte sintaxe de
exemplo:
function <name> [([type]$parameter1[,[type]$parameter2])] {
<lista de instruções>
}
Não há qualquer diferença entre esses dois métodos. Use o que
você preferir.
Quando você executar a função, o valor fornecido para um
parâmetro será 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 é de uma função chamada Small_files. Essa
função tem um parâmetro $size. A função exibe todos os arquivos
menores do que o valor do parâmetro $size e exclui diretórios:
function small_files {
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 small_files -size 50
Você também pode inserir um valor para um parâmetro nomeado sem
o nome do parâmetro. Por exemplo, o seguinte comando gera o
mesmo resultado do que um comando que nomeia o parâmetro Size:
C:\PS> function small_files 50
Para definir um valor padrão para um parâmetro, digite um sinal
de igual e o valor depois do nome do parâmetro, conforme
mostrado na seguinte variação do exemplo de Small_files:
function small_files ($size = 100) {
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
Se você digitar "small_files" sem um valor, a função atribuirá
100 a $size. Se você fornecer um valor, a função o usará.
Parâmetros posicionais
Um parâmetro posicional é um parâmetro sem um nome de
parâmetro. O Windows PowerShell usa a ordem do 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
depois do nome da função. São atribuídos valores de parâmetro
posicional à variável de matriz $args. O valor após o nome da
função é atribuído à primeira posição na matriz $args, $args[0].
A função Extension a seguir adiciona a extensão de nome de
arquivo .txt a um nome de arquivo fornecido por você:
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension meuArquivoTexto
meuArquivoTexto.txt
Funções podem assumir mais de um parâmetro posicional. O
exemplo a seguir exibe valores inseridos com o nome de função.
function repeat { foreach ($arg in $args) { "A entrada é
$arg" } }
C:\PS>repeat um
A entrada é um
C:\PS> repeat um dois três
A entrada é um
A entrada é dois
A entrada é três
Essa função pode ser usada com qualquer número de valores. A
função atribui cada valor a uma posição na matriz $args.
Parâmetros de opção
Uma opção é um parâmetro que não necessita de um valor. Em vez
disso, você digita 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 do parâmetro, conforme mostrado no exemplo a seguir:
function switchExample {
param ([switch]$on)
if ($on) { "Opção ativada" }
else { "Opção desativada" }
}
Quando você digitar o parâmetro de opção On depois do nome da
função, a função exibirá "Opção ativada". Sem o parâmetro de
opção, ela exibirá "Opção desativada".
C:\PS> SwitchExample -on
Opção ativada
C:\PS> SwitchExample
Opção desativada
Você também pode atribuir um valor Booleano a uma opção quando
executa a função, conforme mostrado no seguinte exemplo:
C:\PS> SwitchExample -on:$true
Opção ativada
C:\PS> SwitchExample -on:$false
Opção desativada
Canalizando 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
as palavras-chave Begin, Process e End. A seguinte sintaxe de
exemplo mostra as três palavras-chave:
function <name> {
begin {<lista de instruções>}
process {<lista de instruções>}
end {<lista de instruções>}
}
A lista de instruções Begin é executada somente uma vez, no
começo da função.
A lista de instruções Process é executada uma vez para cada
objeto no pipeline.Enquanto o bloco Process estiver sendo executado,
cada objeto do pipeline será atribuído à variável automática $_,
um objeto de pipeline de cada vez.
Depois que a função receber todos os objetos no pipeline, a lista de
instruções End será executada uma vez. Se não forem usadas
palavras-chave Begin, Process ou End, 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 pipelineFunction
{
process {"O valor é: $_"}
}
Para demonstrar essa função, digite uma matriz de números
criada com vírgulas, conforme mostrado no exemplo a seguir:
C:\PS> 1,2,4 | pipelineFunction
O valor é: 1
O valor é: 2
O valor é: 4
Quando você usar uma função em um pipeline, os objetos
canalizados para a função serão atribuídos à variável
automática $input. A função executa instruções com a
palavra-chave Begin antes de qualquer objeto oriundo do
pipeline. A função executa instruções com a palavra-chave End
depois de todos os objetos terem sido recebidos do pipeline.
O exemplo a seguir mostra a variável automática $input com as
palavras-chave Begin e End.
function PipelineBeginEnd
{
begin {"Begin: A entrada é $input"} end {"End: A
entrada é $input" } }
Se essa função for executada com o uso do pipeline, ela exibirá
os seguintes resultados:
C:\PS> 1,2,4 | PipelineBeginEnd
Begin: A entrada é
End: A entrada é 1 2 4
Quando a instrução Begin é executada, a função não tem a
entrada do pipeline. A instrução End é executa depois que a
função recebe 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 PipelineInput
{
process {"Processing: $_ " }
end {"End: A entrada é: $input" }
}
Neste exemplo, cada objeto canalizado para a função é enviado à
lista de instruções Process. As instruções Process são
executadas em cada objeto, um objeto de cada vez. A variável
automática $input fica vazia quando a função alcança a
palavra-chave End.
C:\PS> 1,2,4 | PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: A entrada é:
Filtros
Um filtro é um tipo de função executado em cada objeto no
pipeline. Um filtro se assemelha a uma função com todas as suas
instruções em um bloco Process.
A sintaxe de um filtro é a seguinte:
filter [<escopo:>]<nome> {<lista de instruções>}
O filtro a seguir recebe entradas de log do pipeline e exibe a
entrada inteira ou apenas a parte da mensagem da entrada:
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message } else
{ $_ }
}
Escopo da função
Uma função existe no escopo em que foi criada.
Se uma função fizer parte de um script, ela estará disponível
para instruções dentro desse script. Por padrão, uma função em
um script não está 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 seguinte exemplo:
function global:get-dependentsvs { get-service |
where {$_.dependentservices} }
Quando uma função está no escopo global, você pode usá-la em
scripts, em funções e na linha de comando.
Funções normalmente criam um escopo. Os itens criados em uma
função, como variáveis, só existem no escopo da função.
Para obter mais informações sobre escopo no Windows PowerShell,
consulte about_Scope.
Localizando e gerenciado funções que usam a unidade Function: Todas
as funções e todos os filtros no Windows PowerShell são automaticamente
armazenados na unidade Function: Essa unidade é exposta pelo provedor
da Função do Windows PowerShell.
Ao fazer referência à unidade Function: digite dois-pontos
depois de Function, seguindo o formato usado nas referências às
unidades C ou D de um computador.
O comando a seguir exibe todas as funções na sessão atual do Windows
PowerShell.
C:\PS> dir function:
Os comandos da função são armazenados como um bloco de scripts
na propriedade definition da função. Por exemplo, para exibir
os comandos na função Help do Windows PowerShell, digite:
(dir function:help).definition
Para obter mais informações sobre a unidade Function:, consulte
Function.
Reutilizando funções em novas sessões
Quando você digita uma função no prompt de comando do Windows
PowerShell, a função se torna parte da sessão atual. Ela está
disponível até que a sessão termine.
Para usar sua função em todas as sessões do Windows PowerShell,
adicione-a ao seu perfil do Windows 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
Windows PowerShell. Digite sua função em um arquivo de texto e
salve o arquivo com a extensão de nome de arquivo .ps1.
Redigindo ajuda para funções
O cmdlet Get-Help obtém ajuda para funções e também para cmdlets,
provedores e scripts. Para obter ajuda sobre uma função, digite
Get-Help seguido do nome da função.
Por exemplo, para obter ajuda sobre a função MyDisks, digite:
get-help MyDisks
Você pode redigir 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 da Ajuda usando palavras-chave especiais nos
comentários. Para criar ajuda baseada em comentário 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 a
ajuda baseada em comentários, consulte about_Comment_Based_Help.
-- Ajuda baseada em XML para funções
Crie um tópico da Ajuda baseado em XML, como o tipo
normalmente criado para cmdlets. A ajuda baseada em XML será
necessária se você estiver localizando tópicos da Ajuda para
vários idiomas.
Para associar a função ao tópico da Ajuda baseada em XML, use
a palavra-chave de comentário de ajuda .ExternalHelp. 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" (em inglês) no MSDN.
CONSULTE TAMBÉM
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (provider)