about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

about_Functions

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]$parame

{
param([type]$parameter1 [,[type]$parameter2])

1 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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

2 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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}
}

3 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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"

4 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

$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 segui

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

5 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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 execut
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 list

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
{

6 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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 Proces

function PipelineInput

7 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

{
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

8 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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 automati
armazenados na unidade Function: Essa unidade é exposta pelo pro
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 Win

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

9 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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_Hel

-- 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

10 of 11 26/05/2019 15:37
about_Functions - Microsoft Windows PowerShell http://underpop.online.fr/w/windows-power-shell/about-functions-micros...

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)

11 of 11 26/05/2019 15:37