Function Provider
Aplica-se a: Windows PowerShell 4.0, Windows PowerShell 5.0
NOME DO PROVEDOR
Função
UNIDADES
Função:
DESCRIÇÃO BREVE
Fornece acesso às funções definidas no Windows PowerShell.
DESCRIÇÃO DETALHADA
O provedor Function do Windows PowerShell permite que você obtenha, adicione, altere, apague e exclua as funções e os filtros no Windows PowerShell.
Uma função é um bloco nomeado de código que executa uma ação. Quando você digita o nome da função, o código na função é executado. Um filtro é um bloco de código nomeado que estabelece as condições para uma ação. Você pode digitar o nome do filtro no lugar da condição, como em um comando Where-Object.
Na unidade Function:, as funções são precedidas pelo rótulo "Função" e os filtros são precedidos pelo rótulo "Filtro", mas eles operam corretamente quando usados no contexto correto, independentemente do rótulo.
O provedor Function é um namespace simples que contém apenas os objetos de função e filtro. Nem funções nem filtros possuem itens filhos.
Cada função é uma instância da classe System.Management.Automation.FunctionInfo. Cada filtro é uma instância da classe System.Management.Automation.FilterInfo.
Os exemplos nesta seção mostram como gerenciar funções, mas os mesmos métodos podem ser usados com filtros.
O provedor Function expõe seu armazenamento de dados na unidade Function:. Para trabalhar com funções, você pode alterar o local para a unidade Function: ("set-location função:"). Ou, é possível trabalhar em outra unidade do Windows PowerShell. Para fazer referência a uma função de outro local, use o nome da unidade (Function:) no caminho.
O provedor Function dá suporte a todos os cmdlets cujos nomes contenham o substantivo Item (os cmdlets de Item), exceto para Invoke-Item. E, é compatível com os cmdlets Get-Content e Set-Content. Entretanto, ele não dá suporte os cmdlets cujos nomes contenham o substantivo ItemProperty (os cmdlets ItemProperty) e não dá suporte ao parâmetro Filter em qualquer cmdlet.
Todas as alterações para as funções afetam apenas o console atual. Para salvar as alterações, adicione a função ao perfil do Windows PowerShell ou use Export-Console para salvar o console atual.
RECURSOS
ShouldProcess
EXEMPLOS
Obtendo a função: Q:
------------------------- EXEMPLO 1 --------------------------
Altera o local atual para a unidade Function:. Você pode usar esse comando de qualquer unidade no Windows PowerShell. Para retornar a uma unidade de sistema de arquivos, digite o nome da unidade. Por exemplo, digite: "set-location c:".
set-location function:
Obtendo funções
------------------------- EXEMPLO 1 --------------------------
Esse comando obtém a lista de todas as funções na sessão atual. Você pode usar esse comando de qualquer unidade do Windows PowerShell.
get-childitem -path function:
------------------------- EXEMPLO 2 --------------------------
Esse comando obtém a função "man" da unidade Function:. Ele usa o cmdlet Get-Item para obter a função. O operador de pipeline (|) envia o resultado para Format-Table.
O parâmetro Wrap direciona o texto que não cabe na linha para a próxima linha. O parâmetro Autosize redimensiona as colunas da tabela para acomodar o texto.
get-item -path man | format-table -wrap -autosize
Se você estiver em uma unidade diferente, adicione o nome de unidade (Function:) ao caminho.
------------------------- EXEMPLO 3 --------------------------
Esses comandos obtêm a função chamada "c:". O primeiro comando pode ser usado em qualquer unidade. O segundo comando é usado na unidade Function:.
Como o nome termina com dois-pontos, que é a sintaxe para uma unidade, você deve qualificar o caminho com o nome da unidade. Dentro da unidade Function:, você pode usar qualquer um dos formatos. No segundo comando, o ponto (.) representa o local atual.
c:\PS> get-item -path function:c:
PS Function> get-item -path .\c:
Criando uma função
------------------------- EXEMPLO 1 --------------------------
Esse comando usa o cmdlet New-Item para criar uma função chamada "HKLM:". A expressão entre chaves é o bloco de script que é representado pelo nome da função.
new-item -path function:hklm: -value {set-location hklm:}
Você também pode criar uma função digitando-a na linha de comando do Windows PowerShell. Por exemplo, digite "function:hklm: {set-location hklm:}". Se estiver na unidade Function:, você poderá omitir o nome da unidade. Como você não pode especificar o rótulo "Filtro" no New-Item, os filtros são rotulados como funções, mas eles operam corretamente com qualquer rótulo. Para criar um filtro com o rótulo "Filtro", digite o filtro na linha de comando. Por exemplo, digite "filter:Running {$_.Status -eq "Running"}".
------------------------- EXEMPLO 2 --------------------------
Esse comando usa o cmdlet New-Item para criar uma função chamada Csrss. Ele usa o parâmetro dinâmico Options para especificar um valor de ReadOnly para a propriedade Options da função.
new-item -path function: -name csrss -options readonly -value {get-process csrss}
Esse comando funciona em qualquer local. Se estiver na unidade Function:, você pode usar um ponto (.) para especificar o caminho. O ponto representa o local atual.
Excluindo uma função
------------------------- EXEMPLO 1 --------------------------
Esse comando exclui a função "hklm:" da sessão atual.
remove-item function:hklm:
------------------------- EXEMPLO 2 --------------------------
Esse comando exclui todas as funções da sessão atual, exceto as funções cuja propriedade Options tem um valor de constante. Sem o parâmetro Force, o comando não exclui funções cuja propriedade Options tem um valor de ReadOnly.
remove-item function:* -force
Quando você exclui todas as funções, são excluídas as alterações no prompt de comando devido à função prompt, que define o conteúdo de prompt de comando.
Exibindo as propriedades e métodos de funções
------------------------- EXEMPLO 1 --------------------------
Esse comando usa o cmdlet Get-Item para obter todas as funções. O operador de pipeline envia os resultados para o cmdlet Get-Member, que exibe os métodos e propriedades do objeto.
get-item -path function:* | get-member
Quando você direcionar uma coleção de objetos (como a coleção de funções na unidade Function:) para Get-Member, o Get-Member avaliará cada objeto na coleção separadamente e retornará informações sobre cada um dos tipos de objeto que encontrar. Se todos os objetos forem do mesmo tipo, ele retornará informações sobre o tipo de objeto único. Nesse caso, todas as funções são objetos FunctionInfo. Para obter informações sobre a coleção de objetos FunctionInfo, use o parâmetro InputObject do Get-Member. Por exemplo, digite "get-member -InputObject (get-item function:*)". Quando você usa o parâmetro InputObject, o Get-Member avalia a coleção, não os objetos na coleção.
------------------------- EXEMPLO 2 --------------------------
Esse comando lista os valores das propriedades da função "prompt". Ele usa o cmdlet Get-Item para obter um objeto que representa a função "prompt". O operador de pipeline (|) envia os resultados para o comando Format-List. O comando Format-List usa o parâmetro Property com um caractere curinga (*) para formatar e exibir os valores de todas as propriedades da função "prompt".
get-item function:prompt | format-list -property *
Alterando as propriedades de uma função
------------------------- EXEMPLO 1 --------------------------
Você pode usar o cmdlet Set-Item com o parâmetro dinâmico Options para alterar o valor da propriedade Options de uma função.
Este comando define as opções AllScope e ReadOnly para a função "prompt". Esse comando usa o parâmetro dinâmico Options do cmdlet Set-Item. O parâmetro Options está disponível apenas em Set-Item quando você o usa com o provedor Function ou Alias.
set-item -path function:prompt -options "AllScope,ReadOnly"
------------------------- EXEMPLO 2 --------------------------
Esse comando usa o cmdlet Set-Item para alterar a função "prompt" para que exiba o horário antes do caminho.
set-item -path function:prompt -value {'PS '+ $(Get-Date -format t) + " " + $(Get-Location) + '> '}
A alteração afeta as propriedades Definition e ScriptBlock do objeto FunctionInfo. Para ver o efeito da alteração, digite "get-item -path function:prompt | format-list -property *".
------------------------- EXEMPLO 3 --------------------------
Esse comando usa o cmdlet Rename-Item para alterar o nome da função "Ajuda" para "gh".
rename-item -path function:help -newname gh
Copiando uma função
------------------------- EXEMPLO 1 --------------------------
Este comando copia a função "prompt" para "oldPrompt", criando, de fato, um novo nome para o bloco de script que está associado à função de prompt. Você pode usar isso para salvar a função de prompt original se quiser alterá-la.
A propriedade Options da nova função tem um valor de None. Para alterar o valor da propriedade Options, use Set-Item.
copy-item -path function:prompt -destination function:oldPrompt
PARÂMETROS DINÂMICOS
Parâmetros dinâmicos são parâmetros de cmdlet adicionados por um provedor do Windows PowerShell e estão disponíveis somente quando o cmdlet estiver sendo usado na unidade habilitada pelo provedor.
Options <System.Management.Automation.ScopedItemOptions>
Determina o valor da propriedade Options de uma função.
| Valor | Descrição |
|---|---|
Não |
Não há opções. "None" é o padrão. |
Constant |
A função não pode ser excluída e suas propriedades não podem ser alteradas. Constant estará disponível somente quando você estiver criando uma função. Você não pode alterar a opção de uma função existente à Constant. |
Private |
A função é visível somente no escopo atual (não em escopos filhos). |
ReadOnly |
As propriedades da função não podem ser alteradas, exceto usando o parâmetro Force. Você pode usar o Remove-Item para excluir a função. |
AllScope |
A função é copiada para quaisquer novos escopos criados. |