• 2/27/2019
  • 12 minutos para ler
    • S
    • s

Breve descrição

Descreve como criar e usar funções no PowerShell.

Long description

a function is a list of PowerShell statements that has a name that youassign. Quando você executa uma função, você digita o nome da função. As declarações na lista correm como se as tivesse escrito na linha de comandos.,

funções podem ser tão simples como:

function Get-PowerShellProcess { Get-Process PowerShell }

uma função pode também ser tão complexa como um cmdlet ou um programa de Aplicação.como cmdlets, as funções podem ter parâmetros. Os parâmetros podem ser nomeados,posicionais, switch, ou parâmetros dinâmicos. Os parâmetros da função podem ser lidos a partir da linha de comando ou do gasoduto.as funções

podem retornar valores que podem ser exibidos, atribuídos a variáveis, ou colocados em outras funções ou cmdlets. Você também pode especificar um valor de retorno usando a palavra-chave return., Thereturn keyword does not affect or suppress other output returned from your function. No entanto, a palavra-chave

sai da função nessa linha. Para mais informações, consulte about_ rent.

A função da lista de instrução pode conter diferentes tipos de instrução listswith as palavras-chave Begin Process e End. Estas declarações listam as entradas do gasoduto de forma diferente.

um filtro é um tipo especial de função que usa a palavra-chave Filter.,as funções

também podem agir como cmdlets. Você pode criar uma função que funciona exatamente como um cmdlet sem usar C# programação. Para mais informações,consulte o sítio web_functions_ advanced.,

Sintaxe

a seguir está A sintaxe de uma função:

Uma função inclui os seguintes itens:

  • Function palavra-chave
  • Um escopo (opcional)
  • Um nome que você selecionar
  • Qualquer número de parâmetros nomeados (opcional)
  • Um ou mais comandos do PowerShell entre chavetas {}

Para mais informações sobre o Dynamicparam palavras-chave e parâmetros dinâmicos infunctions, seeabout_Functions_Advanced_Parameters.,

funções simples

funções não têm de ser complicadas para serem úteis. As funcionalidades mais simples possuem o seguinte formato:

function <function-name> {statements}

por exemplo, a seguinte função inicia a PowerShell com a opção Run as administrator.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Para usar a função, digite: Start-PSAdmin

Para adicionar instruções para a função, o tipo de cada instrução em uma linha separada, oruse um ponto-e-vírgula ; para separar as declarações.,

Por exemplo, a seguinte função encontra todos os ficheiros .jpg nasdirectórias do utilizador actual que foram alteradas após a data de início.

pode criar uma caixa de ferramentas com pequenas funções úteis. Adicione estas funções ao seu perfil PowerShell, como descrito em about_Profiles e mais tarde neste tópico.

nomes de funções

você pode atribuir qualquer nome a uma função, mas as funções que você compartilha com outros devem seguir as regras de nomeação que foram estabelecidas para os comandos allPowerShell.,

funções nomes devem consistir de um par de substantivos verbais em que o verbo identifica a ação que a função executa e o substantivo identifica o conjunto em que o cmdlet executa a sua ação.

Functions should use the standard verbs that have been approved for allPowerShell commands. Estes verbos nos ajudam a manter nossos nomes de comandos simples, consistentes e fáceis de entender pelos usuários.

para mais informações sobre os verbos PowerShell padrão, veja verbos aprovados nos documentos da Microsoft.,

funções com parâmetros

pode usar parâmetros com funções, incluindo parâmetros nomeados, parâmetros posicionais, parâmetros de comutação e parâmetros dinâmicos. Para mais informações sobre parâmetros dinâmicos em funções, verabout_functions_advanced_parameters.

parâmetros nomeados

você pode definir qualquer número de parâmetros nomeados. Você pode incluir um valor padrão para parâmetros nomeados, como descrito mais tarde neste tópico.,

Você pode definir os parâmetros dentro de chaves usando o Param palavra-chave, asshown no exemplo seguinte sintaxe:

function <name> { param ($parameter1$parameter2]) <statement list>}

Você também pode definir parâmetros de fora as chaves sem o Param palavra-chave,como mostrado no exemplo seguinte sintaxe:

function <name> $parameter1$parameter2])] { <statement list>}

Abaixo está um exemplo de como esta sintaxe alternativa.

Function Add-Numbers($one, $two) { $one + $two}

embora o primeiro método seja preferido, não há diferença entre estes dois métodos.,

Quando você executa a função, o valor que você fornece 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 seguinte é uma função chamada Get-SmallFiles. Esta função tem um parâmetro $Size., A função exibe todos os arquivos que são smallerthan o valor de $Size parâmetro, e exclui diretórios:

function Get-SmallFiles { Param($Size) Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

Na função, você pode usar o $Size variável, que é o nome definido para o parâmetro.

para usar esta função, escreva o seguinte comando:

Get-SmallFiles -Size 50

Pode também indicar um valor para um parâmetro nomeado sem o nome do parâmetro.,Por exemplo, o comando a seguir fornece o mesmo resultado como um comando thatnames o parâmetro Tamanho:

Get-SmallFiles 50

Para definir um valor padrão para um parâmetro, digite um sinal de igual e o valueafter o nome do parâmetro, conforme mostrado na seguinte variação deGet-SmallFiles exemplo:

function Get-SmallFiles ($Size = 100) { Get-ChildItem $HOME | Where-Object { $_.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 usa esse valor.,

Opcionalmente, você pode fornecer uma breve cadeia de ajuda que descreve o valor de incumprimento do seu parâmetro, adicionando o atributo PSDefaultValue à descrição do seu parâmetro, e especificando a propriedade de Ajuda do pdsdefaultvalue. Para fornecer uma cadeia de ajuda que descreve o valor padrão(100) do parâmetro de tamanho no Get-SmallFiles função, adicione o atributo ‘sdefaultvalue’ como mostrado no exemplo seguinte.

function Get-SmallFiles { param ( $Size = 100 )}

Para mais informações sobre a classe de atributos PSDefaultValue, Seepsdefaultvalue.,

parâmetros posicionais

um parâmetro posicional é um parâmetro sem um nome de parâmetro. PowerShell utiliza a ordem do valor do parâmetro para associar cada valor do parâmetro a um parâmetro na função.

Quando usar parâmetros posicionais, Escreva um ou mais valores após o functionname. Os valores dos parâmetros posicionais são atribuídos à variável$args array.The value that follows the function name is assigned to the first position in $args array, $args.,

seguinte Get-Extension função adiciona o .txt extensão de nome de arquivo para afile nome que você fornecer:

function Get-Extension { $name = $args + ".txt" $name}
Get-Extension myTextFile
myTextFile.txt

os Parâmetros de opção

Um parâmetro é um parâmetro que não requer um valor. Em vez disso, você digita o nome da função seguido pelo nome do parâmetro switch.,

Para definir um parâmetro, especifique o tipo de antes de parametername, como mostrado no exemplo a seguir:

function Switch-Item { param ($on) if ($on) { "Switch on" } else { "Switch off" }}

Quando você digita o On parâmetro de opção após o nome da função, o functiondisplays “ligar”. Sem o parâmetro switch, ele exibe “desligar”.,

Switch-Item -on
Switch on
Switch-Item
Switch off

Você também pode atribuir um valor Booleano para uma opção quando você executar a função, asshown no exemplo a seguir:

Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off

Usando Splatting para Representar os Parâmetros de Comando

Você pode usar o splatting para representar os parâmetros de um comando. Esta façanha é introduzida no Windows PowerShell 3.0.

Use esta técnica em funções que chamam comandos na sessão., Você não precisa declarar ou enumerar os parâmetros de comando, ou alterar a função quando os parâmetros de comando mudam.

a seguinte função de amostra chama o Get-Command cmdlet. O comando usa@Args para representar os parâmetros de Get-Command.

function Get-MyCommand { Get-Command @Args }

Você pode usar todos os parâmetros de Get-Command quando você chamar oGet-MyCommand função. Os parâmetros e valores dos parâmetros são passados ao comando utilizando @Args.,

Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName----------- ---- ----------Cmdlet Get-ChildItem Microsoft.PowerShell.Management

@Args recurso usa o $Args parâmetro automática, que representsundeclared cmdlet parâmetros e valores de argumentos restantes.

para mais informações sobre splatting, veja about_Splatting.

Piping Objects to Functions

Any function can take input from the pipeline. Você pode controlar como um functionprocesses a entrada do pipeline usando Begin Process e Endpalavras-chave., A seguinte sintaxe de exemplo mostra as três palavras-chave:

function <name> { begin {<statement list>} process {<statement list>} end {<statement list>}}

o Begin a lista de instruções é executada apenas uma vez, no início da função.

Importante

Se a sua função define um Begin Process ou End bloco, todos os seus codemust residem no interior desses blocos. Nenhum código será reconhecido fora do blocksif qualquer um dos blocos são definidos.

o Process a lista de declarações é executada uma vez por cada objecto no oleoduto.,Enquanto o blocoProcess está em execução, cada objeto de pipeline é atribuído ao$_ variável automática, um objeto de pipeline de cada vez.

Depois que a função recebe todos os objetos no pipeline, a lista de declarações

é executada uma vez. Se nãoBeginProcess, ouEndkeywordsare usado, todas as declarações são tratados como umaEndlista de instrução.

a seguinte função usa a palavra-chave Process., A função displaysexamples do pipeline:

function Get-Pipeline{ process {"The value is: $_"}}

Para demonstrar essa função, digite uma lista de números separados por vírgulas, asshown no exemplo a seguir:

1,2,4 | Get-Pipeline
The value is: 1The value is: 2The value is: 4

Quando você usa uma função em um pipeline, os objetos canalizada para a função areassigned para o $input variável automática. A função executa declarações com Begin palavra-chave antes de qualquer objeto vir do pipeline., The function runsstatements with the End keyword after all the objects have been received from the pipeline.

O exemplo a seguir mostra o $input variável automática com Begin eEnd palavras-chave.

function Get-PipelineBeginEnd{ begin {"Begin: The input is $input"} end {"End: The input is $input" }}

Se esta função é executada utilizando o pipeline, ele exibe o followingresults:

1,2,4 | Get-PipelineBeginEnd
Begin: The input isEnd: The input is 1 2 4

o Begin instrução é executada, a função não tem a entrada de thepipeline., A demonstração End é executada após a função ter os valores.

Se a função possui uma Process palavra-chave, cada objeto $input é removedfrom $input e atribuído a $_. O exemplo a seguir tem-se uma Processlista de instrução:

function Get-PipelineInput{ process {"Processing: $_ " } end {"End: The input is: $input" }}

neste exemplo, cada objeto que é canalizada para a função é enviado para oProcess lista de instrução. The Process statements run oneobject at a time., A variável

a variável automática está vazia quando a função atinge o id

palavra-chave.

1,2,4 | Get-PipelineInput
Processing: 1Processing: 2Processing: 4End: The input is:

Para mais informações, consulte Usando Enumeradores

Filtros

Um filtro é um tipo de função que é executada em cada objeto no pipeline. Afilter assemelha-se a uma função com todas as suas afirmações em um bloco Process.,

A sintaxe do filtro, da seguinte forma:

filter <name> {<statement list>}

O seguinte filtro leva entradas de log do pipeline e, em seguida, displayseither a entrada inteira ou apenas na parte da mensagem de entrada:

filter Get-ErrorLog ($message){ if ($message) { Out-Host -InputObject $_.Message } else { $_ }}

Escopo de Função

existe Uma função no âmbito em que ele foi criado.

Se uma função é parte de um script, a função está disponível para statementswith nesse script. Por padrão, uma função em um script não está disponível no comando de comandos.

pode especificar o âmbito de uma função., Por exemplo, a função é adicionada ao escopo global no seguinte exemplo:

function global:Get-DependentSvs { Get-Service | Where-Object {$_.DependentServices}}

quando uma função está no escopo global,você pode usar a função em scripts, em funções e na linha de comandos.as funções

normalmente criam um âmbito. Os itens criados em uma função, tais como variáveis, existem apenas no escopo da função.

para mais informações sobre o escopo em PowerShell, veja abaixo.,

encontrar e gerir funções usando a função: conduzir

Todas as funções e filtros em PowerShell são automaticamente armazenados no Function: conduzir. Esta unidade é exposta pelo fornecedor de energia.

Quando se refere ao Function: unidade, digite dois-pontos depois Função, justas você iria fazer, quando fazer referência C ou D unidade de um computador.,

o seguinte comando mostra todas as funções na sessão actual de powershell:

Get-ChildItem function:

os comandos na função são armazenados como um bloco de script na definição da função. Por exemplo, para mostrar os comandos na função de Ajuda que vem com PowerShell, tipo:

(Get-ChildItem function:help).Definition

Você também pode usar a seguinte sintaxe.

$function:help

Para mais informações sobre oFunction: drive, consulte o topic de Ajuda para o provedor de funções. Type Get-Help Function.,

reutilizar as funções nas novas sessões

quando escrever uma função na linha de comandos PowerShell, a função torna-se parte da sessão actual. Está disponível até o fim da cessão.

para usar a sua função em todas as sessões PowerShell, adicione a funcionalidade ao seu perfil PowerShell. Para mais informações sobre perfis,consulte about_Profiles.

pode também gravar a sua função num ficheiro de script PowerShell. Digite sua função em um arquivo de texto, e então salve o arquivo com o id

file nameextension.,

Escrever Ajuda para Funções

Get-Help cmdlet recebe ajuda para funções, bem como 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 Get-MyDisks função, digite:

Get-Help Get-MyDisks

Você pode escrever ajuda para uma função usando um dos dois followingmethods:

  • Comentário em Ajuda para Funções

    Criar um tópico de ajuda usando palavras-chave especiais nos comentários., Para criar uma ajuda baseada emcomment 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 functionkeyword. Para mais informações sobre a ajuda baseada em comentários, consulte aabout_ comment_based_help.

  • XML-Based Help for Functions

    Create an XML-based help topic, such as the type that is typically created for cmdlets. A ajuda baseada em XML é necessária se você estiver localizando topicsde ajuda em várias linguagens.

    para associar a função ao tópico de Ajuda baseado em XML, use a palavra-chave de Ajuda

    baseada em comentários., Sem esta palavra-chave, Get-Helpnão pode encontrar o tópico de ajuda da função e chamadas para Get-Help para a recuperação da função apenas ajuda auto-gerada.

    Para mais informações sobre o ExternalHelp palavra-chave, seeabout_Comment_Based_Help. Para mais informações sobre a ajuda baseada em XML, veja como escrever a ajuda Cmdlet.

Ver também

about_ variables automáticos