TÓPICO
    about_Scopes

DESCRIÇÃO RESUMIDA
    Explica o conceito de escopo no Windows PowerShell e mostra como 
    definir e alterar o escopo de elementos.

    
DESCRIÇÃO LONGA
    O Windows PowerShell protege o acesso a variáveis, aliases, funções 
    e unidades do Windows PowerShell (PSDrives), limitando onde podem ser 
    lidos e alterados. Com a imposição de algumas regras simples de 
    escopo, o Windows PowerShell ajuda a assegurar que você não altere 
    inadvertidamente um item que não deveria ser alterado.


    Estas são as regras básicas de escopo:

        - Um item que você inclui em um escopo é visível no escopo 
          onde foi criado e em qualquer escopo filho, a menos que 
          você o torne particular explicitamente. Você pode colocar 
          variáveis, aliases, funções ou unidades do Windows 
          PowerShell em um ou mais escopos. 

        - Um item que você criou em um escopo só pode ser alterado 
          no escopo onde foi criado, a menos que você especifique 
          explicitamente outro escopo.


    Se você criar um item em um escopo, e esse item compartilhar seu 
    nome com um item em outro escopo, será possível ocultar o item 
    original sob o novo item. No entanto, ele não será substituído 
    nem alterado.


  Escopos do Windows PowerShell

    Os escopos do Windows PowerShell têm nomes e números. Os escopos  
    nomeados especificam um escopo absoluto. Os números são relativos e 
    refletem a relação entre escopos.


    Global: 
        O escopo em vigor quando o Windows PowerShell é iniciado. 
        As variáveis e as funções presentes quando o Windows PowerShell 
        é iniciado foram criadas no escopo global. Isso inclui variáveis 
        automáticas e preferenciais. Inclui também as variáveis, os aliases 
	e as funções nos seus perfis do Windows PowerShell. 

    Local: 
        O escopo atual. O escopo local pode ser o escopo global ou 
        qualquer outro escopo. 

    Script: 
        O escopo criado durante a execução de um arquivo de script. 
        Somente os comandos no script são executados no escopo de 
        script. Para os comandos de um script, o escopo de script 
        é o escopo local.
 
    Específico:
        Os itens no escopo específico não podem estar fora do escopo
        atual. Você pode usar o escopo específico para criar uma versão 
        específica de um item com o mesmo nome em outro escopo.


    Escopos numerados:
        Você pode fazer referência a escopos por nome ou por um número 
        que descreve a posição relativa de um escopo em relação a outro.
        Escopo 0 representa o escopo atual ou local. Escopo 1 indica 
        o escopo pai imediato. Escopo 2 indica o pai do escopo pai, 
        e assim por diante. Os escopos numerados serão úteis se você 
        tiver criado muitos escopos recursivos.


 Escopos pai e filho
 
    Você pode criar um novo escopo executando um script ou uma função, 
    criando uma sessão ou iniciando uma nova instância do Windows 
    PowerShell. Quando você cria um novo escopo, o resultado é um escopo 
    pai (o escopo original) e um escopo filho (o que você criou).


    No Windows PowerShell, todos os escopos são filhos do escopo 
    global, mas você pode criar muitos escopos e muitos escopos 
    recursivos.


    A menos que você torne os itens particulares explicitamente, 
    os itens no escopo pai estarão disponíveis ao escopo filho. No 
    entanto, itens que você cria e altera no escopo filho não afetam 
    o escopo pai, a menos que você especifique explicitamente o escopo 
    quando criar os itens.

    
 Herança
 
    Um escopo filho não herda as variáveis, os aliases e as funções 
    do escopo pai. A menos que um item seja particular, o escopo 
    filho pode exibir os itens do escopo pai. Ele pode também alterar 
    esses itens especificando o escopo pai explicitamente, mas eles 
    não fazem parte do escopo filho.


    Contudo, um escopo filho é criado com um conjunto de itens. 
    Normalmente, ele inclui todos os aliases que têm a opção 
    AllScope. Essa opção será discutida posteriormente neste tópico. 
    Ele inclui todas as variáveis que têm a opção AllScope, mais 
    algumas que podem ser usadas para personalizar o escopo, como 
    MaximumFunctionCount.


    Para localizar os itens em um escopo específico, use o parâmetro 
    Scope de Get-Variable ou Get-Alias. 


    Por exemplo, para obter todas as variáveis no escopo local, digite:

	get-variable -scope local


    Para obter todas as variáveis no escopo global, digite:

	get-variable -scope global


 Modificadores de escopo
 
    Para especificar o escopo de uma nova variável, alias ou função, 
    use um modificador de escopo. Os valores válidos de um modificador são 
    Global e Script.


    A sintaxe de um modificador de escopo em uma variável é:

        $[<modificador-de-escopo>]:<nome> = <valor>


    A sintaxe de um modificador de escopo em uma função é:

        function [<modificador-de-escopo>]:<nome> {<corpo-da-função>}


    O escopo padrão para scripts é o escopo de script. O escopo 
    padrão para funções e aliases é o local, mesmo que sejam 
    definidos em um script.
 
 
    O comando a seguir, que não usa um modificador de escopo, 
    cria uma variável no escopo atual ou local: 

       $a = "um" 

 
    Para criar a mesma variável no escopo global, use o modificador 
    de escopo global:

       $global:a = "um" 


    Para criar a mesma variável no escopo de script, use o modificador 
    de escopo de script:

       $script:a = "um" 


    Você também pode usar um modificador de escopo em funções. 
    A definição de função a seguir cria uma função no escopo global:

       function global:Hello
       {
	    write-host "Olá, mundo"
       }


    Você também pode usar modificadores de escopo para fazer 
    referência a uma variável em outro escopo. O comando a seguir faz 
    referência à variável $test, primeiro no escopo local, e depois 
    no escopo global:

      $test
	
      $global:test


 A opção AllScope
 
    Variáveis e aliases têm uma propriedade Option que pode tirar um 
    valor de AllScope. Itens que têm a propriedade AllScope tornam-se 
    parte de qualquer escopo filho que você crie, embora não sejam 
    herdados retroativamente pelos escopos pai. 


    Um item com a propriedade AllScope é visível no escopo filho, 
    e faz parte desse escopo. Alterações no item em qualquer escopo 
    afetam todos os escopos nos quais a variável está definida.   


 Gerenciando o escopo
 
    Vários cmdlets têm um parâmetro Scope que permite obter ou definir 
    (criar e alterar) itens em um escopo específico. Use o seguinte 
    comando para localizar todos os cmdlets na sua sessão que têm 
    um parâmetro Scope: 

         get-help * -parameter scope


    Para localizar as variáveis visíveis em um escopo específico, use 
    o parâmetro Scope de Get-Variable. Os parâmetros visíveis incluem 
    parâmetros globais, parâmetros no escopo pai e no escopo atual.


    Por exemplo, o comando a seguir obtém as variáveis visíveis no 
    escopo local:

        get-variable -scope local


    Para criar uma variável em um escopo específico, use um modificador de 
    escopo ou o parâmetro Scope de Set-Variable. O comando a seguir cria uma 
    variável no escopo global:

	new-variable -scope global -name a -value "Um"


    Você também pode usar o parâmetro Scope dos cmdlets New-Alias, 
    Set-Alias ou Get-Alias para especificar o escopo. O comando 
    a seguir cria um alias no escopo global:

	new-alias -scope global -name np -value Notepad.exe


    Para obter as funções de um escopo específico, use o cmdlet 
    Get-Item quando estiver no escopo. O cmdlet Get-Item não tem 
    parâmetro Scope.


 Usando a notação de dot sourcing com o escopo
 
    Scripts e funções seguem todas as regras de escopo. Você os cria em um 
    escopo específico e eles afetam somente aquele escopo, a menos que 
    você use um parâmetro de cmdlet ou um modificador de escopo para 
    alterar aquele escopo.


    Mas você pode adicionar um script ou uma função ao escopo atual 
    usando a notação de dot sourcing. Então, quando um script for 
    executado no escopo atual, qualquer função, alias e variável que 
    o script criar estará disponível no escopo atual. 
 

    Para adicionar uma função ao escopo atual, digite um ponto (.) 
    e um espaço antes do caminho e do nome da função na chamada para 
    a função.


    Por exemplo, para executar o script Sample.ps1 a partir do diretório 
    C:\Scripts no escopo do script (o padrão para scripts), use o seguinte 
    comando:

        c:\scripts\sample.ps1


    Para executar o script Sample.ps1 no escopo local, use o seguinte 
    comando:

        . c:\scripts.sample.ps1

   
    Quando você usa o operador de chamada (&) para executar uma 
    função ou um script, ele não é acrescentado ao escopo atual. 
    O exemplo a seguir usa o operador de chamada:

        & c:\scripts.sample.ps1


    Qualquer alias, função ou variável que o script Sample.ps1 criar 
    não estará disponível no escopo atual.


 Restringindo sem o escopo
 
    Alguns conceitos do Windows PowerShell são semelhantes ao escopo ou 
    à interação com o escopo. Esses conceitos podem ser confundidos com 
    o escopo ou com o comportamento do escopo.


    Sessões, módulos e prompts aninhados são ambientes autossuficiente
    s, mas não são escopos filhos do escopo global da sessão.


    Sessões:
        Uma sessão é um ambiente no qual o Windows PowerShell é executado.
        Quando você cria uma sessão em um computador remoto, o Windows 
        PowerShell estabelece uma conexão persistente com o computador 
        remoto. A conexão persistente permite que você use a sessão para 
        vários comandos relacionados.
 

        Como uma sessão é um ambiente contido, tem seu próprio 
        escopo, mas uma sessão não é um escopo filho da sessão em que 
        foi criada. A sessão é iniciada com seu próprio escopo 
        global. Esse escopo é independente do escopo global da sessão.
        Você pode criar escopos filhos na sessão. Por exemplo, é possível 
        executar um script para criar um escopo filho em uma sessão.

    Módulos:
        Você pode usar um módulo do Windows PowerShell para compartilhar 
        e fornecer ferramentas do Windows PowerShell. Um módulo é uma unidade 
        que pode conter cmdlets, scripts, funções, variáveis, aliases 
        e outros itens úteis. A menos que explicitamente definido, os itens 
        em um módulo não são acessíveis de fora do módulo. Portanto, você 
        pode adicionar o módulo à sua sessão e usar os itens públicos sem se 
        preocupar, pois os outros itens não podem anular cmdlets, scripts, 
        funções e outros itens na sua sessão.


        A privacidade de um módulo se comporta como um escopo, mas 
        acrescentar um módulo a uma sessão não altera o escopo. 
        E o módulo não tem seu próprio escopo, embora os scripts no 
        módulo, como todos os scripts do Windows PowerShell, tenham seus 
        próprios escopos. 


    Prompts aninhados:
        De forma semelhante, os prompts aninhados não têm seus 
        próprios escopos. Quando você entra em um prompt aninhado, 
        ele é um subconjunto do ambiente, mas você permanece dentro 
        do escopo local. 


        Os scripts têm seus próprios escopos. Se você estiver depurando um 
        script e alcançar um ponto de interrupção, entrará no escopo do script.


    Opção particular:
        Aliases e variáveis têm uma propriedade Option que pode tirar 
        um valor de Private. Itens que têm a opção Private podem ser 
        exibidos e alterados no escopo em que foram criados, mas não 
        podem ser exibidos ou alterados fora desse escopo. 


        Por exemplo, se você criar uma variável com uma opção 
        particular no escopo global e então executar um script, 
        os comandos Get-Variable no script não exibirão a variável 
        particular. Isso ocorrerá até mesmo se você usar o modificador 
        de escopo global. 
   

        Você pode usar o parâmetro Option dos cmdlets New-Variable, 
        Set-Variable, New-Alias e Set-Alias para definir o valor da 
        propriedade Option como Private.


    Visibilidade:
        A propriedade Visibility de uma variável ou de um alias 
        determina se você pode consultar o item fora do contêiner 
        no qual foi criado - por exemplo, um módulo. Visibility se 
        destina aos contêineres, da mesma forma que o valor Private da 
        propriedade Option se destina aos escopos.


        A propriedade Visibility retira os valores Public e Private. 
        Itens que têm visibilidade particular podem ser exibidos 
        e alterados somente no contêiner em que foram criados. Se o 
        contêiner for adicionado ou importado, os itens com visibilidade 
        particular não poderão ser exibidos ou alterados.


        Como Visibility se destina a contêineres, funciona de forma diferente em 
        um escopo. Se você criar um item com visibilidade particular no escopo 
        global, não poderá exibir ou alterar o item em qualquer escopo. Se você 
        tentar exibir ou alterar o valor de uma variável com visibilidade 
        particular, o Windows PowerShell retornará uma mensagem de erro.


        Você pode usar os cmdlets New-Variable e Set-Variable para 
        criar uma variável com visibilidade particular.

   
EXEMPLOS

  Exemplo 1: alterar o valor de uma variável somente em um script

      O comando a seguir altera o valor da variável $ConfirmPreference
      em um script. A alteração não afeta o escopo global.

    
      Primeiro, para exibir o valor da variável $ConfirmPreference no 
      escopo local, use o seguinte comando:

          C:\PS> $ConfirmPreference
          High


      Crie um script Scope.ps1 contendo os seguintes comandos:

          $ConfirmPreference = "Low"
          "O valor de `$ConfirmPreference é $ConfirmPreference." 

      Execute o script. O script altera o valor da variável 
      $ConfirmPreference, e então relata seu valor no escopo 
      do script. A saída deve ser semelhante à seguinte:

          O valor de $ConfirmPreference é Low.

        
      Em seguida, teste o valor atual da variável $ConfirmPreference 
      no escopo atual.

          C:\PS> $ConfirmPreference
          High

      
      Esse exemplo mostra que as alterações no valor de uma variável 
      no escopo de script não afetam o valor daquela variável no 
      escopo pai.


  Exemplo 2: exibir o valor de uma variável em escopos diferentes
 
      Você pode usar modificadores de escopo para exibir o valor de 
      uma variável no escopo local e em um escopo pai. 


      Primeiro, defina uma variável $test no escopo global.

	  $test = "Global"

      Em seguida, crie um script Sample.ps1 que defina a variável 
      $test. No script, use um modificador de escopo para fazer 
      referência às versões global ou local da variável $test.


          # Em Sample.ps1

          $test = "Local"
          "O valor local de `$test é $test." 
          "O valor global de `$test é $global:test." 
    
      Quando você executar Sample.ps1, a saída deverá se parecer com 
      a seguinte:
         
          O valor local de $test é Local.
          O valor global de $test é Global.


      Quando o script for concluído, somente o valor global de $test será 
      definido na sessão.

          C:\PS> $test
          Global


  Exemplo 3: alterar o valor de uma variável em um escopo pai

      A menos que proteja um item usando a opção Private ou outro 
      método, você pode exibir e alterar o valor de uma variável em 
      um escopo pai.


      Primeiro, defina uma variável $test no escopo global.

	  $test = "Global"


      Em seguida, crie um script Sample.ps1 que defina a variável 
      $test. No script, use um modificador de escopo para fazer 
      referência às versões global ou local da variável $test.

          # Em Sample.ps1

          $global:test = "Local"
          "O valor global de `$test é $global:test."

        
      Quando o script for concluído, somente o valor global de $test será 
      alterado.

          C:\PS> $test
          Local
          

  Exemplo 4: criando uma variável particular

      Uma variável particular é uma variável com uma propriedade 
      Option que tem um valor Private. As variáveis particulares são 
      herdadas pelo escopo filho, mas só podem ser exibidas ou 
      alteradas no escopo em que foram criadas.


      O comando a seguir cria uma variável particular chamada $ptest 
      no escopo local.

	  new-variable -name ptest -value 1 -option private


      Você pode exibir e alterar o valor de $ptest no escopo local.

	  C:\PS> $ptest
          1
          C:\PS> $ptest = 2
          C:\PS> $ptest
	  2
         
      
      Em seguida, crie um script Sample.ps1 contendo os comandos a seguir.
      O comando tenta exibir e alterar o valor de $ptest.  

          # Em Sample.ps1

          "O valor de `$Ptest é $Ptest."
      	  "O valor de `$Ptest é $global:Ptest."

    
      Como a variável $ptest não é visível no escopo de script, 
      a saída é vazia.
    
          "O valor de $Ptest é ."
      	  "O valor de $Ptest é ."
        
   
CONSULTE TAMBÉM
    about_Variables
    about_Environment_Variables
    about_Functions
    about_Script_Blocks




Sumário