Public/Invoke-ComputerCleanup.ps1
|
<#
.SYNOPSIS Main orchestrator function to invoke one or multiple cleanup functions included in this module. .DESCRIPTION Delegates to specialized cleanup functions based on the switches provided. Captures before/after disk space, tracks elapsed time per section, and produces a summary report. Optionally sends the report via email. Each cleanup function returns a result object that is collected into a results array. The -Days parameter controls file age threshold but does NOT apply to -BrowserCache, -TeamsCache, -SoftwareDistribution, -FontCache, -RecycleBin or -CleanManager. Supports -WhatIf, -Confirm, and -Force. .PARAMETER Days Only remove files and folders older than this many days. Defaults to 30. Does NOT apply to BrowserCache, TeamsCache, SoftwareDistribution, FontCache, RecycleBin or CleanManager. .PARAMETER CleanManager Runs installed Windows Disk Cleanup with Temporary Files and Thumbnail Cache selected. .PARAMETER SystemTemp Removes common system-wide temporary files and folders older than Days. .PARAMETER SoftwareDistribution Cleans the SoftwareDistribution\Download folder. .PARAMETER FontCache Clears user font cache files and restarts the Font Cache service. .PARAMETER BrowserCache Clears browser cache files for all users. Stops running browser processes. .PARAMETER TeamsCache Clears Microsoft Teams cache files for all users. Stops running Teams processes. .PARAMETER Force Suppresses implicit confirmation; explicit -Confirm and -WhatIf take precedence. .PARAMETER UserTemp Removes common temporary files from user profiles older than Days. .PARAMETER UserDownloads Removes selected archives larger than 500MB from Downloads, independently of UserTemp. .PARAMETER ArchiveTypes File extensions to consider as archive files when using -UserDownloads. Defaults to zip, rar, 7z, iso. .PARAMETER RecycleBin Clears the Windows Recycle Bin. .PARAMETER MailReport Send a separately confirmed HTML report and private transcript through the legacy SMTP path. Requires all SMTP/address parameters. .PARAMETER SmtpServer SMTP server address for email reports. .PARAMETER SmtpPort SMTP server port for email reports. .PARAMETER FromAddress Sender email address for the report. .PARAMETER ToAddress Recipient email address for the report. .EXAMPLE Invoke-ComputerCleanup -Days 30 -UserTemp -SystemTemp -CleanManager -SoftwareDistribution -RecycleBin Runs Disk Cleanup, cleans user and system temp files older than 30 days, cleans SoftwareDistribution, and empties the Recycle Bin. .EXAMPLE Invoke-ComputerCleanup -Days 30 -BrowserCache -TeamsCache -Force Clears browser and Teams cache for all users without confirmation prompts. .EXAMPLE Invoke-ComputerCleanup -Days 30 -UserTemp -SystemTemp -WhatIf Shows what would be cleaned without actually removing any files. .OUTPUTS [PSCustomObject[]] Array of per-section cleanup results, plus console summary output. .LINK https://systom.dev .NOTES Author: Tom de Leeuw Website: https://systom.dev #> function Invoke-ComputerCleanup { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] [OutputType([PSCustomObject[]])] param( [Parameter()] [ValidateRange(1, [int]::MaxValue)] [int] $Days = 30, [Parameter()] [switch] $CleanManager, [Parameter()] [switch] $SystemTemp, [Parameter()] [switch] $SoftwareDistribution, [Parameter()] [switch] $FontCache, [Parameter()] [switch] $BrowserCache, [Parameter()] [switch] $TeamsCache, [Parameter()] [switch] $Force, [Parameter()] [switch] $UserTemp, [Parameter()] [switch] $UserDownloads, [Parameter()] [ValidatePattern('^[A-Za-z0-9]+$')] [string[]] $ArchiveTypes = @('zip', 'rar', '7z', 'iso'), [Parameter()] [switch] $RecycleBin, [Parameter()] [switch] $MailReport, [Parameter()] [string] $SmtpServer, [Parameter()] [int] $SmtpPort, [Parameter()] [string] $FromAddress, [Parameter()] [string] $ToAddress ) if ($Force -and -not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = 'None' } Assert-RunAsAdministrator $Selected = @('CleanManager','UserTemp','UserDownloads','SystemTemp','SoftwareDistribution','FontCache','TeamsCache','BrowserCache','RecycleBin' | Where-Object { $PSBoundParameters.ContainsKey($_) -and $PSBoundParameters[$_] }) if (-not $Selected.Count) { throw 'Select at least one cleanup operation.' } if ($MailReport -and (-not $SmtpServer -or $SmtpPort -lt 1 -or $SmtpPort -gt 65535 -or -not $FromAddress -or -not $ToAddress)) { throw 'MailReport requires SmtpServer, SmtpPort (1-65535), FromAddress and ToAddress.' } # One approval covers the selected batch, including logging. All actual child # actions still have their own ShouldProcess guards for direct invocation. $Action = 'Permanently clean selected data, affect selected processes/services, and create a local transcript' if (-not $PSCmdlet.ShouldProcess(($Selected -join ', '), $Action)) { return } $LogFile = $null $Results = [Collections.Generic.List[PSCustomObject]]::new() $Before = Get-DiskSpace $StopWatch = [Diagnostics.Stopwatch]::StartNew() try { $LogFile = Start-Logging -LogName 'ComputerCleanup' -Confirm:$false $Child = @{ Confirm = $false; ErrorAction = 'Stop' } if ($CleanManager) { $Results.Add((Invoke-CleanManager @Child)) } if ($UserTemp -or $UserDownloads) { $Results.Add((Optimize-UserProfiles -Days $Days -TempFiles:$UserTemp -Downloads:$UserDownloads -ArchiveFiles:$UserDownloads -ArchiveTypes $ArchiveTypes @Child)) } if ($SystemTemp -or $RecycleBin) { $Results.Add((Optimize-SystemFiles -Days $Days -TempFiles:$SystemTemp -RecycleBin:$RecycleBin @Child)) } if ($SoftwareDistribution) { $Results.Add((Clear-SoftwareDistribution @Child)) } if ($FontCache) { $Results.Add((Clear-FontCache @Child)) } if ($TeamsCache) { $Results.Add((Clear-TeamsCache @Child)) } if ($BrowserCache) { $Results.Add((Clear-BrowserCache @Child)) } } finally { $StopWatch.Stop() if ($LogFile) { Stop-Transcript -ErrorAction Stop | Out-Null } } if ($MailReport -and $PSCmdlet.ShouldProcess($ToAddress, 'Send cleanup report and transcript over configured SMTP')) { $After = Get-DiskSpace $Summary = [PSCustomObject]@{ TotalSeconds = '{0:F2} sec' -f $StopWatch.Elapsed.TotalSeconds TotalMinutes = '{0:F2} min' -f $StopWatch.Elapsed.TotalMinutes SpaceBefore = "$($Before.FreeSpaceGB) GB" SpaceAfter = "$($After.FreeSpaceGB) GB" TotalCleaned = '{0:F2} GB' -f ($After.FreeSpaceGB - $Before.FreeSpaceGB) } $MailBody = New-HtmlCleanupReport -CleanupResults $Results.ToArray() -Summary $Summary # Compatibility only: prefer consuming returned objects with your approved mail client. Send-MailMessage -SmtpServer $SmtpServer -Port $SmtpPort -From $FromAddress -To $ToAddress -Subject 'ComputerCleanup report' -Body $MailBody -BodyAsHtml -Attachments $LogFile -ErrorAction Stop } $Results.ToArray() } |