Rename-Item
Cambiar el nombre de un elemento en un espacio de nombres de un proveedor de Windows PowerShell.
Sintaxis
Rename-Item [-Path] <string> [-NewName] <string> [-Credential <PSCredential>] [-Force] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]
Descripción
El cmdlet Rename-Item cambia el nombre de un elemento especificado. Este cmdlet no afecta al contenido del elemento cuyo nombre se va a cambiar.
No se puede utilizar Rename-Item para mover un elemento especificando, por ejemplo, una ruta de acceso junto con el nuevo nombre. Para mover y cambiar el nombre de un elemento, utilice el cmdlet Move-Item.
Parámetros
-Credential <PSCredential>
Especifica una cuenta de usuario con permiso para realizar esta acción. El valor predeterminado es el usuario actual.
Escriba un nombre de usuario, como "Usuario01" o "Dominio01\Usuario01", o bien, escriba un objeto PSCredential, como uno generado por el cmdlet Get-Credential. Si escribe un nombre de usuario se le pedirá una contraseña.
Este parámetro no es compatible con los proveedores que se instalan con Windows PowerShell.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
true (ByPropertyName) |
¿Aceptar caracteres comodín? |
false |
-Force
Permite al cmdlet cambiar el nombre de los elementos que no se pueden cambiar de ningún otro modo, como archivos ocultos o de solo lectura, o bien, alias o variables de solo lectura. El cmdlet no puede cambiar variables ni alias de constantes. La implementación varía según el proveedor. Para obtener más información, vea about_Providers. Incluso si se usa el parámetro Force, el cmdlet no puede invalidar las restricciones de seguridad.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
false |
¿Aceptar caracteres comodín? |
false |
-NewName <string>
Especifica el nuevo nombre del elemento. Escriba solamente un nombre, no una ruta de acceso y un nombre. Si escribe una ruta de acceso diferente de la ruta de acceso especificada en el parámetro Path, Rename-Item genera un error. Para cambiar de nombre y mover un elemento, utilice el cmdlet Move-Item.
No puede utilizar caracteres comodín en el valor de NewName. Para especificar un nombre para varios archivos, utilice el operador Replace en una expresión regular. Para obtener más información sobre el operador Replace, escriba "Get-Helpabout_Comparison_Operators". Para obtener una demostración, vea los ejemplos.
¿Requerido? |
true |
¿Posición? |
2 |
Valor predeterminado |
|
¿Aceptar canalización? |
true (ByPropertyName) |
¿Aceptar caracteres comodín? |
false |
-PassThru
Pasa a la canalización un objeto que representa el elemento. De forma predeterminada, este cmdlet no genera resultados.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
false |
¿Aceptar caracteres comodín? |
false |
-Path <string>
Especifica la ruta del elemento cuyo nombre se va a cambiar.
¿Requerido? |
true |
¿Posición? |
1 |
Valor predeterminado |
|
¿Aceptar canalización? |
true (ByValue, ByPropertyName) |
¿Aceptar caracteres comodín? |
false |
-Confirm
Solicita confirmación antes de ejecutar el comando.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
false |
¿Aceptar caracteres comodín? |
false |
-WhatIf
Describe lo que ocurriría si ejecutara el comando sin ejecutarlo realmente.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
false |
¿Aceptar caracteres comodín? |
false |
-UseTransaction
Incluye el comando en la transacción activa. Este parámetro solo es válido cuando hay una transacción en curso. Para obtener más información, vea about_Transactions.
¿Requerido? |
false |
¿Posición? |
named |
Valor predeterminado |
|
¿Aceptar canalización? |
false |
¿Aceptar caracteres comodín? |
false |
<CommonParameters>
Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.
Entradas y salidas
El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.
Entradas |
System.String Puede canalizar una cadena que contiene una ruta de acceso a Rename-Item. |
Salidas |
Ninguno o un objeto que representa el elemento cuyo nombre ha cambiado. Cuando se usa el parámetro Passthru, Rename-Item genera un objeto que representa el elemento cuyo nombre ha cambiado. En caso contrario, este cmdlet no genera resultados. |
Notas
El cmdlet Rename-Item está diseñado de modo que funcione con los datos expuestos por cualquier proveedor. Para mostrar los proveedores que están disponibles en la sesión, escriba "Get-PsProvider". Para obtener más información, vea about_Providers.
Ejemplo 1
C:\PS>rename-item -path c:\logfiles\daily_file.txt -newname monday_file.txt
Descripción
-----------
Este comando cambia el nombre del archivo daily_file.txt a monday_file.txt.
Ejemplo 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
Descripción
-----------
En este ejemplo, se muestra que no se puede utilizar el cmdlet Rename-Item para cambiar de nombre y mover un elemento. Concretamente, no se puede proporcionar una ruta de acceso para el valor del parámetro NewName, a menos que sea idéntica a la ruta de acceso especificada en el parámetro Path. De lo contrario, solo se permite un nuevo nombre.
El primer comando utiliza el cmdlet Rename-Item para cambiar el nombre del archivo project.txt en el directorio actual a old-project.txt en el directorio D:\Archive. El resultado es el error que se muestra en la salida.
El segundo comando muestra la forma correcta de mover y cambiar el nombre de un archivo utilizando el cmdlet Move-Item. El cmdlet Move-Item permite especificar una nueva ruta de acceso y un nuevo nombre en el valor de su parámetro Destination.
Ejemplo 3
C:\PS>rename-item HKLM:\Software\MyCompany\Advertising -NewName Marketing
Descripción
-----------
Este comando utiliza el cmdlet Rename-Item para cambiar el nombre de una clave del Registro de Advertising a Marketing. Cuando el comando se completa, se cambia el nombre de la clave, pero las entradas del Registro en la clave permanecen inalteradas.
Ejemplo 4
C:\PS>get-childItem *.txt | rename-item -newname { $_.name -replace '\.txt','.log' }
Descripción
-----------
En este ejemplo se muestra la forma de utilizar el operador Replace para cambiar el nombre de varios archivos, aunque el parámetro NewName no acepte caracteres comodín.
Este comando cambia el nombre de los archivos .txt del directorio actual a .log.
El comando utiliza un cmdlet Get-ChildItem para obtener todos los archivos del directorio actual que tienen una extensión de nombre de archivo .txt. A continuación, utiliza el operador de canalización (|) para enviar los archivos resultantes al cmdlet Rename-Item.
En el comando Rename-Item, el valor del parámetro NewName es un bloque de script que se ejecuta antes de que se envíe el valor al parámetro NewName.
En el bloque de script, la variable automática $_ representa cada objeto de archivo que llega al comando a través de la canalización. El comando usa el formato con punto (.) para obtener la propiedad Name de cada objeto de archivo. El operador Replace reemplaza la extensión de nombre de archivo ".txt" de cada archivo por ".log".
Dado que el operador Replace funciona con expresiones regulares, el punto que precede a "txt" se interpreta como equivalente a cualquier carácter. Para garantizar la equivalencia solo con un punto (.), se utiliza una barra diagonal inversa como carácter de escape (\). La barra diagonal inversa no se requiere en ".log" porque es una cadena y no una expresión regular.
Vea también
Conceptos
about_Providers
Clear-Item
Invoke-Item
Move-Item
Rename-ItemProperty
Set-Item
New-Item
Remove-Item
Get-Item
Copy-Item