Function Provider
Nome do provedor
Function
Unidades
Function:
Descrição resumida
Fornece acesso às funções definidas no Windows PowerShell.
Descrição detalhada
O provedor Function do Windows PowerShell permite obter, adicionar, alterar, limpar e excluir 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 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 "Function" e os filtros são precedidos pelo rótulo "Filter", mas eles operam de forma adequada quando utilizados no contexto correto, independentemente do rótulo.
O provedor Function é um namespace comum que contém apenas nos objetos de função e de filtro. Nem funções nem filtros têm 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 utilizados com filtros.
O provedor Function expõe seu repositório de dados na unidade Function:. Para trabalhar com funções, você pode alterar sua localização para a unidade Function: ("set-location function:"). Ou trabalhar de outra unidade do Windows PowerShell. Para referenciar uma função de outro local, use o nome de unidade (Function:) no caminho.
O provedor Function dá suporte a todos os cmdlets cujos nomes contenham Item (os cmdlets Item), exceto Invoke-Item. Além disso, ele dá suporte aos cmdlets Get-Content e Set-Content. No entanto, não dá suporte aos cmdlets cujos nomes contenham ItemProperty (os cmdlets ItemProperty), e nem ao parâmetro Filter em nenhum cmdlet.
Todas as alterações nas 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.
Exemplos
Obtendo a unidade Function:
-------------------------- EXEMPLO 1 --------------------------
Altera o local atual para a unidade Function: Você pode utilizar o comando em qualquer unidade do Windows PowerShell. Para retornar a uma unidade do sistema de arquivos, digite o nome da unidade. Por exemplo, digite "set-location c:".
set-location function:
Obtendo funções
-------------------------- EXEMPLO 1 --------------------------
Este comando obtém a lista de todas as funções na sessão atual. Você pode utilizar o comando a partir de qualquer unidade do Windows PowerShell.
get-childitem -path function:
-------------------------- EXEMPLO 2 --------------------------
Este comando obtém a função "man" na 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 linha seguinte. 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 da unidade (Function:) ao caminho.
-------------------------- EXEMPLO 3 --------------------------
Esses comandos obtêm a função nomeada "c:". O primeiro comando pode ser utilizado em qualquer unidade. O segundo comando é usado na unidade Function:.
Como o nome termina em dois-pontos, que é a sintaxe para uma unidade, qualifique o caminho com o nome da unidade. Na unidade Function:, você poderá 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 --------------------------
Este comando utiliza o cmdlet New-Item para criar uma função chamada "HKLM:". A expressão entre colchetes é o bloco de script representado pelo nome da função.
new-item -path function:hklm: -value {set-location hklm:}
Você também poderá criar um função digitando-a na linha de comando do Windows PowerShell. Por exemplo, digite "function:hklm: {set-location hklm:}". Se você estiver na unidade Function:, poderá omitir o nome da unidade. Como você não pode especificar o rótulo "Filter" em New-Item, os filtros são rotulados como funções, mas funcionam corretamente com qualquer rótulo. Para criar um filtro com o rótulo "Filter", digite o filtro na linha de comando. Por exemplo, digite "filter:Running {$_.Status -eq "Running"}".
-------------------------- EXEMPLO 2 --------------------------
Este comando utiliza o cmdlet New-Item para criar uma função chamada Csrss. Ele utiliza 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 de qualquer local. Se você estiver na unidade Function:, poderá usar um ponto (.) para especificar o caminho. O ponto (.) representa o local atual.
Excluindo uma função
-------------------------- EXEMPLO 1 --------------------------
Este comando exclui a função "hklm:" da sessão atual.
remove-item function:hklm:
-------------------------- EXEMPLO 2 --------------------------
Este comando exclui todas as funções da sessão atual, exceto as funções cujas propriedades Options tenham um valor Constant. Sem o parâmetro Force, o comando não exclui funções cujas propriedades Options tenham um valor ReadOnly.
remove-item function:* -force
Quando você exclui todas as funções, o prompt de comando é alterado, pois a função prompt, que define o conteúdo do prompt de comando, é excluída.
Exibindo as propriedades e os métodos de funções
-------------------------- EXEMPLO 1 --------------------------
Este comando utiliza 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 as propriedades do objeto.
get-item -path function:* | get-member
Quando você canaliza uma coleção de objetos (como as coleções de funções na unidade Function:) para Get-Member, este avalia cada objeto da coleção separadamente e retorna informações sobre cada tipo de objeto que encontra. Se todos os objetos forem do mesmo tipo, ele retornará informações sobre o tipo de objeto único. Neste 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 de Get-Member. Por exemplo, digite "get-member -InputObject (get-item function:*)". Quando você usa o parâmetro InputObject, Get-Member avalia a coleção, não os objetos da coleção.
-------------------------- EXEMPLO 2 --------------------------
Este comando lista os valores das propriedades da função "prompt". Ele utiliza o cmdlet Get-Item para obter um objeto que represente a função "prompt". O operador de pipeline (|) envia os resultados para o comando Format-List. O comando Format-List utiliza 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ê poderá 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". Ele usa o parâmetro dinâmico Options do cmdlet Set-Item. O parâmetro Options fica disponível em Set-Item somente quando é utilizado com o provedor Alias ou Function.
set-item -path function:prompt -options "AllScope,ReadOnly"
-------------------------- EXEMPLO 2 --------------------------
Este comando utiliza o cmdlet Set-Item para alterar a função "prompt" de forma que ela exiba a hora 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 --------------------------
Este comando usa o cmdlet Rename-Item para alterar o nome da função "help" 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 efetivamente um novo nome para o bloco de script associado à função prompt. Você pode utilizar o comando para salvar a função prompt original se planejar alterá-la.
A propriedade Options da nova função tem um valor 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 cmdlets, que são adicionados por um provedor do Windows PowerShell e estão disponíveis apenas quando o cmdlet está sendo usado na unidade habilitada pelo provedor.
Options <System.Management.Automation.ScopedItemOptions>
Determina o valor da propriedade Options de uma função.
| Value | Description |
|---|---|
None |
Sem 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 está disponível apenas quando você está criando uma função. Não é possível alterar a opção de uma função existente para Constant. |
Private |
A função é visível apenas no escopo atual (não em escopos filho). |
ReadOnly |
As propriedades da função não podem ser alteradas, a não ser que o parâmetro Force seja utilizado. Você poderá usar Remove-Item para excluir a função. |
AllScope |
A função é copiada para quaisquer novos escopos que são criados. |