5e9d160d48
Comprehensive documentation for Claude Code including: - Repository overview and structure - Detailed script architecture (Exchange-Inventory, Fix-VSSBackup, etc.) - Common patterns and execution requirements - Testing approach and environment constraints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# 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
|