OrionUtils.psm1
|
<# ================================================================================ ORION UTILS - POWERSHELL UTILITY FUNCTIONS ================================================================================ Author: Sune Alexandersen Narud Date: February 9, 2026 Version: 1.6.0 HIGH LEVEL DESIGN (HLD): ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PURPOSE: OrionUtils is a collection of PowerShell utility functions for file management, time/date operations, logging, and common administrative tasks. It provides reliable, tested functions for everyday automation needs. ARCHITECTURE: ┌─────────────────────────────────────────────────────────────────────────────┐ │ FILE MANAGEMENT │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Remove-StaleFile Keep N newest files, delete the rest │ │ Test-FileLock Check if a file is locked by another process │ ├─────────────────────────────────────────────────────────────────────────────┤ │ TIME & DATE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Format-TimeSpan Format TimeSpan to human-readable string │ │ Get-TimeElapsed Calculate time since a given date │ ├─────────────────────────────────────────────────────────────────────────────┤ │ STOPWATCH / PERFORMANCE TIMING │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Start-Stopwatch Start a named stopwatch for timing │ │ Stop-Stopwatch Stop stopwatch and record elapsed time │ │ Get-Stopwatch Get running or completed stopwatch data │ │ Reset-Stopwatch Clear stopwatch data │ │ Show-StopwatchSummary Display formatted performance summary │ ├─────────────────────────────────────────────────────────────────────────────┤ │ USER INTERACTION │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Wait-ForInput Wait for key press, or timed wait with -Timer │ ├─────────────────────────────────────────────────────────────────────────────┤ │ LOGGING & METRICS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Write-Log Structured logging to file │ │ Export-MetricsToCSV Export PSObject metrics to CSV with timestamps │ ├─────────────────────────────────────────────────────────────────────────────┤ │ SYSTEM UTILITIES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Get-WindowsVersion Convert OS version to friendly name │ ├─────────────────────────────────────────────────────────────────────────────┤ │ DEMO │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Show-OrionUtilsDemo Interactive demo of all module functions │ ├─────────────────────────────────────────────────────────────────────────────┤ │ PRIVATE FUNCTIONS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Remove-FileWithLockCheck Internal helper for safe file deletion │ └─────────────────────────────────────────────────────────────────────────────┘ CORE FEATURES: • 📁 File management utilities with lock detection • ⏱️ Time/date formatting and elapsed time calculations • 🔒 Safe file operations with error handling • 📝 Structured logging with multiple levels • 📊 Metrics export to CSV with dynamic headers • ⚡ WhatIf/Confirm support for safe testing • 🎨 Optional integration with OrionDesign for beautiful output • 📚 Complete Comment-Based Help documentation DEPENDENCIES: • PowerShell 5.1 or later • OrionDesign module (optional, for enhanced output formatting) USAGE PATTERNS: Import-Module OrionUtils # File Management Remove-StaleFile -Path "C:\Logs" -Filter "*.log" -Keep 10 Test-FileLock -FilePath "C:\Data\file.xlsx" -Silent # Time Operations Format-TimeSpan -TimeSpan $stopwatch.Elapsed Get-TimeElapsed -DateTime $lastLogin -OutputFormat Days # Stopwatch / Performance Timing Start-Stopwatch -Name "Data Import" # ... your code ... Stop-Stopwatch -Name "Data Import" -ShowElapsed Show-StopwatchSummary # User Interaction Wait-ForInput -Message "Press any key to continue..." Wait-ForInput -Timer 10 -ShowCountdown # Timed wait with countdown # Logging Write-Log -Message "Process completed" -Level INFO -LogFile "C:\Logs\app.log" Export-MetricsToCSV -Metrics $stats -Path "C:\Data\metrics.csv" # System Get-WindowsVersion -OSVersion "10.0.22000" ================================================================================ #> Write-Verbose "DEBUG: OrionUtils.psm1 loaded. PSScriptRoot = $PSScriptRoot" $root = $PSScriptRoot # --- Load Private functions (internal only) --- $privatePath = Join-Path $root 'Functions\Private' if (Test-Path $privatePath) { Get-ChildItem -Path $privatePath -Filter *.ps1 | ForEach-Object { Write-Verbose "Loading private function: $($_.BaseName)" . $_.FullName } } # --- Load Public functions (to be exported) --- $publicPath = Join-Path $root 'Functions\Public' $publicFunctions = @() if (Test-Path $publicPath) { Get-ChildItem -Path $publicPath -Filter *.ps1 | ForEach-Object { Write-Verbose "Loading public function: $($_.BaseName)" . $_.FullName $publicFunctions += $_.BaseName } } # --- Export public functions and aliases --- if ($publicFunctions.Count -gt 0) { Write-Verbose "Exporting functions: $($publicFunctions -join ', ')" Export-ModuleMember -Function $publicFunctions } else { Write-Warning "No public functions found to export from OrionUtils" } |