Compartilhar via


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