Compartilhar via

Set-Variable

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

Define o valor de uma variável. Cria a variável se uma com o nome solicitado não existir.

Sintaxe

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

Description

O cmdlet Set-Variable atribui um valor a uma variável especificada ou altera o valor atual. Se a variável não existir, o cmdlet a criará.

Exemplos

Exemplo 1: Definir uma variável e obter seu valor

PS C:\> Set-Variable -Name "desc" -Value "A description"
PS C:\> Get-Variable -Name "desc"

Esses comandos definem o valor da variável de desc como Uma descrição e, em seguida, obtém o valor da variável.

Exemplo 2: Definir uma variável global somente leitura

PS C:\> Set-Variable -Name "processes" -Value (Get-Process) -Option constant -Scope global -Description "All processes" -PassThru | Format-List -Property *

Esse comando cria uma variável global somente leitura que contém todos os processos no sistema e, em seguida, exibe todas as propriedades da variável.

O comando usa o cmdlet Set-Variable para criar a variável. Ele usa o parâmetro PassThru para criar um objeto que representa a nova variável e usa o operador de pipeline (|) para passar o objeto para o cmdlet Format-List. Ele usa o parâmetro propriedade de Format-List com um valor de todos (*) para exibir todas as propriedades da variável recém-criada.

O valor , "(Get-Process)", é colocado entre parênteses para garantir que ele seja executado antes de ser armazenado na variável. Caso contrário, a variável contém as palavras "Get-Process".

Exemplo 3: Entender variáveis públicas versus privadas

PS C:\> New-Variable -Name "counter" -Visibility Public -Value 26
PS C:\> $Counter
26
PS C:\> Get-Variable c*

Name                  Value
----                  -----
Culture               en-US
ConsoleFileName
ConfirmPreference     High
CommandLineParameters {}
Counter               26

PS C:\> Set-Variable -Name "counter" -Visibility Private
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"

PS C:\> .\use-counter.ps1
#Commands completed successfully.

Este comando mostra como alterar a visibilidade de uma variável para Private. Essa variável pode ser lida e alterada por scripts com as permissões necessárias, mas não está visível para o usuário.

A saída de exemplo mostra a diferença no comportamento de variáveis públicas e privadas.

Parâmetros

-Confirm

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

-Exclude

Especifica uma matriz de itens que esse cmdlet exclui da operação. O valor desse parâmetro qualifica o parâmetro Path. Insira um elemento ou padrão de caminho, como *.txt. Curingas são permitidos.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-Force

Permite que você crie uma variável com o mesmo nome de uma variável somente leitura existente ou altere o valor de uma variável somente leitura.

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 .

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Include

Especifica uma matriz de itens que esse cmdlet inclui na operação. O valor desse parâmetro qualifica o parâmetro Name. Insira um padrão de nome ou nome, como c*. Curingas são permitidos.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-Name

Especifica o nome da 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 válidos são:

  • Nenhum: não define nenhuma opção. ("Nenhum" é o padrão.)
  • ReadOnly: pode ser excluído. Não é possível alterar, exceto usando o parâmetro Force.
  • Constante: não pode ser excluído ou alterado. "Constante" é válido somente quando você está criando uma variável. Não é possível alterar as opções de uma variável existente para "Constante".
  • Privado: a variável está disponível apenas no escopo atual.
  • AllScope: a variável é copiada para quaisquer novos escopos criados.

Para ver a propriedade Options 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 a nova variável. Por padrão, esse cmdlet não gera nenhuma saída.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Scope

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

  • Global
  • Local
  • Roteiro
  • Privado
  • Um número relativo ao escopo atual (0 por meio do número de escopos, em que 0 é o escopo atual e 1 é o pai).

Local é o padrão.

Para obter mais informações, consulte about_Scopes.

Tipo:String
Cargo:Named
Valor padrão:Local
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Value

Especifica o valor 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 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 válidos são:

  • Público: A variável está visível. ("Público" é o padrão.)
  • Privado: 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 variável: unidade. 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.

Tipo:SessionStateEntryVisibility
Valores aceitos:Public, Private
Cargo:Named
Valor padrão:Public
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

Object

Você pode canalizar um objeto que representa o valor da variável para set-variable.

Saídas

None or System.Management.Automation.PSVariable

Quando você usa o parâmetro PassThru, set-variable gera um objeto System.Management.Automation.PSVariable que representa a variável nova ou alterada. Caso contrário, esse cmdlet não gerará nenhuma saída.