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.

Syntax

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 Set-Variable cmdlet 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

Esses comandos definem o valor da $desc variável como A descriptione, em seguida, obtém o valor da variável.

Set-Variable -Name "desc" -Value "A description"
Get-Variable -Name "desc"

Name                           Value
----                           -----
desc                           A description

Exemplo 2: Definir uma variável global somente leitura

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

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

O comando usa o Set-Variable cmdlet 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 Format-List cmdlet. Ele usa o parâmetro Propriedade com Format-List 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

Este exemplo 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 fica visível para o usuário.

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 fica visível para o usuário.

Parâmetros

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Description

Especifica a descrição da variável.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Exclude

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

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 ou ReadOnlyConstant. Para obter mais informações, consulte o parâmetro Option .

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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*. Caracteres curinga são permitidos.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:True

-Name

Especifica o nome da variável.

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Option

Especifica o valor da propriedade Options da variável.

Os valores válidos 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.
  • Constant: não pode ser excluído ou alterado. Constant é válido somente quando você está criando uma variável. Você não pode alterar as opções de uma variável existente para Constant.
  • Private: a variável está disponível somente no escopo atual.
  • AllScope: a variável é copiada para quaisquer novos escopos criados.
Type:ScopedItemOptions
Accepted values:None, ReadOnly, Constant, Private, AllScope, Unspecified
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Retorna um objeto que representa a nova variável. Por padrão, este cmdlet não gera saída.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Scope

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

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

Local é o padrão.

Para obter mais informações, consulte about_Scopes.

Type:String
Position:Named
Default value:Local
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Value

Especifica o valor da variável.

Type:Object
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Visibility

Determina se a variável é visível fora da sessão na qual ela 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 é visível. ("Public" é 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 unidade Variável: . 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.

Type:SessionStateEntryVisibility
Accepted values:Public, Private
Position:Named
Default value:Public
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

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

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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, este cmdlet não gera nenhuma saída.