Rename-Item

Artigo
10/30/2009

Renomeia um item em um namespace de provedor do Windows PowerShell.

Sintaxe

Rename-Item [-Path] <string> [-NewName] <string> [-Credential <PSCredential>] [-Force] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Descrição

O cmdlet Rename-Item altera o nome de um item especificado. Este cmdlet não afeta o conteúdo do item renomeado.

Não é possível usar Rename-Item para mover um item, por exemplo, especificando um caminho junto com o novo nome. Para mover e renomear um item, use o cmdlet Move-Item.

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

-Force

Permite que o cmdlet renomeie os itens que não podem ser alterados, como variáveis, aliases ou arquivos somente leitura ou ocultos. O cmdlet não pode alterar os aliases nem as variáveis constantes. A implementação varia de provedor para provedor. Para obter mais informações, consulte about_Providers. Mesmo usando o parâmetro Force, o cmdlet não pode substituir as restrições de segurança.

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

-NewName <string>

Especifica o novo nome do item. Insira apenas um nome, não um caminho e um nome. Se você inserir um caminho diferente daquele especificado no parâmetro Path, Rename-Item gerará um erro. Para mover e renomear um item, use o cmdlet Move-Item.

Você não pode usar caracteres curinga no valor de NewName. Para especificar um nome para vários arquivos, use o operador Replace em uma expressão regular. Para obter mais informações sobre o operador Replace, digite "Get-Help about_Comparison_Operators". Para obter uma demonstração, consulte os exemplos.

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

-PassThru

Passa um objeto que representa o item para o pipeline. 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 para o item a ser renomeado.

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByValue, 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.String

Você pode enviar uma cadeia de caracteres que contém um caminho para Rename-Item.

Saídas

Nenhum ou um objeto que representa o item renomeado.

Quando você usa o parâmetro Passthru, Rename-Item gera um objeto que representa o item renomeado. Caso contrário, esse cmdlet não gera nenhuma saída.

Observações

O cmdlet Rename-Item 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>rename-item -path c:\logfiles\daily_file.txt -newname monday_file.txt

Descrição
-----------
Esse comando renomeia o arquivo daily_file.txt para monday_file.txt.

Exemplo 2

C:\PS>rename-item -path project.txt -newname d:\archive\old-project.txt

Rename-Item : Cannot rename because the target specified represents a path or device name.
At line:1 char:12
+ rename-item <<<<  -path project.txt -newname d:\archive\old-project.txt
    + CategoryInfo          : InvalidArgument: (:) [Rename-Item], PSArgumentException
    + FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.RenameItemCommand


C:\PS> move-item -path project.txt -destination d:\archive\old-project.txt
# Command succeeds

Descrição
-----------
Este exemplo mostra que você não pode usar o cmdlet Rename-Item para renomear e mover um item. Especificamente, não é possível fornecer um caminho para o valor do parâmetro NewName, a menos que o caminho seja idêntico àquele especificado no parâmetro Path. Caso contrário, somente um novo nome será permitido.

O primeiro comando usa o cmdlet Rename-Item para renomear o arquivo project.txt no diretório atual como old-project.txt no diretório D:\Archive. O resultado é o erro mostrado na saída.

O segundo comando mostra a maneira correta de mover e renomear um arquivo usando o cmdlet Move-Item. O cmdlet Move-Item permite especificar um novo caminho e um novo nome no valor do parâmetro Destination.

Exemplo 3

C:\PS>rename-item HKLM:\Software\MyCompany\Advertising -NewName Marketing

Descrição
-----------
Esse comando usa o cmdlet Rename-Item para renomear uma chave do Registro de Advertising para Marketing. Quando o comando for concluído, a chave estará renomeada, mas as entradas do Registro na chave estarão inalteradas.

Exemplo 4

C:\PS>get-childItem *.txt | rename-item -newname { $_.name -replace '\.txt','.log' }

Descrição
-----------
Este exemplo mostra como usar o operador Replace para renomear vários arquivos, embora o parâmetro NewName não aceite caracteres curinga.

Esse comando renomeia todos os arquivos .txt do diretório atual como .log. 

O comando usa um cmdlet Get-ChildItem para obter todos os arquivos no diretório atual que têm uma extensão de nome de arquivo .txt. Em seguida, ele usa o operador de pipeline (|) para enviar os arquivos resultantes para o cmdlet Rename-Item. 

No comando Rename-Item, o valor do parâmetro NewName é um bloco de scripts executado antes que o valor seja enviado para o parâmetro NewName.

No bloco de scripts, a variável automática $_ representa cada objeto de arquivo conforme chega no comando por meio do pipeline. O comando usa o formato de ponto (.) para obter a propriedade Name de cada objeto de arquivo. O operador Replace substitui a extensão de nome de arquivo ".txt" de cada arquivo por ".log".

Como o operador Replace funciona com expressões regulares, o ponto antes de "txt" é interpretado como uma correspondência a qualquer caractere. Para garantir que ele corresponda somente a um ponto (.), usa-se o caractere de escape de barra invertida (\). O caractere de barra invertida não é exigido em ".log" porque é uma cadeia de caracteres, não uma expressão regular.

Consulte também

Conceitos

about_Providers
Clear-Item
Invoke-Item
Move-Item
Rename-ItemProperty
Set-Item
New-Item
Remove-Item
Get-Item
Copy-Item

Compartilhar via