Gets Items from the Windows Recycle Bin and Optionally Deletes Them

Get-RecycleBin.ps1

#Requires -Version 3.0
#Requires -PSEdition Desktop

function Get-RecycleBin {
	<#
 	.SYNOPSIS
        Lists and deletes items from the Windows Recycle Bin.
    .DESCRIPTION
		Lists and optionally deletes items in the Windows Recycle Bin for a specific user. 
		
		Files can be filtered based on deletion date allowing you to only target files that are older XX days.
	.PARAMETER DeleteItems
		Delete the specified items in Recycle Bin.
	.PARAMETER RetentionInDays
		Filter items that are only older than the day specified.
    .EXAMPLE
        Get-RecycleBin

		Lists all of the items currently in the Recycle Bin.
    .EXAMPLE
        Get-RecycleBin -RetentionInDays 30

		Lists only items in the Recycle Bin that were deleted more than 30 days ago.
    .EXAMPLE
        Get-RecycleBin -RetentionInDays 7 -DeleteItems

		Deletes items in the Recycle Bin that were deleted more than 7 days ago.
	#>
	[CmdletBinding(SupportsShouldProcess=$true,ConfirmImpact='High')]
	Param (
		[Parameter()]
		[Int32]
		$RetentionInDays,

		[Parameter()]
		[Switch]
		$DeleteItems
	)
	
	begin {
		$shell = New-Object -ComObject Shell.Application
		$recycler = $shell.NameSpace(0xa)

		function Get-UserNameFromSID {
			param (
				[Parameter(Mandatory=$true)]
				[String]
				$SID
			)

			$sidObj = (New-Object -TypeName System.Security.Principal.SecurityIdentifier($SID))
			$userObj = $sidObj.Translate([System.Security.Principal.NTAccount])
			
			$userObj.Value.Split('\')[1].ToLower()
		}
	}
	
	process {
		foreach($item in $recycler.Items()) {
			# CREATE AN OBJECT FOR EACH ITEM FOUND IN THE RECYCLE BIN
			$obj = [PSCustomObject]@{
				'DeletionDate'  = [DateTime]($Recycler.GetDetailsOf($item,2) -replace "\u200f|\u200e","") # REMOVE INVISIBLE UNICODE CHARACTERS THAT AFFECT [STRING] TO [DATETIME] CONVERSION
				'Size'          = "{0:N3}" -f $($item.Size/1MB)+" MB"
				'Name'          = $item.Name
				'Type'          = $item.Type
				'Path'          = $item.Path
			}
			
			# FILTER OUT ITEMS THAT WERE DELETED AFTER THE RETENTION PERIOD (YOUNGER FILES)
			if ($PSBoundParameters.ContainsKey('RetentionInDays')) {
				$obj = $obj | Where-Object -Property 'DeletionDate' -lt -Value (Get-Date).AddDays(-$RetentionInDays)
			}

			# CHECK IF THERE ARE ANY MATCHES
			if ($null -ne $obj) {
				$obj = $obj | Sort-Object -Property 'DeletionDate'

				# DELETE THE FILES IF THE -DELETEITEMS SWITCH WAS USED
				if ($PSBoundParameters.ContainsKey('DeleteItems')) {

					# PROMPT TO MAKE SURE THE FILES SHOULD BE DELETED
					# CAN BE OVERRIDEN WITH -CONFIRM:$FALSE FOR UNATTENDED PURPOSES
					if ($PSCmdlet.ShouldProcess('Recycle Bin',"Permanently remove item: '$($obj.Name)'")) {
						$verbose = @(
							$obj.Path.Split('\')[0],
							$obj.Path.Split('\')[1],
							(Get-UserNameFromSID -SID ($obj.Path.Split('\')[2])),
							$obj.Name
						) -join '\'
						Write-Verbose -Message "Deleting item: $verbose"
						
						Remove-Item -Path $obj.Path -Confirm:$false -Force -Recurse
					}
	
				} else {
					$obj
				}
			}
		}
	}

	end {

	}
}

Overview

Lists items in the Windows Recycle Bin. Allows for date filtering and deletion of items. Can be called from a Scheduled Task to make sure your Recycle Bin is always kept trim, but without having to empty the entire Recycle Bin.

Resources & Documentation

• Empty Recycle Bin with Retention Time (Logoff Script)
• Delete files in Recycle Bin automatically after certain days