Lección 8 de 8: un proyecto completo en PowerShell. Vamos a juntar todo el curso en una herramienta útil: un script que ordena la carpeta de Descargas en subcarpetas por tipo de archivo, sin perder nunca un archivo, con -WhatIf para ver antes lo que hará, un registro en CSV, pruebas automáticas con Pester y la tarea programada para que Windows lo ejecute cada noche.
El plan
La carpeta de Descargas de casi todo el mundo es un cajón de sastre: fotos, PDF de facturas, instaladores, ZIP, todo revuelto. Vamos a escribir una herramienta que la ordene en subcarpetas según el tipo de archivo, y a hacerlo como se hace en un proyecto de verdad:
- La lógica va en un módulo (
Organizador.psm1), con funciones pequeñas que se pueden probar por separado. - Un script (
ordenar.ps1) recibe la carpeta como parámetro, admite-WhatIfy guarda un registro en CSV de lo que movió. - Nunca se pierde un archivo: si ya existe uno con el mismo nombre en el destino, el nuevo se renombra.
- Unas pruebas automáticas con Pester comprueban que todo eso funciona, en una carpeta temporal y sin tocar tus archivos.
El módulo
Tres funciones: Get-TipoArchivo decide la carpeta según la extensión, Get-NombreLibre busca un nombre que no choque con otro (foto (2).jpg, foto (3).jpg…) y Move-ArchivoPorTipo hace el trabajo, con SupportsShouldProcess para que -WhatIf funcione. Las carpetas van sin acentos («Imagenes») para no tener sorpresas con programas viejos.
# Organizador.psm1: funciones para ordenar una carpeta por tipo de archivo.
function Get-TipoArchivo {
[CmdletBinding()]
[OutputType([string])]
param([Parameter(Mandatory)][AllowEmptyString()][string]$Extension)
switch -Regex ($Extension.ToLowerInvariant()) {
'^\.(jpg|jpeg|png|gif|webp|heic)$' { 'Imagenes'; break }
'^\.(pdf|docx?|xlsx?|pptx?|txt|csv)$' { 'Documentos'; break }
'^\.(zip|7z|rar)$' { 'Comprimidos'; break }
'^\.(mp3|mp4|mov|wav)$' { 'Multimedia'; break }
default { 'Otros' }
}
}
function Get-NombreLibre {
[CmdletBinding()]
[OutputType([string])]
param([Parameter(Mandatory)][string]$Carpeta, [Parameter(Mandatory)][string]$Nombre)
$base = [System.IO.Path]::GetFileNameWithoutExtension($Nombre)
$ext = [System.IO.Path]::GetExtension($Nombre)
$candidato = $Nombre
$n = 2
while (Test-Path -LiteralPath (Join-Path $Carpeta $candidato)) {
$candidato = "$base ($n)$ext"
$n++
}
$candidato
}
function Move-ArchivoPorTipo {
[CmdletBinding(SupportsShouldProcess)]
param([Parameter(Mandatory)][string]$Ruta)
foreach ($archivo in Get-ChildItem -LiteralPath $Ruta -File) {
$tipo = Get-TipoArchivo -Extension $archivo.Extension
$carpeta = Join-Path $Ruta $tipo
if ($PSCmdlet.ShouldProcess($archivo.Name, "Mover a $tipo")) {
if (-not (Test-Path -LiteralPath $carpeta)) {
$null = New-Item -ItemType Directory -Path $carpeta
}
$nombre = Get-NombreLibre -Carpeta $carpeta -Nombre $archivo.Name
Move-Item -LiteralPath $archivo.FullName -Destination (Join-Path $carpeta $nombre)
[pscustomobject]@{ Archivo = $archivo.Name; Carpeta = $tipo; NuevoNombre = $nombre }
}
}
}
Export-ModuleMember -Function Get-TipoArchivo, Get-NombreLibre, Move-ArchivoPorTipoTodo lo usaste ya en el curso: switch -Regex de la lección 3, objetos con [pscustomobject] de la lección 4, ShouldProcess de la lección 5 y -LiteralPath de la lección 6, para que un nombre con corchetes no se tome como comodín. [OutputType([string])] documenta qué devuelve cada función, y ToLowerInvariant() convierte a minúsculas igual en cualquier idioma del sistema.
El script
<#
.SYNOPSIS
Ordena los archivos de una carpeta en subcarpetas según su tipo.
.EXAMPLE
.\ordenar.ps1 -Ruta "$HOME\Downloads" -WhatIf
#>
[CmdletBinding(SupportsShouldProcess)]
param(
[Parameter(Mandatory)]
[ValidateScript({ Test-Path -LiteralPath $_ -PathType Container })]
[string]$Ruta,
[string]$Registro = (Join-Path $PSScriptRoot 'registro-ordenar.csv')
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
Import-Module (Join-Path $PSScriptRoot 'Organizador.psm1') -Force
$movidos = @(Move-ArchivoPorTipo -Ruta $Ruta -WhatIf:$WhatIfPreference)
if ($movidos.Count -eq 0) {
'No se movió ningún archivo.'
return
}
$fecha = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
$movidos |
Select-Object @{ Name = 'Fecha'; Expression = { $fecha } }, Archivo, Carpeta, NuevoNombre |
Export-Csv -Path $Registro -Append -NoTypeInformation -Encoding utf8BOM
$movidos | Group-Object Carpeta | Sort-Object Name | ForEach-Object {
'{0,-12} {1} archivo(s)' -f $_.Name, $_.Count
}
"Registro: $(Split-Path $Registro -Leaf)"Las primeras líneas son la ayuda (Get-Help .\ordenar.ps1 la muestra). [ValidateScript()] comprueba que la ruta sea una carpeta que existe antes de empezar. Después vienen las dos líneas de seguridad de la lección 7, Set-StrictMode y $ErrorActionPreference = 'Stop', y el módulo se importa desde $PSScriptRoot, la carpeta del propio script, para que funcione lo ejecutes desde donde lo ejecutes.
Probarlo
Creamos una carpeta Descargas de prueba con siete archivos y ejecutamos primero con -WhatIf, que es lo que deberías hacer siempre la primera vez:
consolaPS> $null = New-Item -ItemType Directory -Path Descargas
PS> "foto.jpg", "IMG_2041.JPG", "factura.pdf", "reporte.xlsx", "fotos.zip", "cancion.mp3", "instalador.exe" | ForEach-Object { Set-Content -Path "Descargas/$_" -Value $_ }
PS> ./ordenar.ps1 -Ruta Descargas -WhatIf
What if: Performing the operation "Mover a Multimedia" on target "cancion.mp3".
What if: Performing the operation "Mover a Documentos" on target "factura.pdf".
What if: Performing the operation "Mover a Imagenes" on target "foto.jpg".
What if: Performing the operation "Mover a Comprimidos" on target "fotos.zip".
What if: Performing the operation "Mover a Imagenes" on target "IMG_2041.JPG".
What if: Performing the operation "Mover a Otros" on target "instalador.exe".
What if: Performing the operation "Mover a Documentos" on target "reporte.xlsx".
No se movió ningún archivo.
PS> ./ordenar.ps1 -Ruta Descargas
Comprimidos 1 archivo(s)
Documentos 2 archivo(s)
Imagenes 2 archivo(s)
Multimedia 1 archivo(s)
Otros 1 archivo(s)
Registro: registro-ordenar.csv
PS> Get-ChildItem -Path Descargas -Recurse -File | ForEach-Object { "{0}/{1}" -f $_.Directory.Name, $_.Name } | Sort-Object
Comprimidos/fotos.zip
Documentos/factura.pdf
Documentos/reporte.xlsx
Imagenes/foto.jpg
Imagenes/IMG_2041.JPG
Multimedia/cancion.mp3
Otros/instalador.exe
PS> Set-Content -Path "Descargas/foto.jpg" -Value "otra foto"
PS> ./ordenar.ps1 -Ruta Descargas
Imagenes 1 archivo(s)
Registro: registro-ordenar.csv
PS> Import-Csv registro-ordenar.csv | Select-Object Archivo, Carpeta, NuevoNombre -Last 2
Archivo Carpeta NuevoNombre
------- ------- -----------
reporte.xlsx Documentos reporte.xlsx
foto.jpg Imagenes foto (2).jpg
PS> ./ordenar.ps1 -Ruta NoExiste
ordenar.ps1: Cannot validate argument on parameter 'Ruta'. The " Test-Path -LiteralPath $_ -PathType Container " validation script for the argument with value "NoExiste" did not return a result of True. Determine why the validation script failed, and then try the command again.Con -WhatIf dijo qué haría con cada archivo y no movió nada. La segunda vez los ordenó. Luego llegó otra foto.jpg y, como ya había una en Imagenes, se guardó como foto (2).jpg, y el registro lo dejó anotado. La última línea enseña la validación: una carpeta que no existe se rechaza antes de hacer nada.
El error que te ahorra: el -WhatIf que no llega al módulo
En el script, la llamada al módulo lleva -WhatIf:$WhatIfPreference. Parece redundante, pero mira qué pasa con una versión sin ese detalle, ordenar_mal.ps1:
consolaPS> $null = New-Item -ItemType Directory -Path Descargas PS> Set-Content -Path "Descargas/contrato.pdf" -Value "x" PS> ./ordenar_mal.ps1 -Ruta Descargas -WhatIf What if: Performing the operation "Export-Csv" on target "/home/ana/proyecto/registro-ordenar.csv". Documentos 1 archivo(s) Registro: registro-ordenar.csv PS> Get-ChildItem -Path Descargas -Recurse -Name Documentos Documentos/contrato.pdf
Le pedimos que no hiciera nada y movió el contrato: el único «What if» fue el de Export-Csv, un cmdlet normal. Las funciones de un módulo no heredan las preferencias del script que las llama, y -WhatIf es una de ellas. Por eso hay que pasarlo de forma explícita. Es exactamente el tipo de fallo que una prueba automática debería atrapar, y por eso la siguiente sección prueba -WhatIf.
Las pruebas con Pester
Pester es el marco de pruebas de PowerShell. Una prueba es un bloque It que hace algo y comprueba el resultado con Should; los It se agrupan en bloques Describe. $TestDrive es una carpeta temporal que Pester crea para las pruebas y borra al terminar, así que nunca se tocan tus archivos de verdad. En PowerShell 7 se instala con Install-PSResource Pester. Windows 10 y posteriores traen de serie, para la 5.1, Pester 3.4.0, que es muy vieja y no entiende esta sintaxis; allí se instala la nueva con Install-Module -Name Pester -Force -SkipPublisherCheck, como indica la documentación de Pester. Este curso usa Pester 6.2.
BeforeAll {
Import-Module (Join-Path $PSScriptRoot 'Organizador.psm1') -Force
}
Describe 'Get-TipoArchivo' {
It 'reconoce <Extension> como <Esperado>' -ForEach @(
@{ Extension = '.jpg'; Esperado = 'Imagenes' }
@{ Extension = '.PDF'; Esperado = 'Documentos' }
@{ Extension = '.zip'; Esperado = 'Comprimidos' }
@{ Extension = '.exe'; Esperado = 'Otros' }
@{ Extension = ''; Esperado = 'Otros' }
) {
Get-TipoArchivo -Extension $Extension | Should -Be $Esperado
}
}
Describe 'Move-ArchivoPorTipo' {
BeforeEach {
$carpeta = Join-Path $TestDrive 'Descargas'
$null = New-Item -ItemType Directory -Path $carpeta -Force
Get-ChildItem -LiteralPath $carpeta | Remove-Item -Recurse
'a' | Set-Content (Join-Path $carpeta 'foto.jpg')
'b' | Set-Content (Join-Path $carpeta 'factura.pdf')
}
It 'mueve cada archivo a la carpeta de su tipo' {
Move-ArchivoPorTipo -Ruta $carpeta | Out-Null
Join-Path $carpeta 'Imagenes/foto.jpg' | Should -Exist
Join-Path $carpeta 'Documentos/factura.pdf' | Should -Exist
}
It 'no sobrescribe: renombra si ya existe' {
$null = New-Item -ItemType Directory -Path (Join-Path $carpeta 'Imagenes')
'vieja' | Set-Content (Join-Path $carpeta 'Imagenes/foto.jpg')
$r = Move-ArchivoPorTipo -Ruta $carpeta | Where-Object Archivo -EQ 'foto.jpg'
$r.NuevoNombre | Should -Be 'foto (2).jpg'
}
It 'con -WhatIf no mueve nada' {
Move-ArchivoPorTipo -Ruta $carpeta -WhatIf
(Get-ChildItem -LiteralPath $carpeta -File).Count | Should -Be 2
}
}Con -ForEach, un mismo It se ejecuta una vez por cada caso de la lista, y <Extension> en el nombre se sustituye por el valor. BeforeEach prepara una carpeta limpia antes de cada prueba. Se ejecutan con Invoke-Pester:
consolaPS> Invoke-Pester -Path ./Organizador.Tests.ps1 -Output Detailed Pester v6.2.0 Running tests from 1 files. Running tests from '/home/ana/proyecto/Organizador.Tests.ps1' Describing Get-TipoArchivo [+] reconoce .jpg como Imagenes [+] reconoce .PDF como Documentos [+] reconoce .zip como Comprimidos [+] reconoce .exe como Otros [+] reconoce como Otros Describing Move-ArchivoPorTipo [+] mueve cada archivo a la carpeta de su tipo [+] no sobrescribe: renombra si ya existe What if: Performing the operation "Mover a Documentos" on target "factura.pdf". What if: Performing the operation "Mover a Imagenes" on target "foto.jpg". [+] con -WhatIf no mueve nada Tests completed in Tests Passed: 8, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0
Ocho pruebas, ocho aprobadas. (Pester escribe también cuántos milisegundos tardó cada una; los quitamos porque cambian en cada ejecución.) Las líneas «What if» son de la última prueba, que comprueba justamente que con -WhatIf los dos archivos sigan en su lugar. Si alguien cambia el módulo y rompe algo, Invoke-Pester lo dice en segundos, con el nombre de la prueba que falló, lo que esperaba y lo que obtuvo.
$avisos = Invoke-ScriptAnalyzer -Path . -Recurse -Severity Warning, Error "Archivos revisados: $((Get-ChildItem -Filter *.ps*1).Count). Avisos: $(@($avisos).Count)"
salidaArchivos revisados: 5. Avisos: 0
Y PSScriptAnalyzer no tiene nada que decir de ninguno de los archivos del proyecto.
Que se ejecute solo cada noche
Solo en Windows
El Programador de tareas de Windows ejecuta programas a una hora fija, y se configura desde PowerShell con el módulo ScheduledTasks, que viene con Windows. Esto programa el script todos los días a las 9 de la noche (ajusta las rutas a las tuyas):
$accion = New-ScheduledTaskAction -Execute "pwsh.exe" `
-Argument '-NoProfile -File "C:\Scripts\ordenar.ps1" -Ruta "C:\Users\ana\Downloads"'
$disparador = New-ScheduledTaskTrigger -Daily -At 9pm
Register-ScheduledTask -TaskName "Ordenar Descargas" -Action $accion -Trigger $disparadorEl acento grave al final de la primera línea dice que la orden sigue en la siguiente; no puede llevar ni un espacio después. La tarea aparece en el Programador de tareas, donde puedes ver cuándo se ejecutó y con qué código terminó. Para quitarla: Unregister-ScheduledTask -TaskName "Ordenar Descargas". No pudimos ejecutar esto en el contenedor Linux del curso, así que aquí no hay salida.
Retos
Reto 1. Añade una prueba que compruebe que Get-NombreLibre devuelve informe (3).pdf cuando ya existen informe.pdf e informe (2).pdf.
Ver la solución
Describe 'Get-NombreLibre' {
It 'salta los nombres ocupados' {
'x' | Set-Content (Join-Path $TestDrive 'informe.pdf')
'x' | Set-Content (Join-Path $TestDrive 'informe (2).pdf')
Get-NombreLibre -Carpeta $TestDrive -Nombre 'informe.pdf' | Should -Be 'informe (3).pdf'
}
}consolaPS> Copy-Item Organizador.Tests.ps1 Reto.Tests.ps1
PS> Add-Content Reto.Tests.ps1 -Value "Describe 'Get-NombreLibre' { It 'salta los nombres ocupados' { 'x' | Set-Content (Join-Path `$TestDrive 'informe.pdf'); 'x' | Set-Content (Join-Path `$TestDrive 'informe (2).pdf'); Get-NombreLibre -Carpeta `$TestDrive -Nombre 'informe.pdf' | Should -Be 'informe (3).pdf' } }"
PS> (Invoke-Pester -Path ./Reto.Tests.ps1 -PassThru -Output None).PassedCount
What if: Performing the operation "Mover a Documentos" on target "factura.pdf".
What if: Performing the operation "Mover a Imagenes" on target "foto.jpg".
9En la consola añadimos la prueba al final de una copia del archivo y pedimos solo el número de pruebas aprobadas: ahora son 9. Las líneas «What if» vuelven a ser de la prueba de -WhatIf.
Reto 2. Haz que el script acepte un parámetro -Excluir con extensiones que no se deben mover (por ejemplo, .tmp y .crdownload, que son descargas a medias). Pista: filtra en el script antes de llamar al módulo, o añade el parámetro a Move-ArchivoPorTipo.
Ver la solución
La forma más limpia es añadirlo al módulo, para poder probarlo: en Move-ArchivoPorTipo, un parámetro [string[]]$Excluir = @() y, al principio del foreach, if ($archivo.Extension -in $Excluir) { continue }. En el script, el mismo parámetro y la llamada Move-ArchivoPorTipo -Ruta $Ruta -Excluir $Excluir -WhatIf:$WhatIfPreference. Y una prueba nueva: crea video.crdownload en la carpeta de prueba y comprueba con Should -Exist que sigue donde estaba.
Reto 3. ¿Qué pasaría si quitas -Force de Import-Module en el script, editas el módulo y vuelves a ejecutar el script en la misma consola?
Ver la solución
Seguiría usando la versión vieja del módulo. Import-Module no vuelve a cargar un módulo que ya está cargado en la sesión, aunque el archivo haya cambiado. -Force lo obliga a recargarlo, lo cual es cómodo mientras desarrollas. En una consola nueva no pasa, porque cada sesión empieza sin módulos cargados.
Lo que aprendiste en el curso
Con este proyecto usaste casi todo lo del curso: variables y tipos, comparaciones y switch, el pipeline de objetos, funciones con parámetros validados y -WhatIf, módulos, archivos y CSV, errores controlados y pruebas. El siguiente paso es aplicarlo a tus propias tareas: en los ejemplos de PowerShell hay recetas para renombrar en lote, procesar registros, hacer copias de seguridad o llamar a una API. Y para comprobar lo que aprendiste, haz el test.
Todos los scripts de esta lección se ejecutaron con PowerShell 7.6.10 (la versión LTS) en un contenedor limpio sin acceso a la red, y se revisaron con PSScriptAnalyzer 1.25 antes de publicarla; las salidas están copiadas de esa ejecución. El contenedor es Linux, así que las rutas salen como /home/ana/proyecto; en tu Windows verás algo como C:\Users\ana. Mira tu versión con $PSVersionTable.PSVersion.
