Tests/Demo-O365MailboxUsage.ps1
|
<#
.SYNOPSIS Demonstration script for Get-O365MailboxUsage with automatic connection management .DESCRIPTION This script demonstrates how to use the new O365 mailbox usage functions with automatic connection management. It shows various usage scenarios and provides examples of the output. .EXAMPLE .\Demo-O365MailboxUsage.ps1 Runs the complete demonstration .NOTES This script requires appropriate Office 365 permissions to access mailbox information. #> param( [Parameter(HelpMessage = "Skip the connection test and go straight to examples")] [switch]$SkipConnectionTest, [Parameter(HelpMessage = "User email to use for single user examples")] [string]$TestUserEmail, [Parameter(HelpMessage = "Run examples that process all mailboxes (may take time)")] [switch]$IncludeAllMailboxExamples ) # Import the module functions $moduleRoot = Split-Path $PSScriptRoot -Parent $functions = @( "Get-O365MailboxUsage.ps1", "Connect-O365Exchange.ps1" ) Write-Host "=== O365 Mailbox Usage Demonstration ===" -ForegroundColor Green Write-Host "Loading functions..." -ForegroundColor Cyan foreach ($function in $functions) { $functionPath = Join-Path $moduleRoot "Public\$function" if (Test-Path $functionPath) { . $functionPath Write-Host " ✓ Loaded: $function" -ForegroundColor Green } else { Write-Error "Could not find: $functionPath" exit 1 } } Write-Host "`n=== Connection Management ===" -ForegroundColor Yellow if (-not $SkipConnectionTest) { Write-Host "`n1. Testing current connection status:" -ForegroundColor Cyan if (Test-O365ExchangeConnection -Detailed) { Write-Host "Connection is active and ready!" -ForegroundColor Green } else { Write-Host "No active connection found. Attempting to connect..." -ForegroundColor Yellow if (Connect-O365Exchange -ShowProgress) { Write-Host "Successfully connected!" -ForegroundColor Green } else { Write-Error "Failed to connect. Please check your credentials and permissions." exit 1 } } } else { Write-Host "Skipping connection test as requested..." -ForegroundColor Yellow if (-not (Test-O365ExchangeConnection -Quiet)) { Write-Error "No Exchange Online connection found. Please run Connect-O365Exchange first." exit 1 } } Write-Host "`n=== Basic Usage Examples ===" -ForegroundColor Yellow if ($TestUserEmail) { Write-Host "`n2. Single User Example:" -ForegroundColor Cyan Write-Host "Getting mailbox usage for: $TestUserEmail" -ForegroundColor White try { $singleUserResult = Get-O365MailboxUsage -UserPrincipalName $TestUserEmail -Verbose if ($singleUserResult) { Write-Host "`nResults:" -ForegroundColor Green $singleUserResult | Format-Table DisplayName, UserPrincipalName, @{ Name="Used (GB)"; Expression={$_.UsedSpaceGB} }, @{ Name="Total (GB)"; Expression={$_.TotalQuotaGB} }, @{ Name="% Full"; Expression={"{0:F1}%" -f $_.PercentFull} }, ItemCount -AutoSize Write-Host "`n3. Pipeline Input Example:" -ForegroundColor Cyan Write-Host "Processing the same user via pipeline..." -ForegroundColor White $pipelineResult = $TestUserEmail | Get-O365MailboxUsage Write-Host "Pipeline processing successful: $($pipelineResult.DisplayName)" -ForegroundColor Green } } catch { Write-Warning "Could not process user $TestUserEmail : $($_.Exception.Message)" } } else { Write-Host "`n2. Single User Example: Skipped (no test user provided)" -ForegroundColor Yellow Write-Host " Use -TestUserEmail parameter to test with a specific user" -ForegroundColor Gray } Write-Host "`n4. Multiple Users via Pipeline Example:" -ForegroundColor Cyan Write-Host "Getting a few random mailboxes to demonstrate pipeline processing..." -ForegroundColor White try { # Get a small sample of mailboxes for demonstration $sampleMailboxes = Get-Mailbox -ResultSize 3 -WarningAction SilentlyContinue if ($sampleMailboxes.Count -gt 0) { Write-Host "Found $($sampleMailboxes.Count) sample mailboxes for demonstration" -ForegroundColor Green $sampleEmails = $sampleMailboxes | Select-Object -First 2 | ForEach-Object { $_.PrimarySmtpAddress } Write-Host "Processing: $($sampleEmails -join ', ')" -ForegroundColor White $multipleResults = $sampleEmails | Get-O365MailboxUsage -SortBy PercentFull Write-Host "`nResults (sorted by % full):" -ForegroundColor Green $multipleResults | Format-Table DisplayName, @{ Name="Used (GB)"; Expression={$_.UsedSpaceGB} }, @{ Name="Total (GB)"; Expression={$_.TotalQuotaGB} }, @{ Name="% Full"; Expression={"{0:F1}%" -f $_.PercentFull} }, MailboxType -AutoSize } else { Write-Warning "No mailboxes found for sample demonstration" } } catch { Write-Warning "Could not retrieve sample mailboxes: $($_.Exception.Message)" } Write-Host "`n5. Sorting Demonstration:" -ForegroundColor Cyan Write-Host "Showing different sorting options with the same data..." -ForegroundColor White if ($sampleEmails -and $sampleEmails.Count -ge 2) { $sortOptions = @("PercentFull", "UsedSpaceGB", "TotalQuotaGB", "DisplayName") foreach ($sortBy in $sortOptions) { Write-Host "`n Sorted by $sortBy :" -ForegroundColor Yellow try { $sortedResults = $sampleEmails | Get-O365MailboxUsage -SortBy $sortBy $sortedResults | Format-Table DisplayName, @{ Name=$sortBy; Expression={ $_.$sortBy } } -AutoSize } catch { Write-Warning "Error sorting by $sortBy : $($_.Exception.Message)" } } } if ($IncludeAllMailboxExamples) { Write-Host "`n=== Advanced Examples ===" -ForegroundColor Yellow Write-Host "`n6. All Mailboxes Analysis:" -ForegroundColor Cyan Write-Host "WARNING: This may take several minutes for large organizations!" -ForegroundColor Red $confirm = Read-Host "Continue? (y/N)" if ($confirm -match '^[Yy]') { Write-Host "Retrieving all mailboxes..." -ForegroundColor Yellow try { $allResults = Get-O365MailboxUsage -Verbose Write-Host "`nSummary Statistics:" -ForegroundColor Green Write-Host " Total Mailboxes: $($allResults.Count)" -ForegroundColor White Write-Host " Average Usage: $([math]::Round(($allResults | Measure-Object PercentFull -Average).Average, 1))%" -ForegroundColor White $over80Percent = $allResults | Where-Object { $_.PercentFull -gt 80 } Write-Host " Mailboxes >80% full: $($over80Percent.Count)" -ForegroundColor $(if ($over80Percent.Count -gt 0) { "Red" } else { "Green" }) Write-Host "`nTop 10 Most Full Mailboxes:" -ForegroundColor Cyan $allResults | Select-Object -First 10 | Format-Table DisplayName, @{ Name="Used (GB)"; Expression={$_.UsedSpaceGB} }, @{ Name="Total (GB)"; Expression={$_.TotalQuotaGB} }, @{ Name="% Full"; Expression={"{0:F1}%" -f $_.PercentFull} }, MailboxType -AutoSize Write-Host "`n7. Filtering Examples:" -ForegroundColor Cyan Write-Host "`n Mailboxes over 90% full:" -ForegroundColor Yellow $criticalMailboxes = $allResults | Where-Object { $_.PercentFull -gt 90 } if ($criticalMailboxes.Count -gt 0) { $criticalMailboxes | Format-Table DisplayName, @{ Name="% Full"; Expression={"{0:F1}%" -f $_.PercentFull} } -AutoSize } else { Write-Host " No mailboxes over 90% full - Great!" -ForegroundColor Green } Write-Host "`n Largest mailboxes by used space:" -ForegroundColor Yellow $allResults | Sort-Object UsedSpaceGB -Descending | Select-Object -First 5 | Format-Table DisplayName, @{ Name="Used (GB)"; Expression={$_.UsedSpaceGB} }, MailboxType -AutoSize } catch { Write-Error "Failed to retrieve all mailboxes: $($_.Exception.Message)" } } } else { Write-Host "`n=== Advanced Examples (Skipped) ===" -ForegroundColor Yellow Write-Host "Use -IncludeAllMailboxExamples to run resource-intensive examples" -ForegroundColor Gray } Write-Host "`n=== Archive Functionality ===" -ForegroundColor Yellow if ($TestUserEmail) { Write-Host "`n8. Archive Statistics Example:" -ForegroundColor Cyan Write-Host "Checking if $TestUserEmail has archive enabled..." -ForegroundColor White try { $archiveResult = Get-O365MailboxUsage -UserPrincipalName $TestUserEmail -IncludeArchive if ($archiveResult.ArchiveUsedSpaceGB) { Write-Host "Archive statistics found:" -ForegroundColor Green Write-Host " Archive Used: $($archiveResult.ArchiveUsedSpaceGB) GB" -ForegroundColor White Write-Host " Archive Total: $($archiveResult.ArchiveTotalQuotaGB) GB" -ForegroundColor White Write-Host " Archive % Full: $($archiveResult.ArchivePercentFull)%" -ForegroundColor White } else { Write-Host "No archive found for this user" -ForegroundColor Yellow } } catch { Write-Warning "Could not check archive for $TestUserEmail : $($_.Exception.Message)" } } else { Write-Host "Archive example skipped (no test user provided)" -ForegroundColor Yellow } Write-Host "`n=== Summary ===" -ForegroundColor Green Write-Host "✓ Connection management functions work automatically" -ForegroundColor Green Write-Host "✓ Pipeline input processing works correctly" -ForegroundColor Green Write-Host "✓ Sorting and filtering options are functional" -ForegroundColor Green Write-Host "✓ Percentage calculations are accurate" -ForegroundColor Green Write-Host "✓ Error handling works properly" -ForegroundColor Green Write-Host "`nKey Functions Available:" -ForegroundColor Cyan Write-Host "• Connect-O365Exchange - Establish connection" -ForegroundColor White Write-Host "• Test-O365ExchangeConnection - Verify connection" -ForegroundColor White Write-Host "• Get-O365MailboxUsage - Retrieve usage statistics" -ForegroundColor White Write-Host "• Disconnect-O365Exchange - Clean disconnection" -ForegroundColor White Write-Host "`nExample Usage:" -ForegroundColor Cyan Write-Host 'Get-O365MailboxUsage | Where-Object { $_.PercentFull -gt 80 }' -ForegroundColor Gray Write-Host '"user@domain.com" | Get-O365MailboxUsage -IncludeArchive' -ForegroundColor Gray Write-Host 'Get-O365MailboxUsage -SortBy UsedSpaceGB | Export-Csv "mailbox-report.csv"' -ForegroundColor Gray Write-Host "`nDemonstration completed successfully!" -ForegroundColor Green Write-Host "Run 'Disconnect-O365Exchange' when finished to clean up the session." -ForegroundColor Yellow |