Share via

New-Variable

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

Cria uma nova variável.

Syntax

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

Description

O New-Variable cmdlet cria uma nova variável em Windows PowerShell. Você pode atribuir um valor à variável ao criá-la ou atribuir ou alterar o valor depois que ela é 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 New-Variable cmdlet para usar seus parâmetros.

Exemplos

Exemplo 1: Create uma variável

New-Variable days

Esse comando cria uma nova variável chamada days. Você não precisa digitar o parâmetro Name .

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

New-Variable -Name "zipcode" -Value 98033

Esse comando cria uma variável chamada cepcódigo e atribui o valor 98033.

Exemplo 3: Create 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, porque 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: Atribuir várias opções a uma variável

New-Variable -Name 'TestVariable' -Value 'Test Value' -Option AllScope,Constant

Este exemplo cria uma variável e atribui as AllScope opções e Constant para que a variável fique disponível no escopo atual e quaisquer novos escopos criados e não possam ser alterados ou excluídos.

Exemplo 5: Create 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 Get-Counter cmdlet , 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 amostra de saída mostra o comportamento de uma variável particular. 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 6: Create 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

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

Parâmetros

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Description

Especifica uma descrição da variável.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Indica que o cmdlet cria uma 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 .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Especifica um nome para a nova variável.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Option

Especifica o valor da propriedade Options da variável. Os valores aceitáveis para esse parâmetro são:

  • None – Não define nenhuma opção. None é o padrão.
  • ReadOnly - Pode ser excluído. Não é possível alterar, exceto usando o parâmetro Force .
  • Private - A variável está disponível apenas no escopo atual.
  • AllScope - A variável é copiada para todos os novos escopos criados.
  • Constant – Não é possível excluir ou alterar. Constant é válido somente quando você está criando uma variável. Não é possível alterar as opções de uma variável existente para Constant.

Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro Option como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use a conclusão de tabulação nos valores.

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

Type:ScopedItemOptions
Accepted values:None, ReadOnly, Constant, Private, AllScope, Unspecified
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Scope

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

  • Global – As variáveis criadas no escopo global podem ser acessadas 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.
  • Script – As variáveis criadas no escopo do script são acessíveis somente dentro do arquivo de script ou módulo em que são criadas.
  • Private – 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 até o número de escopos, em que 0 é o escopo atual, 1 é seu pai, 2 o pai do escopo pai e assim por diante). Números negativos não podem ser usados.

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

Para obter mais informações, consulte about_Scopes.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Value

Especifica o valor inicial da variável.

Type:Object
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Visibility

Determina se a variável é visível fora da sessão na qual ela 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 esse parâmetro são:

  • Public - A variável está visível. Public é o padrão.
  • Private - 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-Variableou em exibições da Variable: unidade. 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 tiverem sido escritos na sessão em que a variável foi definida.

Type:SessionStateEntryVisibility
Accepted values:Public, Private
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

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

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

Object

Você pode redirecionar um valor para New-Variable.

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, este cmdlet não gera nenhuma saída.