New-Variable
Cria uma nova variável.
Sintaxe
Default (Predefiniçã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 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 cmdlet New-Variable para usar seus parâmetros.
Exemplos
Exemplo 1: Criar uma variável
PS C:\> New-Variable days
Este 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-lhe um valor
PS C:\> New-Variable -Name "zipcode" -Value 98033
Este comando cria uma variável chamada zipcode e atribui-lhe o valor 98033.
Exemplo 3: Criar uma variável com a opção Somente leitura
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. Este comando retorna um erro, porque a opção somente leitura está 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
...
Este 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 Private para criar a variável.
A saída de amostra mostra o comportamento de uma variável privada. O usuário que carregou o módulo não pode visualizar ou alterar o valor da variável Contador, mas a variável Contador 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
Este 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 confirmação antes de executar o cmdlet.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Cf. |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Description
Especifica uma descrição da variável.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 ReadOnly ou Constant. Para obter mais informações, consulte o parâmetro Option.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Name
Especifica um nome para a nova variável.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-Option
Especifica o valor da propriedade Options da variável. Os valores aceitáveis para este parâmetro são:
- Nenhum. Não define opções. (Nenhum é o padrão.)
- ReadOnly. Pode ser excluído. Não pode ser alterado, exceto usando o parâmetro Force.
- Privado. A variável está disponível apenas no escopo atual.
- AllScope. A variável é copiada para todos os novos escopos criados.
- Constante. Não pode ser excluído ou alterado. Constant é válida somente quando você está criando uma variável. Não é possível alterar as opções de uma variável existente para Constant.
Para ver a propriedade Options de todas as variáveis na sessão, digite Get-Variable | Format-Table -Property name, options -autosize.
Propriedades dos parâmetros
| Tipo: | ScopedItemOptions |
| Default value: | None |
| Valores aceites: | None, ReadOnly, Constant, Private, AllScope, Unspecified |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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, este pode ser qualquer escopo dependendo do contexto.
- Roteiro. 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.
- Privado. As variáveis criadas no âmbito privado não podem ser acedidas fora do âmbito 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 através do número de escopos, onde 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 scope não é especificado.
Para obter mais informações, consulte about_Scopes.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Value
Especifica o valor inicial da variável.
Propriedades dos parâmetros
| Tipo: | Object |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 1 |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-Visibility
Determina se a variável é visível fora da sessão em que foi criada. Este 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ública. A variável é visível. (Público é o padrão.)
- Privado. A variável não é 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 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 escritos na sessão em que a variável foi definida.
Propriedades dos parâmetros
| Tipo: | SessionStateEntryVisibility |
| Default value: | None |
| Valores aceites: | Public, Private |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-WhatIf
Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Wi |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 canalizar 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, esse cmdlet não gerará nenhuma saída.