Cria uma nova variável.

Sintaxe

New-Variable [-Name] <string> [[-Value] <Object>] [-Descrição <string>] [-Force] [-Option {<None> | <ReadOnly> | <Constant> | <Private> | <AllScope>}] [-PassThru] [-Scope <string>] [-Visibility {<Public> | <Private>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Descrição

O cmdlet New-Variable cria uma nova variável no Windows PowerShell. Você pode atribuir um valor à variável enquanto a estiver criando ou atribuir ou alterar o valor após sua criação.

Você pode usar os parâmetros de New-Variable para definir as propriedades da variável (como as que criam variáveis somente leitura ou frequentes), definir o escopo de uma variável e determinar se variáveis são públicas ou privadas.

Normalmente, você cria uma nova variável digitando o nome de variável e seu valor, como "$var = 3", mas você pode usar o cmdlet New-Variable para usar seus parâmetros.

Parâmetros

-Descrição <string>

Especifica uma descrição da variável.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Force

Permite criar uma nova variável com o mesmo nome que uma variável somente leitura existente.

Por padrão, você pode substituir uma variável, a menos que a variável tenha um valor de opção de ReadOnly ou Constant. Para obter mais informações, consulte o parâmetro Option.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Name <string>

Especifica um nome para a nova variável.

Necessário?

true

Posição?

1

Valor padrão

Aceitar entrada do pipeline?

true (ByPropertyName)

Aceitar caracteres curinga?

false

-Option <ScopedItemOptions>

Define o valor da propriedade Options da nova variável.

Os valores válidos são:

-- None: não define nenhuma opção. ("None" é o padrão.)

-- ReadOnly: o valor da variável não pode ser alterado, exceto com o uso do parâmetro Force. É possível usar Remove-Variable para excluir a variável.

-- Constant: a variável não pode ser excluída e suas propriedades não podem ser alteradas. "Constant" está disponível apenas quando você está criando um alias. Não é possível alterar a opção de uma variável existente para "Constant".

-- Private: a variável está disponível apenas no escopo especificado pelo parâmetro Scope. Ela é herdada pelos escopos filho. (Esse valor não é relacionado ao valor "Private" do parâmetro Visibility.)

-- AllScope: a variável é copiada em qualquer novo escopo criado.

Para visualizar a propriedade Options das variáveis, digite "get-variable| Format-Table -property name, options -autosize".

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-PassThru

Retorna um objeto que representa a nova variável. Por padrão, este cmdlet não gera nenhuma saída.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Scope <string>

Determina o escopo da nova variável. Os valores válidos são "Global", "Local" ou "Script" ou um número relativo ao atual escopo (0 ao número de escopos, onde 0 é o escopo atual e 1 é seu pai). "Local" é o padrão. Para obter mais informações, consulte about_Scopes.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Value <Object>

Especifica o valor inicial da variável.

Necessário?

false

Posição?

2

Valor padrão

Aceitar entrada do pipeline?

true (ByValue, ByPropertyName)

Aceitar caracteres curinga?

false

-Visibility <SessionStateEntryVisibility>

Determina se a variável é visível fora da sessão na qual foi criada. Esse parâmetro é criado para uso em scripts e comandos que serão entregues a outros usuários.

Os valores válidos são:

-- Public: a variável é visível. ("Public" é o padrão.)

-- Private: a variável não é visível.

Quando uma variável é particular, ela não aparece em listas de variáveis, como as retornadas por Get-Variable ou em exibições da unidade Variable: Comandos para ler ou alterar o valor de uma variável particular retornam um erro. No entanto, o usuário poderá executar comandos que usam uma variável particular se os comandos forem escritos na sessão na qual a variável foi definida.

Necessário?

false

Posição?

named

Valor padrão

Public

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Confirm

Solicita confirmação antes da execução do comando.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-WhatIf

Descreve o que aconteceria se você executasse o comando, sem executá-lo de fato.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

System.Object

Você pode canalizar um valor para New-Variable.

Saídas

None ou System.Management.Automation.PSVariable

Quando você usa o parâmetro PassThru, New-Variable gera um objeto System.Management.Automation.PSVariable que representa a nova variável. Caso contrário, esse cmdlet não gera nenhuma saída.

Exemplo 1

C:\PS>new-variable days

Descrição
-----------
Esse comando cria uma nova variável denominada "days". Ele não possui valor imediatamente após o comando.

Exemplo 2

C:\PS>new-variable zipcode -value 98033

Descrição
-----------
Esse comando cria uma variável denominada "zipcode" e atribui a ela o valor "98033".

Exemplo 3

C:\PS>new-variable -name max -value 256 -option readonly

new-variable -name max -value 1024

new-variable -name max -value 1024 -force

C:\PS> new-variable -name max -value 256 -option readonly

C:\PS> new-variable -name max -value 1024
New-Variable : A variable with name 'max' already exists.
At line:1 char:13
+ new-variable <<<<  -name max -value 1024

C:\PS> new-variable -name max -value 1024 -force

Descrição
-----------
Este exemplo mostra como usar a opção ReadOnly de New-Variable para impedir que uma variável seja substituída.

O primeiro comando cria uma nova variável denominada Max e define seu valor como "256." Ele usa o parâmetro Option com um valor de ReadOnly.

O segundo comando tenta criar uma segunda variável com o mesmo nome. Este comando retorna um erro, porque a opção somente leitura é definida na variável.

O terceiros comando usa o parâmetro Force para substituir a proteção de somente leitura da variável. Neste caso, o comando para criar uma nova variável com o mesmo nome tem sucesso.

Exemplo 4

C:\PS>new-variable -name counter -visibility private

#Effect of private variable in a module.

C:\PS> get-variable c*

Name                           Value
----                           -----
Culture                        en-US
ConsoleFileName
ConfirmPreference              High
CommandLineParameters          {}

C:\PS> $counter
"Cannot access the variable '$counter' because it is a private variable"

C:\PS> Get-Counter
Name         Value
----         -----
Counter1     3.1415
...

Descrição
-----------
Este comando demonstra o comportamento de uma variável particular em um módulo. O módulo contém o cmdlet Get-Counter, que tem uma variável particular denominada "Counter". O comando usa o parâmetro Visibility com um valor de "Private" para criar a variável.

O exemplo de saída mostra o comportamento de uma variável particular. O usuário que carregou o módulo não pode exibir nem alterar o valor da variável Counter, mas a variável Counter pode ser lida e alterada pelos comandos do módulo.

See Also



Sumário