Set-Variable

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

Sintaxe

Set-Variable [-Name] <string[]> [[-Value] <Object>] [-Description <string>] [-Exclude <string[]>] [-Force] [-Include <string[]>] [-Option {<None> | <ReadOnly> | <Constant> | <Private> | <AllScope>}] [-PassThru] [-Scope <string>] [-Visibility {<Public> | <Private>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Descrição

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á.

Parâmetros

-Description <string>

Especifica a descrição da variável.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Exclude <string[]>

Omite os itens especificados. O valor desse parâmetro qualifica o parâmetro Path. Digite um elemento ou padrão do caminho, como "*.txt". Os caracteres curinga são permitidos.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Force

Permite criar uma variável com o mesmo nome que uma variável somente leitura existente ou alterar 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 Option.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Include <string[]>

Altera somente os itens especificados. O valor desse parâmetro qualifica o parâmetro Name. Digite um nome ou um padrão de nome, como "c*". Os caracteres curinga são permitidos.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Name <string[]>

Especifica o nome da variável.

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Option <ScopedItemOptions>

Altera 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: as propriedades da variável não podem ser alteradas, 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.

-- 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 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 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 objeto que representa o valor da variável para Set-Variable.
Saídas	Nenhum ou 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 gera nenhuma saída.

Exemplo 1

C:\PS>set-variable -name desc -value "A description"

C:\PS>get-variable -name desc

Descrição
-----------
Esses comandos definem o valor da variável "desc" para "uma descrição" e, em seguida, obtêm o valor da variável.

Exemplo 2

C:\PS>set-variable -name processes -value (Get-Process) -option constant -scope global -description "All processes" -passthru | format-list -property *

Descrição
-----------
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 Property de Format-List com um valor de all (*) para exibir todas as propriedades da variável recém-criada. 

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

Exemplo 3

C:\PS># set-variable -name counter -visibility private

C:\PS> new-variable -name counter -visibility public -value 26

C:\PS> $counter
26

C:\PS> get-variable c*

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

C:\PS> set-variable -name counter -visibility private

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> .\use-counter.ps1
Commands completed successfully.

Descrição
-----------
Esse 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 é visível para o usuário.

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

Consulte também

Conceitos

Get-Variable
New-Variable
Remove-Variable
Clear-Variable