Compartilhar via

New-Variable

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Cria uma nova variável.

Sintaxe

New-Variable
   [-Name] <String>
   [[-Value] <Object>]
   [-Description <String>]
   [-Option <ScopedItemOptions>]
   [-Visibility <SessionStateEntryVisibility>]
   [-Force]
   [-PassThru]
   [-Scope <String>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

O cmdlet New-Variable cria uma nova variável no Windows PowerShell. Você pode atribuir um valor à variável ao criá-la ou atribuir ou alterar o valor depois que ela for criada.

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

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

Exemplos

Exemplo 1: Criar uma variável

PS C:\> New-Variable days

Esse comando cria uma nova variável chamada days. Não é necessário digitar o parâmetro Name.

Exemplo 2: criar uma variável e atribuí-la a um valor

PS C:\> New-Variable -Name "zipcode" -Value 98033

Esse comando cria uma variável chamada zipcode e atribui-lhe o valor 98033.

Exemplo 3: criar uma variável com a opção ReadOnly

PS C:\> New-Variable -Name Max -Value 256 -Option ReadOnly
PS C:\> New-Variable -Name max -Value 1024

New-Variable : A variable with name 'max' already exists.
At line:1 char:1
+ New-Variable -Name max -Value 1024
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceExists: (max:String) [New-Variable], SessionStateException
    + FullyQualifiedErrorId : VariableAlreadyExists,Microsoft.PowerShell.Commands.NewVariableCommand

PS C:\> New-Variable -Name max -Value 1024 -Force

Este exemplo mostra como usar a opção ReadOnly de new-variable para proteger uma variável de ser substituída.

O primeiro comando cria uma nova variável chamada 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. Esse comando retorna um erro, pois a opção somente leitura é definida na variável.

O terceiro comando usa o parâmetro Force para substituir a proteção somente leitura na variável. Nesse caso, o comando para criar uma nova variável com o mesmo nome é bem-sucedido.

Exemplo 4: Criar uma variável privada

PS C:\> New-Variable -Name counter -Visibility Private

#Effect of private variable in a module.

PS C:\> Get-Variable c*

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

PS C:\> $counter
"Cannot access the variable '$counter' because it is a private variable"
At line:1 char:1
+ $counter
+ ~~~~~~~~
    + CategoryInfo          : PermissionDenied: (counter:String) [], SessionStateException
    + FullyQualifiedErrorId : VariableIsPrivate

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

Esse comando demonstra o comportamento de uma variável privada em um módulo. O módulo contém o cmdlet Get-Counter, que tem uma variável privada chamada Counter. O comando usa o parâmetro Visibility com um valor de Private para criar a variável.

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

Exemplo 5: Criar uma variável com um espaço

PS C:\> New-Variable -Name 'with space' -Value 'abc123xyz'

PS C:\> Get-Variable -Name 'with space'

Name                           Value
----                           -----
with space                     abc123xyz

PS C:\> ${with space}
abc123xyz

Esse comando demonstra que variáveis com espaços podem ser criadas. As variáveis podem ser acessadas usando o cmdlet Get-Variable ou diretamente delimitando uma variável com chaves.

Parâmetros

-Confirm

Solicita a confirmação antes de executar o cmdlet.

Tipo:SwitchParameter
Aliases:cf
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Description

Especifica uma descrição da variável.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Force

Indica que o cmdlet cria uma variável com o mesmo nome de 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 opção .

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Name

Especifica um nome para a nova variável.

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Option

Especifica o valor da propriedade opções da variável. Os valores aceitáveis para este parâmetro são:

  • Nenhum. Não define nenhuma opção. (Nenhum é o padrão.)
  • ReadOnly. Pode ser excluído. Não é possível alterar, exceto usando o parâmetro Force.
  • Privado. A variável está disponível apenas no escopo atual.
  • AllScope. A variável é copiada para quaisquer novos escopos criados.
  • Constante. Não pode ser excluído ou alterado. A constante é válida somente quando você está criando uma variável. Não é possível alterar as opções de uma variável existente para Constante.

Para ver a propriedade Options de todas as variáveis na sessão, digite Get-Variable | Format-Table -Property name, options -autosize.

Tipo:ScopedItemOptions
Valores aceitos:None, ReadOnly, Constant, Private, AllScope, Unspecified
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-PassThru

Retorna um objeto que representa o item com o qual você está trabalhando. Por padrão, esse cmdlet não gera nenhuma saída.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Scope

Especifica o escopo da nova variável. Os valores aceitáveis para este parâmetro são:

  • Global. As variáveis criadas no escopo global são acessíveis em todos os lugares em um processo do PowerShell.
  • Local. O escopo local refere-se ao escopo atual, pode ser qualquer escopo dependendo do contexto.
  • Roteiro. As variáveis criadas no escopo do script só podem ser acessadas no arquivo de script ou módulo em que são criadas.
  • Privado. As variáveis criadas no escopo privado não podem ser acessadas fora do escopo em que existem. Você pode usar o escopo privado para criar uma versão privada de um item com o mesmo nome em outro escopo.
  • Um número relativo ao escopo atual (0 por meio do número de escopos, onde 0 é o escopo atual, 1 é seu pai, 2 o pai do escopo pai e assim por diante). Não é possível usar números negativos.

Local é o escopo padrão quando o parâmetro de escopo não é especificado.

Para obter mais informações, consulte about_Scopes.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Value

Especifica o valor inicial da variável.

Tipo:Object
Cargo:1
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Visibility

Determina se a variável está visível fora da sessão na qual foi criada. Esse parâmetro foi projetado para uso em scripts e comandos que serão entregues a outros usuários. Os valores aceitáveis para este parâmetro são:

  • Público. A variável está visível. (Público é o padrão.)
  • Privado. A variável não está visível.

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

Tipo:SessionStateEntryVisibility
Valores aceitos:Public, Private
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

Object

Você pode redirecionar um valor para De Nova Variável.

Saídas

None or 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 gerará nenhuma saída.