PowerShell-scripts/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a collection of standalone PowerShell scripts for Windows Server administration, focused on Active Directory, Exchange Server (on-premises), and system maintenance tasks. Each script is self-contained and can be executed independently.

Project Structure

The repository is organized into three main directories:

• ActiveDirectory/ - Scripts for Active Directory management (group membership operations)
• Exchange/ - Scripts for Exchange Server administration (mailbox reporting, inventory, traffic analysis)
• Misc/ - System maintenance scripts (VSS backup recovery)

Script Architecture

Exchange Scripts

Exchange-Inventory.ps1 - The most complex script in this repository. Key architecture:

• Report Generation Engine: Dual-mode output system (Word COM automation with HTML fallback)

  • Word automation via COM (Word.Application) for professional reports
  • HTML fallback with StringBuilder when Word is unavailable
  • Abstraction layer: Add-Heading(), Add-Paragraph(), Add-Table() functions work for both modes

• Progress Tracking System: Multi-level progress reporting

  • Section-based progress ($sections array with 22 named sections)
  • Throttled progress updates ($ProgressThrottleMs parameter controls update frequency)
  • Prevents UI flooding during intensive loops (mailbox statistics, database copies)

• Data Collection Pipeline: Sequential inventory collection

  1. Organization config & servers
  2. Client access & virtual directories (OWA, ECP, EWS, MAPI, etc.)
  3. POP/IMAP settings
  4. Certificates (with expiry status calculation)
  5. Domains, policies, transport rules
  6. Databases, DAG configuration, database copies
  7. Mailbox enumeration (on-prem only, filters out Remote* types)
  8. Mailbox statistics (collected per-database to avoid prompts)
  9. Retention, compliance, mobile device policies
  10. Addressing (address lists, GAL, OAB)
  11. Public folders, throttling, hybrid/federation config
  12. Queue monitoring

• Storage Calculation: Computes actual mailbox space requirements

  • Parses TotalItemSize from mailbox statistics (handles KB/MB/GB/TB units)
  • Aggregates per-database and total storage (excludes whitespace)
  • Uses ToBytes() method when available, regex fallback for string parsing

• CSV Export: Optional detailed exports controlled by $IncludeCSVs parameter

Get-LargeMailboxes.ps1 - Simple filtering script

• Queries mailboxes > 100GB
• Uses pipeline: Get-Mailbox | Get-MailboxStatistics | Where-Object
• Converts bytes to GB with formatting

Get-MailboxesPerType.ps1 - Quick mailbox type inventory

• Single-liner using Group-Object for counting

Get-SMTPTraffic.ps1 - Log parsing utility

• Reads Exchange FrontEnd SMTP receive logs
• CSV parsing with quoted field handling (regex: split(',(?=(?:[^"]*"[^"]*")*[^"]*$)'))
• Filters by IP range (192.168.1.*)

System Maintenance Scripts

Fix-VSSBackup.ps1 - VSS recovery automation

• Event log analysis (Application/System logs for VSS/VolSnap errors)
• VSS writer status parsing via vssadmin list writers
• Service restart orchestration with dependency handling
• Configurable service list (VSS, SwPrv, EventSystem, SQLWriter, IISADMIN, vmicvss, etc.)
• Smart defaults when run without parameters (auto-creates C:\Temp, enables Force mode)
• State verification after service restart

Active Directory Scripts

CopyADgroups.ps1 - Group membership cloning

• Simple member enumeration and addition
• Duplicate checking before adding
• Error handling per-member

Common Patterns

Error Handling

Scripts use -ErrorAction SilentlyContinue extensively to gracefully handle missing cmdlets or unavailable features across different Exchange versions (2013/2016/2019).

Execution Environment

• Exchange scripts: Require Exchange Management Shell with appropriate RBAC permissions
• VSS script: Requires Administrator privileges
• AD scripts: Require Active Directory PowerShell module

Parameter Design

• CmdletBinding with typed parameters
• Configurable defaults (e.g., $TopMailboxCount = 30, $LookbackMinutes = 60)
• Boolean parameters for feature toggles ($IncludeCSVs, $RequireFailedWriter)

Localization

Some scripts contain Dutch language strings (comments, log messages) - Exchange-Inventory.ps1 and Fix-VSSBackup.ps1 use Dutch for output.

Testing Approach

These are operational scripts without formal test frameworks. When modifying:

1. Exchange scripts: Test in non-production Exchange Management Shell first
2. VSS script: Test service restart logic on non-critical systems
3. AD scripts: Use test groups before production deployment

Important Constraints

• Scripts are environment-specific (hardcoded paths like C:\Program Files\Microsoft\Exchange Server\V15\...)
• Exchange-Inventory.ps1 assumes specific Exchange cmdlet availability
• Get-SMTPTraffic.ps1 filters for specific IP range (192.168.1.*) - modify for different networks