Set-ItemProperty

Cria ou altera o valor de uma propriedade de um item.

Sintaxe

Set-ItemProperty [-LiteralPath] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Set-ItemProperty [-Path] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Set-ItemProperty [-LiteralPath] <string[]> [-Name] <string> [-Value] <Object> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Set-ItemProperty [-Path] <string[]> [-Name] <string> [-Value] <Object> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Descrição

O cmdlet Set-ItemProperty altera o valor da propriedade do item especificado. Você pode usar o cmdlet para estabelecer ou alterar as propriedades de itens. Por exemplo, use Set-ItemProperty para definir o valor da propriedade IsReadOnly de um objeto de arquivo como true.

Use-o também Set-ItemProperty para criar e alterar valores e dados do Registro. Por exemplo, você pode adicionar uma nova entrada do Registro a uma chave e estabelecer ou alterar seu valor.

Parâmetros

-Credential <PSCredential>

Especifica uma conta de usuário com permissão para executar essa ação. O padrão é o usuário atual.

Digite um nome de usuário, como "User01" ou "Domain01\User01", ou insira um objeto PSCredential, como aquele gerado pelo cmdlet Get-Credential. Uma senha será solicitada após a digitação do nome do usuário.

Este parâmetro não tem suporte em nenhum dos provedores instalados com o Windows PowerShell.

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

-Exclude <string[]>

Especifica os itens em que o cmdlet não agirá, incluindo todos os outros.

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

-Filter <string>

Especifica um filtro no formato ou no idioma do provedor. O valor desse parâmetro qualifica o parâmetro Path. A sintaxe do filtro, incluindo o uso dos caracteres curinga, depende do provedor. Os filtros são mais eficientes que outros parâmetros, porque o provedor os aplica durante a recuperação dos objetos, em vez de fazer com que o Windows PowerShell os filtre depois de recuperados.

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

-Force

Permite que o cmdlet defina uma propriedade em itens que não podem ser acessados de outra forma pelo usuário. A implementação varia de provedor para provedor. Para obter mais informações, consulte about_Providers.

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

-Include <string[]>

Especifica somente os itens em que o cmdlet agirá, excluindo todos os outros.

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

-InputObject <psobject>

Especifica o objeto que tem as propriedades que você deseja alterar. Insira uma variável que contenha o objeto ou um comando que obtenha o objeto.

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

-LiteralPath <string[]>

Especifica o caminho até a propriedade do item. O valor de LiteralPath é usado exatamente como é digitado. Nenhum caractere será interpretado como curinga. Se o caminho incluir caracteres de escape, coloque-os entre aspas simples. As aspas simples dizem ao Windows PowerShell para não interpretar quaisquer caracteres que tenham sequências de escape.

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

-Name <string>

Especifica o nome da propriedade.

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

-PassThru

Retorna um objeto que representa a propriedade do item. 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

-Path <string[]>

Especifica o caminho até os itens cuja propriedade será definida.

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

-Value <Object>

Especifica o valor da propriedade.

Necessário?	true
Posição?	3
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
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

-UseTransaction

Inclui o comando na transação ativa. Este parâmetro é válido apenas quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions.

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.Management.Automation.PSObject Você pode enviar objetos para Set-ItemProperty.
Saídas	Nenhum ou System.Management.Automation.PSCustomObject Quando você usa o parâmetro PassThru, Set-ItemProperty gera um objeto PSCustomObject que representa o item alterado e seu novo valor de propriedade. Caso contrário, esse cmdlet não gera nenhuma saída.

Observações

O cmdlet Set-ItemProperty foi desenvolvido para funcionar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis em sua sessão, digite "Get-PSProvider". Para obter mais informações, consulte about_Providers.

Exemplo 1

C:\PS>set-itemproperty -path c:\GroupFiles\final.doc -name IsReadOnly -value $true

Descrição
-----------
Esse comando define o valor da propriedade IsReadOnly do arquivo do final.doc como true. 

O comando usa o cmdlet Set-ItemProperty para alterar o valor da propriedade do arquivo final.doc. Ele usa o parâmetro Path para especificar o arquivo. Ele usa o parâmetro Name para especificar o nome da propriedade e o parâmetro Value para especificar o novo valor.

A variável automática $true representa um valor de TRUE. Para obter mais informações, consulte about_Automatic_Variables.

O arquivo é um objeto System.IO.FileInfo e IsReadOnly é apenas uma de suas propriedades. Para ver todas as propriedades e métodos de um objeto FileInfo, envie o arquivo por pipe para o cmdlet Get-Member. Por exemplo, "final.doc | get-member".

Exemplo 2

C:\PS>set-itemproperty -path HKLM:\Software\MyCompany -name NoOfEmployees -value 823

C:\PS>get-itemproperty -path HKLM:\Software\MyCompany

PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
PSParentPath  : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
PSChildName   : mycompany
PSDrive       : HKLM
PSProvider    : Microsoft.PowerShell.Core\Registry
NoOfLocations : 2
NoOfEmployees : 823

C:\PS>set-itemproperty -path HKLM:\Software\MyCompany -name NoOfEmployees -value 824
C:\PS>get-itemproperty -path HKLM:\Software\MyCompany


PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
PSParentPath  : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
PSChildName   : mycompany
PSDrive       : HKLM
PSProvider    : Microsoft.PowerShell.Core\Registry
NoOfLocations : 2
NoOfEmployees : 824

Descrição
-----------
Esse exemplo mostra como usar Set-ItemProperty para criar uma nova entrada do Registro e atribuir um valor à entrada. Ele cria a entrada NoOfEmployees na chave MyCompany na chave HKLM\Software e define seu valor como 823.

Como as entradas do Registro são consideradas como propriedades das chaves do Registro (que são itens), use Set-ItemProperty para criar entradas do Registro e estabelecer e alterar seus valores.

O primeiro comando usa o cmdlet Set-ItemProperty para criar a entrada do Registro. Ele usa o parâmetro Path para especificar o caminho para a unidade HKLM: e a chave Software\MyCompany. Ele usa o parâmetro Name para especificar o nome da entrada e o parâmetro Value para especificar um valor.

O segundo comando usa o cmdlet Get-ItemProperty para ver a nova entrada do Registro. Se você usar o cmdlet Get-Item ou Get-ChildItem, as entradas não serão exibidas, porque elas são propriedades de uma chave, não itens ou itens filho.

O terceiro comando altera o valor da entrada NoOfEmployees para 824.

Você também pode usar o cmdlet New-ItemProperty para criar a entrada do Registro e seu valor e, em seguida, usar Set-ItemProperty para alterar o valor.

Para obter mais informações sobre a unidade HKLM:, digite "get-help get-psdrive". Para obter mais informações sobre o uso do Windows PowerShell para gerenciar o Registro, digite "get-help registry".

Exemplo 3

C:\PS>get-childitem weekly.txt | set-itemproperty -name IsReadOnly -value $true

Descrição
-----------
Esses comandos mostram como usar um operador pipeline (|) para enviar um item para Set-ItemProperty. 

A primeira parte do comando usa o cmdlet Get-ChildItem para obter um objeto que representa o arquivo Weekly.txt. O comando usa um operador de pipeline (|) para enviar o objeto de arquivo para Set-ItemProperty. O comando Set-ItemProperty usa os parâmetros Name e Value para especificar a propriedade e seu novo valor.

Esse comando equivale a usar o parâmetro InputObject para especificar o objeto que Get-ChildItem obtém.

Consulte também

Conceitos

about_Providers
Get-ItemProperty
New-ItemProperty
Clear-ItemProperty
Remove-ItemProperty
Rename-ItemProperty
Move-ItemProperty
Copy-ItemProperty