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