New-Variable
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 New-Variable
cmdlet 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 é 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: Criar uma variável
New-Variable days
Esse comando cria uma nova variável chamada days. Não é necessário digitar o parâmetro Nome .
Exemplo 2: Criar uma variável e atribuir um valor a ela
New-Variable -Name "zipcode" -Value 98033
Este comando cria uma variável chamada zipcode e atribui a ela 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 ReadOnly
opção 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 and 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 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.
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 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: 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 Get-Variable
cmdlet 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.
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 Option .
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 esse parâmetro são:
None
- Não define opções.None
é o padrão.ReadOnly
- Pode ser excluído. Não pode ser alterado, 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 paraConstant
.
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 OR binária. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores.
Para ver a propriedade Opções 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 que você está trabalhando. Por padrão, este cmdlet não gera 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 esse parâmetro são:
Global
- As variáveis criadas no escopo global podem ser acessadas em qualquer lugar 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 scope não é especificado.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.- 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.
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 Private
valor com esse cmdlet não altera a visibilidade da variável. 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 é visível fora da sessão na qual ela foi criada. Esse parâmetro é voltado 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 é 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-Variable
, ou 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.
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
Você pode canalizar qualquer objeto para .New-Variable
Saídas
None
Por padrão, esse cmdlet não retorna nenhuma saída.
Quando você usa o parâmetro PassThru , esse cmdlet retorna um objeto PSVariable que representa a nova variável.
Observações
O Windows PowerShell inclui os seguintes aliases para New-Variable
:
nv