New-Variable
Cria uma nova variável.
Sintaxe
New-Variable [-Name] <string> [[-Value] <Object>] [-Descrição <string>] [-Force] [-Option {<None> | <ReadOnly> | <Constant> | <Private> | <AllScope>}] [-PassThru] [-Scope <string>] [-Visibility {<Public> | <Private>}] [-Confirm] [-WhatIf] [<CommonParameters>]
Descrição
O cmdlet New-Variable cria uma nova variável no Windows PowerShell. Você pode atribuir um valor à variável enquanto a estiver criando ou atribuir ou alterar o valor após sua criação.
Você pode usar os parâmetros de New-Variable para definir as propriedades da variável (como as que criam variáveis somente leitura ou frequentes), definir o escopo de uma variável e determinar se variáveis são públicas ou privadas.
Normalmente, você cria uma nova variável digitando o nome de variável e seu valor, como "$var = 3", mas você pode usar o cmdlet New-Variable para usar seus parâmetros.
Parâmetros
-Descrição <string>
Especifica uma descrição da variável.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Force
Permite criar uma nova 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.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Name <string>
Especifica um nome para a nova variável.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByPropertyName) |
Aceitar caracteres curinga? |
false |
-Option <ScopedItemOptions>
Define o valor da propriedade Options da nova variável.
Os valores válidos são:
-- None: não define nenhuma opção. ("None" é o padrão.)
-- ReadOnly: o valor da variável não pode ser alterado, exceto com o uso do parâmetro Force. É possível usar Remove-Variable para excluir a variável.
-- Constant: a variável não pode ser excluída e suas propriedades não podem ser alteradas. "Constant" está disponível apenas quando você está criando um alias. Não é possível alterar a opção de uma variável existente para "Constant".
-- Private: a variável está disponível apenas no escopo especificado pelo parâmetro Scope. Ela é herdada pelos escopos filho. (Esse valor não é relacionado ao valor "Private" do parâmetro Visibility.)
-- AllScope: a variável é copiada em qualquer novo escopo criado.
Para visualizar a propriedade Options das variáveis, digite "get-variable| Format-Table -property name, options -autosize".
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-PassThru
Retorna um objeto que representa a nova variável. Por padrão, este cmdlet não gera nenhuma saída.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Scope <string>
Determina o escopo da nova variável. Os valores válidos são "Global", "Local" ou "Script" ou um número relativo ao atual escopo (0 ao número de escopos, onde 0 é o escopo atual e 1 é seu pai). "Local" é o padrão. Para obter mais informações, consulte about_Scopes.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Value <Object>
Especifica o valor inicial da variável.
Necessário? |
false |
Posição? |
2 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue, ByPropertyName) |
Aceitar caracteres curinga? |
false |
-Visibility <SessionStateEntryVisibility>
Determina se a variável é visível fora da sessão na qual foi criada. Esse parâmetro é criado para uso em scripts e comandos que serão entregues a outros usuários.
Os valores válidos são:
-- Public: a variável é visível. ("Public" é o padrão.)
-- Private: a variável não é visível.
Quando uma variável é particular, ela não aparece em listas de variáveis, como as retornadas por Get-Variable ou em exibições da unidade Variable: Comandos para ler ou alterar o valor de uma variável particular retornam um erro. No entanto, o usuário poderá executar comandos que usam uma variável particular se os comandos forem escritos na sessão na qual a variável foi definida.
Necessário? |
false |
Posição? |
named |
Valor padrão |
Public |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Confirm
Solicita confirmação antes da execução do comando.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-WhatIf
Descreve o que aconteceria se você executasse o comando, sem executá-lo de fato.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
System.Object Você pode canalizar um valor para New-Variable. |
Saídas |
Nenhum ou 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 gera nenhuma saída. |
Exemplo 1
C:\PS>new-variable days
Descrição
-----------
Esse comando cria uma nova variável denominada "days". Ele não possui valor imediatamente após o comando.
Exemplo 2
C:\PS>new-variable zipcode -value 98033
Descrição
-----------
Esse comando cria uma variável denominada "zipcode" e atribui a ela o valor "98033".
Exemplo 3
C:\PS>new-variable -name max -value 256 -option readonly
new-variable -name max -value 1024
new-variable -name max -value 1024 -force
C:\PS> new-variable -name max -value 256 -option readonly
C:\PS> new-variable -name max -value 1024
New-Variable : A variable with name 'max' already exists.
At line:1 char:13
+ new-variable <<<< -name max -value 1024
C:\PS> new-variable -name max -value 1024 -force
Descrição
-----------
Este exemplo mostra como usar a opção ReadOnly de New-Variable para impedir que uma variável seja substituída.
O primeiro comando cria uma nova variável denominada 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 é definida na variável.
O terceiros comando usa o parâmetro Force para substituir a proteção de somente leitura da variável. Neste caso, o comando para criar uma nova variável com o mesmo nome tem sucesso.
Exemplo 4
C:\PS>new-variable -name counter -visibility private
#Effect of private variable in a module.
C:\PS> get-variable c*
Name Value
---- -----
Culture en-US
ConsoleFileName
ConfirmPreference High
CommandLineParameters {}
C:\PS> $counter
"Cannot access the variable '$counter' because it is a private variable"
C:\PS> Get-Counter
Name Value
---- -----
Counter1 3.1415
...
Descrição
-----------
Este comando demonstra o comportamento de uma variável particular em um módulo. O módulo contém o cmdlet Get-Counter, que tem uma variável particular denominada "Counter". O comando usa o parâmetro Visibility com um valor de "Private" para criar a variável.
O exemplo de saída mostra o comportamento de uma variável particular. O usuário que carregou o módulo não pode exibir nem alterar o valor da variável Counter, mas a variável Counter pode ser lida e alterada pelos comandos do módulo.