Compartilhar via

New-Variable

Módulo:
Microsoft.PowerShell.Utility Module

Cria uma nova variável.

Sintaxe

Default (Padrão) 

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 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

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

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 opção 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: 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 opções AllScope e Constant para que a variável esteja disponível no escopo atual e quaisquer novos escopos criados e não possam ser alterados ou excluídos.

Exemplo 5: Criar uma variável privada

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.

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
...

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 6: Criar uma variável com um espaço

Este exemplo 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.

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

Parâmetros

-Confirm

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

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False
Aliases:cf

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Description

Especifica uma descrição da variável.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 .

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Name

Especifica um nome para a nova variável.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:True
Valor dos argumentos restantes:False

-Option

Especifica o valor da propriedade opções da variável. Os valores aceitáveis para este 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 pode ser excluído ou alterado. 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 a opção parâmetro 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 binária-OR. Passar valores como uma matriz é a opção mais simples e também permite usar o preenchimento com Tab nos valores.

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

Propriedades do parâmetro

Tipo:ScopedItemOptions
Valor padrão:None
Valores aceitos:None, ReadOnly, Constant, Private, AllScope, Unspecified
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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. Local é o escopo padrão quando o parâmetro de escopo não é especificado.
  • Script - As variáveis criadas no escopo do script só podem ser acessadas no arquivo de script ou módulo em que são criadas.
  • 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.

Observação

O parâmetro também aceita o valor de Private. Private não é realmente um escopo, mas uma configuração opcional para uma variável. No entanto, usar o valor Private com esse cmdlet não altera a visibilidade da variável. Para obter mais informações, consulte about_Scopes.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Value

Especifica o valor inicial da variável.

Propriedades do parâmetro

Tipo:Object
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:1
Obrigatório:False
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:True
Valor dos argumentos restantes: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:

  • 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 unidade Variable:. 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.

Propriedades do parâmetro

Tipo:SessionStateEntryVisibility
Valor padrão:None
Valores aceitos:Public, Private
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-WhatIf

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

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False
Aliases:wi

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

Object

Você pode redirecionar qualquer objeto para New-Variable.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

PSVariable

Quando você usa o parâmetro PassThru, esse cmdlet retorna um objeto PSVariable que representa a nova variável.

Observações

O PowerShell inclui os seguintes aliases para New-Variable:

  • Todas as plataformas:
    • nv