How to Write a Text File in PowerShell

How to Write a Text File in PowerShell

Managing text files efficiently stands as one of the most fundamental tasks in system administration, automation, and scripting workflows. Whether you're logging system events, generating configuration files, or creating reports, the ability to write data to text files in PowerShell transforms how you handle information across Windows environments. This capability bridges the gap between ephemeral command outputs and persistent data storage, making your automation efforts both practical and valuable.

Writing text files in PowerShell encompasses a range of techniques and cmdlets designed to handle different scenarios—from simple one-line outputs to complex data structures requiring precise formatting. The platform offers multiple approaches, each with distinct advantages depending on your specific requirements, performance needs, and the complexity of the data you're managing. Understanding these methods empowers you to choose the right tool for each situation.

Throughout this comprehensive exploration, you'll discover the essential cmdlets for text file creation, learn performance optimization strategies, understand encoding considerations, and master error handling techniques. You'll gain practical knowledge through detailed examples, comparative analyses, and real-world scenarios that demonstrate how these concepts apply to actual administrative and development tasks.

Essential Cmdlets for Writing Text Files

PowerShell provides several native cmdlets specifically designed for writing content to text files. Each cmdlet serves particular use cases and offers unique features that make it suitable for different scenarios. Understanding these fundamental tools forms the foundation of effective file manipulation in PowerShell.

Out-File: The Versatile Writing Cmdlet

The Out-File cmdlet represents the most straightforward approach to writing text files in PowerShell. This cmdlet takes pipeline input and directs it to a file, handling the conversion from objects to text automatically. The cmdlet provides extensive control over encoding, width, and whether to append or overwrite existing content.

Get-Process | Out-File -FilePath "C:\Reports\processes.txt"
"Configuration updated successfully" | Out-File -FilePath "C:\Logs\status.log" -Append
Get-EventLog -LogName System -Newest 100 | Out-File -FilePath "C:\Logs\events.txt" -Width 200

The Out-File cmdlet automatically formats objects using PowerShell's default formatting system, which means complex objects are converted to their string representations before being written. This behavior proves particularly useful when you want to capture exactly what you see in the console, but it can create unnecessarily verbose output for structured data.

"The choice between appending and overwriting determines whether your script builds upon existing data or starts fresh with each execution—a decision that fundamentally affects how your logging and reporting systems behave."

Set-Content: Direct Content Management

Unlike Out-File, the Set-Content cmdlet treats files as content containers rather than output destinations. This distinction makes Set-Content more efficient for writing string data directly without the overhead of PowerShell's formatting system. The cmdlet replaces the entire file content by default, making it ideal for configuration file updates and situations where you need complete control over the file's contents.

Set-Content -Path "C:\Config\settings.txt" -Value "ServerName=PROD-SQL01"
$configLines = @(
    "[Database]"
    "ConnectionString=Server=localhost;Database=MainDB"
    "Timeout=30"
)
Set-Content -Path "C:\Config\database.ini" -Value $configLines

Set-Content excels when working with arrays of strings, as it automatically inserts line breaks between array elements. This behavior simplifies the creation of multi-line configuration files and structured text documents without requiring manual newline character management.

Add-Content: Cumulative Writing Operations

The Add-Content cmdlet specializes in appending data to existing files without reading or overwriting their current contents. This efficiency makes it the preferred choice for logging operations, where performance matters and you're continuously adding entries to growing log files.

Add-Content -Path "C:\Logs\application.log" -Value "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') - Application started"
Get-Service | Where-Object {$_.Status -eq "Running"} | ForEach-Object {
    Add-Content -Path "C:\Reports\active-services.txt" -Value "$($_.Name) - $($_.DisplayName)"
}

Add-Content maintains file handles more efficiently than repeatedly opening and closing files with Set-Content, resulting in better performance when making multiple append operations. This efficiency becomes particularly noticeable when processing large datasets or writing to files in tight loops.

Advanced Writing Techniques and Operators

Redirection Operators: Streamlined Syntax

PowerShell's redirection operators provide concise syntax for writing output to files, offering a more familiar approach for users transitioning from traditional command-line environments. The > operator overwrites files, while >> appends to them, creating elegant one-liners for simple file operations.

Get-ChildItem C:\Windows\System32\*.dll > "C:\Reports\system-dlls.txt"
"Process completed at $(Get-Date)" >> "C:\Logs\execution.log"
Get-WmiObject Win32_LogicalDisk | Select-Object DeviceID, FreeSpace, Size > "C:\Reports\disk-space.txt"

These operators function as shortcuts to Out-File, inheriting its formatting behavior and characteristics. While they provide convenience, they offer less explicit control over encoding and other parameters compared to using the full cmdlet syntax.

StreamWriter for Performance-Critical Operations

When performance becomes paramount—particularly when writing thousands of lines or working with large files—the .NET StreamWriter class offers superior speed compared to PowerShell cmdlets. This approach requires more code but delivers significantly better throughput for intensive file operations.

$streamWriter = [System.IO.StreamWriter]::new("C:\Data\large-output.txt")
try {
    for ($i = 1; $i -le 100000; $i++) {
        $streamWriter.WriteLine("Record $i - $(Get-Date)")
    }
}
finally {
    $streamWriter.Close()
}

# Alternative using automatic disposal
$streamWriter = [System.IO.StreamWriter]::new("C:\Data\output.txt")
try {
    Get-Content "C:\Data\input.txt" | ForEach-Object {
        $streamWriter.WriteLine($_.ToUpper())
    }
}
finally {
    $streamWriter.Dispose()
}

StreamWriter bypasses PowerShell's object formatting pipeline entirely, writing strings directly to the file system. This direct approach eliminates overhead but requires manual resource management through proper disposal patterns to prevent file locking issues.

"Performance optimization isn't about using the fastest method everywhere—it's about recognizing when the overhead of convenience features outweighs their benefits for your specific scenario."

StringBuilder for Complex String Construction

Before writing content to files, you often need to construct complex strings from multiple sources. The StringBuilder class provides efficient string concatenation, particularly valuable when building large text blocks before writing them to disk in a single operation.

$stringBuilder = [System.Text.StringBuilder]::new()
[void]$stringBuilder.AppendLine("System Report Generated: $(Get-Date)")
[void]$stringBuilder.AppendLine("="*50)

Get-Process | Select-Object -First 10 | ForEach-Object {
    [void]$stringBuilder.AppendLine("$($_.Name) - PID: $($_.Id) - Memory: $($_.WorkingSet64 / 1MB) MB")
}

$stringBuilder.ToString() | Set-Content -Path "C:\Reports\system-report.txt"

StringBuilder avoids the performance penalties associated with string concatenation in loops, where each concatenation creates a new string object in memory. For reports or logs constructed from many pieces of information, this approach dramatically reduces memory pressure and execution time.

Encoding and Character Set Management

Text encoding determines how characters are represented as bytes in files, affecting compatibility across systems, languages, and applications. PowerShell's default encoding behavior has evolved across versions, making explicit encoding specification a best practice for portable scripts.

Understanding PowerShell Encoding Defaults

PowerShell 5.1 and earlier versions use UTF-16 LE (Little Endian) as the default encoding for Out-File, which creates files with byte order marks (BOM) that some applications struggle to process. PowerShell Core (6.0+) changed this default to UTF-8 without BOM, aligning better with cross-platform expectations and modern text file standards.

# Explicitly specifying encoding for cross-platform compatibility
"Configuration data" | Out-File -FilePath "C:\Config\settings.txt" -Encoding UTF8
Set-Content -Path "C:\Data\output.json" -Value $jsonContent -Encoding UTF8NoBOM

# Working with ASCII for legacy systems
Get-Service | Out-File -FilePath "C:\Reports\services.txt" -Encoding ASCII

# Using UTF-16 for Windows-native applications
$report | Out-File -FilePath "C:\Reports\windows-report.txt" -Encoding Unicode

Special Character Handling

Different encodings handle special characters, accented letters, and symbols differently. UTF-8 provides the broadest character support while maintaining reasonable file sizes, making it the recommended choice for most scenarios involving international text or special symbols.

# Handling special characters correctly
$textWithSpecialChars = @"
Company: Müller & Søn
Location: São Paulo, Brasil
Currency: €, £, ¥
Symbols: ™, ©, ®
"@

# UTF-8 preserves all special characters
$textWithSpecialChars | Out-File -FilePath "C:\Data\international.txt" -Encoding UTF8

# ASCII would corrupt these characters
# $textWithSpecialChars | Out-File -FilePath "C:\Data\corrupted.txt" -Encoding ASCII

"Encoding issues often remain hidden during development, only to surface when files are shared across systems or processed by different applications—making explicit encoding specification a form of preventive maintenance."

Robust Error Handling and File Access Management

File operations frequently encounter issues—locked files, insufficient permissions, missing directories, or full disks. Implementing comprehensive error handling ensures your scripts gracefully manage these situations rather than failing unexpectedly.

Try-Catch-Finally Patterns

PowerShell's structured exception handling provides the foundation for robust file operations. The try-catch-finally pattern allows you to attempt file operations, handle specific errors, and ensure proper cleanup regardless of success or failure.

function Write-LogEntry {
    param(
        [string]$LogPath,
        [string]$Message
    )
    
    try {
        $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        $logEntry = "$timestamp - $Message"
        
        # Attempt to write to log file
        Add-Content -Path $LogPath -Value $logEntry -ErrorAction Stop
        
        Write-Verbose "Successfully wrote to log: $LogPath"
    }
    catch [System.IO.DirectoryNotFoundException] {
        # Create directory if it doesn't exist
        $directory = Split-Path -Path $LogPath -Parent
        New-Item -Path $directory -ItemType Directory -Force | Out-Null
        Add-Content -Path $LogPath -Value $logEntry
        Write-Warning "Created missing directory: $directory"
    }
    catch [System.UnauthorizedAccessException] {
        Write-Error "Access denied to log file: $LogPath"
        # Attempt alternative logging location
        $altPath = Join-Path -Path $env:TEMP -ChildPath "fallback.log"
        Add-Content -Path $altPath -Value $logEntry
        Write-Warning "Wrote to alternative location: $altPath"
    }
    catch {
        Write-Error "Failed to write log entry: $_"
        # Log to event viewer as last resort
        Write-EventLog -LogName Application -Source "MyScript" -EventId 1000 -Message $Message -ErrorAction SilentlyContinue
    }
}

File Locking and Concurrent Access

File locking issues arise when multiple processes attempt to access the same file simultaneously. Implementing retry logic with exponential backoff provides resilience against transient locking issues while avoiding infinite loops.

function Write-FileWithRetry {
    param(
        [string]$Path,
        [string]$Content,
        [int]$MaxRetries = 3,
        [int]$InitialDelayMs = 100
    )
    
    $attempt = 0
    $delay = $InitialDelayMs
    
    while ($attempt -lt $MaxRetries) {
        try {
            Set-Content -Path $Path -Value $Content -ErrorAction Stop
            Write-Verbose "Successfully wrote file on attempt $($attempt + 1)"
            return $true
        }
        catch [System.IO.IOException] {
            $attempt++
            if ($attempt -ge $MaxRetries) {
                Write-Error "Failed to write file after $MaxRetries attempts: $_"
                return $false
            }
            
            Write-Warning "File locked, waiting $delay ms before retry $attempt"
            Start-Sleep -Milliseconds $delay
            $delay *= 2  # Exponential backoff
        }
    }
}

Validating File Paths and Permissions

Proactive validation prevents errors before they occur. Testing paths, verifying permissions, and ensuring adequate disk space before attempting write operations creates more reliable scripts.

function Test-FileWriteAccess {
    param([string]$Path)
    
    # Validate path format
    if (-not [System.IO.Path]::IsPathRooted($Path)) {
        throw "Path must be absolute: $Path"
    }
    
    # Ensure directory exists
    $directory = Split-Path -Path $Path -Parent
    if (-not (Test-Path -Path $directory)) {
        New-Item -Path $directory -ItemType Directory -Force | Out-Null
    }
    
    # Test write permissions
    try {
        $testFile = Join-Path -Path $directory -ChildPath "write-test-$([Guid]::NewGuid()).tmp"
        [System.IO.File]::WriteAllText($testFile, "test")
        Remove-Item -Path $testFile -Force
        return $true
    }
    catch {
        Write-Error "Cannot write to directory: $directory"
        return $false
    }
}

# Check available disk space
function Test-DiskSpace {
    param(
        [string]$Path,
        [long]$RequiredBytes = 10MB
    )
    
    $drive = [System.IO.Path]::GetPathRoot($Path)
    $driveInfo = Get-PSDrive -Name $drive.TrimEnd(':\') -PSProvider FileSystem
    
    if ($driveInfo.Free -lt $RequiredBytes) {
        throw "Insufficient disk space. Required: $($RequiredBytes/1MB)MB, Available: $($driveInfo.Free/1MB)MB"
    }
}

"The difference between a script that works on your development machine and one that works reliably in production often comes down to how thoroughly it anticipates and handles exceptional conditions."

Performance Optimization Strategies

File writing performance varies dramatically based on the methods used, data volumes, and system conditions. Understanding these performance characteristics helps you choose appropriate techniques for different scenarios.

Comparative Performance Analysis

Batching Write Operations

Rather than writing individual lines repeatedly, accumulating content and writing in batches significantly improves performance by reducing file system operations and overhead.

# Inefficient: Multiple write operations
$services = Get-Service
foreach ($service in $services) {
    Add-Content -Path "C:\Reports\services.txt" -Value "$($service.Name) - $($service.Status)"
}

# Efficient: Batch write operation
$services = Get-Service
$output = $services | ForEach-Object {
    "$($_.Name) - $($_.Status)"
}
Set-Content -Path "C:\Reports\services.txt" -Value $output

# Most efficient: Pipeline to single write
Get-Service | ForEach-Object {
    "$($_.Name) - $($_.Status)"
} | Set-Content -Path "C:\Reports\services.txt"

Memory Management for Large Files

When working with extremely large datasets, streaming data through the pipeline rather than loading everything into memory prevents out-of-memory errors and maintains consistent performance.

# Memory-intensive approach (loads everything)
$allData = Get-Content "C:\Data\huge-input.txt"
$processed = $allData | ForEach-Object { $_.ToUpper() }
Set-Content -Path "C:\Data\output.txt" -Value $processed

# Memory-efficient streaming approach
$reader = [System.IO.StreamReader]::new("C:\Data\huge-input.txt")
$writer = [System.IO.StreamWriter]::new("C:\Data\output.txt")

try {
    while ($null -ne ($line = $reader.ReadLine())) {
        $writer.WriteLine($line.ToUpper())
    }
}
finally {
    $reader.Close()
    $writer.Close()
}

"Performance optimization requires measurement—what seems intuitively faster may not be in practice, making benchmarking essential before committing to complex optimization strategies."

Measuring and Benchmarking

The Measure-Command cmdlet provides precise timing for comparing different approaches, enabling data-driven decisions about which methods to use in production scenarios.

# Benchmark different writing methods
$testData = 1..10000 | ForEach-Object { "Line $_" }

# Test Out-File
$outFileTime = Measure-Command {
    $testData | Out-File -FilePath "C:\Temp\test-outfile.txt"
}

# Test Set-Content
$setContentTime = Measure-Command {
    Set-Content -Path "C:\Temp\test-setcontent.txt" -Value $testData
}

# Test StreamWriter
$streamWriterTime = Measure-Command {
    $sw = [System.IO.StreamWriter]::new("C:\Temp\test-streamwriter.txt")
    try {
        $testData | ForEach-Object { $sw.WriteLine($_) }
    }
    finally {
        $sw.Close()
    }
}

[PSCustomObject]@{
    OutFile = $outFileTime.TotalMilliseconds
    SetContent = $setContentTime.TotalMilliseconds
    StreamWriter = $streamWriterTime.TotalMilliseconds
} | Format-Table -AutoSize

Real-World Implementation Scenarios

📋 Structured Logging System

Creating a comprehensive logging system demonstrates how file writing integrates into larger automation frameworks, handling rotation, severity levels, and concurrent access.

class LogManager {
    [string]$LogDirectory
    [string]$LogFileName
    [long]$MaxLogSizeBytes
    [int]$MaxLogFiles
    
    LogManager([string]$directory, [string]$fileName) {
        $this.LogDirectory = $directory
        $this.LogFileName = $fileName
        $this.MaxLogSizeBytes = 10MB
        $this.MaxLogFiles = 5
        
        if (-not (Test-Path $this.LogDirectory)) {
            New-Item -Path $this.LogDirectory -ItemType Directory -Force | Out-Null
        }
    }
    
    [void]WriteLog([string]$message, [string]$level = "INFO") {
        $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        $logEntry = "[$timestamp] [$level] $message"
        $logPath = Join-Path $this.LogDirectory $this.LogFileName
        
        # Check if rotation needed
        if ((Test-Path $logPath) -and (Get-Item $logPath).Length -gt $this.MaxLogSizeBytes) {
            $this.RotateLogs()
        }
        
        # Write log entry with retry logic
        $retries = 3
        for ($i = 0; $i -lt $retries; $i++) {
            try {
                Add-Content -Path $logPath -Value $logEntry -ErrorAction Stop
                break
            }
            catch {
                if ($i -eq $retries - 1) { throw }
                Start-Sleep -Milliseconds 100
            }
        }
    }
    
    [void]RotateLogs() {
        $basePath = Join-Path $this.LogDirectory $this.LogFileName
        
        # Remove oldest log if max count reached
        $oldestLog = "$basePath.$($this.MaxLogFiles)"
        if (Test-Path $oldestLog) {
            Remove-Item $oldestLog -Force
        }
        
        # Rotate existing logs
        for ($i = $this.MaxLogFiles - 1; $i -gt 0; $i--) {
            $source = if ($i -eq 1) { $basePath } else { "$basePath.$($i-1)" }
            $destination = "$basePath.$i"
            
            if (Test-Path $source) {
                Move-Item -Path $source -Destination $destination -Force
            }
        }
    }
}

# Usage example
$logger = [LogManager]::new("C:\Logs\MyApplication", "app.log")
$logger.WriteLog("Application started", "INFO")
$logger.WriteLog("Configuration loaded successfully", "INFO")
$logger.WriteLog("Warning: High memory usage detected", "WARN")
$logger.WriteLog("Critical error occurred", "ERROR")

📊 CSV Report Generation

Generating structured reports combines data collection, formatting, and file writing into cohesive workflows that transform raw information into actionable documents.

function New-SystemReport {
    param(
        [string]$OutputPath = "C:\Reports\system-report.csv"
    )
    
    # Collect system information
    $reportData = [System.Collections.ArrayList]::new()
    
    # Disk information
    Get-CimInstance Win32_LogicalDisk -Filter "DriveType=3" | ForEach-Object {
        [void]$reportData.Add([PSCustomObject]@{
            Category = "Disk"
            Name = $_.DeviceID
            Value = "$([math]::Round($_.FreeSpace/1GB, 2)) GB Free"
            Status = if (($_.FreeSpace / $_.Size) -lt 0.1) { "Critical" } else { "OK" }
        })
    }
    
    # Memory information
    $os = Get-CimInstance Win32_OperatingSystem
    $freeMemoryGB = [math]::Round($os.FreePhysicalMemory/1MB, 2)
    $totalMemoryGB = [math]::Round($os.TotalVisibleMemorySize/1MB, 2)
    
    [void]$reportData.Add([PSCustomObject]@{
        Category = "Memory"
        Name = "Physical Memory"
        Value = "$freeMemoryGB GB Free of $totalMemoryGB GB"
        Status = if (($freeMemoryGB / $totalMemoryGB) -lt 0.1) { "Warning" } else { "OK" }
    })
    
    # Service information
    Get-Service | Where-Object { $_.StartType -eq "Automatic" -and $_.Status -ne "Running" } | ForEach-Object {
        [void]$reportData.Add([PSCustomObject]@{
            Category = "Service"
            Name = $_.DisplayName
            Value = $_.Status
            Status = "Warning"
        })
    }
    
    # Export to CSV
    $reportData | Export-Csv -Path $OutputPath -NoTypeInformation -Encoding UTF8
    
    # Also create formatted text version
    $textPath = $OutputPath -replace '\.csv$', '.txt'
    $reportData | Format-Table -AutoSize | Out-File -FilePath $textPath -Width 200
    
    Write-Host "Report generated: $OutputPath"
    return $reportData
}

⚙️ Configuration File Management

Managing configuration files requires careful handling of existing content, preserving structure while updating specific values, and maintaining readability for both humans and applications.

function Update-ConfigurationFile {
    param(
        [string]$ConfigPath,
        [hashtable]$Settings
    )
    
    # Read existing configuration
    $configContent = if (Test-Path $ConfigPath) {
        Get-Content $ConfigPath
    } else {
        @()
    }
    
    # Parse existing settings into hashtable
    $existingSettings = @{}
    foreach ($line in $configContent) {
        if ($line -match '^([^=]+)=(.+)$') {
            $existingSettings[$matches[1].Trim()] = $matches[2].Trim()
        }
    }
    
    # Merge new settings
    foreach ($key in $Settings.Keys) {
        $existingSettings[$key] = $Settings[$key]
    }
    
    # Build new configuration content
    $newContent = [System.Collections.ArrayList]::new()
    [void]$newContent.Add("# Configuration file updated: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')")
    [void]$newContent.Add("")
    
    foreach ($key in ($existingSettings.Keys | Sort-Object)) {
        [void]$newContent.Add("$key=$($existingSettings[$key])")
    }
    
    # Write configuration with backup
    if (Test-Path $ConfigPath) {
        $backupPath = "$ConfigPath.bak"
        Copy-Item -Path $ConfigPath -Destination $backupPath -Force
    }
    
    Set-Content -Path $ConfigPath -Value $newContent -Encoding UTF8
}

# Usage
Update-ConfigurationFile -ConfigPath "C:\Config\app.conf" -Settings @{
    ServerName = "PROD-WEB01"
    Port = "8080"
    EnableLogging = "true"
    MaxConnections = "100"
}

📝 Template-Based Document Generation

Template systems enable dynamic document creation by replacing placeholders with actual values, useful for generating emails, reports, or configuration files from standardized formats.

function Expand-Template {
    param(
        [string]$TemplatePath,
        [string]$OutputPath,
        [hashtable]$Variables
    )
    
    # Read template
    $template = Get-Content -Path $TemplatePath -Raw
    
    # Replace variables
    foreach ($key in $Variables.Keys) {
        $placeholder = "{{$key}}"
        $template = $template -replace [regex]::Escape($placeholder), $Variables[$key]
    }
    
    # Write output
    Set-Content -Path $OutputPath -Value $template -Encoding UTF8
}

# Create template file
$emailTemplate = @"
Dear {{CustomerName}},

Thank you for your order #{{OrderNumber}} placed on {{OrderDate}}.

Your order total is {{OrderTotal}} and will be shipped to:
{{ShippingAddress}}

Estimated delivery: {{DeliveryDate}}

Best regards,
{{CompanyName}}
"@

Set-Content -Path "C:\Templates\order-confirmation.txt" -Value $emailTemplate

# Generate personalized email
Expand-Template -TemplatePath "C:\Templates\order-confirmation.txt" `
    -OutputPath "C:\Output\customer-email.txt" `
    -Variables @{
        CustomerName = "John Smith"
        OrderNumber = "12345"
        OrderDate = (Get-Date).ToString("yyyy-MM-dd")
        OrderTotal = "$299.99"
        ShippingAddress = "123 Main St, City, State 12345"
        DeliveryDate = (Get-Date).AddDays(3).ToString("yyyy-MM-dd")
        CompanyName = "Acme Corporation"
    }

"Real-world implementations rarely use file writing in isolation—they integrate it into larger workflows where reliability, maintainability, and performance all contribute to overall system quality."

🔄 Automated Backup and Archive System

Combining file writing with compression and organization creates robust backup systems that document their operations and maintain historical records.

function Invoke-BackupWithLog {
    param(
        [string]$SourcePath,
        [string]$BackupRoot = "C:\Backups",
        [switch]$Compress
    )
    
    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
    $backupName = "Backup-$timestamp"
    $backupPath = Join-Path $BackupRoot $backupName
    $logPath = Join-Path $BackupRoot "$backupName.log"
    
    # Initialize log
    $logEntries = [System.Collections.ArrayList]::new()
    
    function Write-BackupLog {
        param([string]$Message)
        $entry = "$(Get-Date -Format 'HH:mm:ss') - $Message"
        [void]$logEntries.Add($entry)
        Write-Host $entry
    }
    
    try {
        Write-BackupLog "Starting backup of $SourcePath"
        
        # Create backup directory
        New-Item -Path $backupPath -ItemType Directory -Force | Out-Null
        Write-BackupLog "Created backup directory: $backupPath"
        
        # Copy files
        $fileCount = 0
        $totalSize = 0
        
        Get-ChildItem -Path $SourcePath -Recurse -File | ForEach-Object {
            $relativePath = $_.FullName.Substring($SourcePath.Length)
            $destinationPath = Join-Path $backupPath $relativePath
            $destinationDir = Split-Path $destinationPath -Parent
            
            if (-not (Test-Path $destinationDir)) {
                New-Item -Path $destinationDir -ItemType Directory -Force | Out-Null
            }
            
            Copy-Item -Path $_.FullName -Destination $destinationPath -Force
            $fileCount++
            $totalSize += $_.Length
            
            if ($fileCount % 100 -eq 0) {
                Write-BackupLog "Copied $fileCount files..."
            }
        }
        
        Write-BackupLog "Copied $fileCount files (Total: $([math]::Round($totalSize/1MB, 2)) MB)"
        
        # Compress if requested
        if ($Compress) {
            Write-BackupLog "Compressing backup..."
            $zipPath = "$backupPath.zip"
            Compress-Archive -Path $backupPath -DestinationPath $zipPath -CompressionLevel Optimal
            
            $zipSize = (Get-Item $zipPath).Length
            Write-BackupLog "Compressed to $([math]::Round($zipSize/1MB, 2)) MB"
            
            # Remove uncompressed backup
            Remove-Item -Path $backupPath -Recurse -Force
            Write-BackupLog "Removed uncompressed backup"
        }
        
        Write-BackupLog "Backup completed successfully"
    }
    catch {
        Write-BackupLog "ERROR: $($_.Exception.Message)"
        throw
    }
    finally {
        # Write log file
        Set-Content -Path $logPath -Value $logEntries -Encoding UTF8
    }
}

Best Practices and Guidelines

✅ Path Management

• Always use absolute paths in production scripts to avoid ambiguity about file locations
• Validate paths before operations using Test-Path and creating directories as needed
• Use Join-Path for constructing file paths rather than string concatenation to ensure cross-platform compatibility
• Avoid hardcoding paths by using parameters or configuration files for flexibility

✅ Encoding Consistency

• Explicitly specify encoding in all file operations to ensure predictable behavior across PowerShell versions
• Use UTF-8 without BOM as the default for maximum compatibility with modern applications
• Document encoding choices in script comments when using non-standard encodings
• Test encoding compatibility with downstream systems that will consume your files

✅ Error Handling

• Implement try-catch blocks around all file operations to handle exceptions gracefully
• Provide meaningful error messages that include context about what operation failed and why
• Use -ErrorAction Stop with cmdlets inside try blocks to ensure exceptions are catchable
• Clean up resources in finally blocks to prevent file locks and handle disposal properly

✅ Performance Considerations

• Choose appropriate methods based on data volume—StreamWriter for large files, cmdlets for moderate operations
• Batch write operations instead of writing individual lines repeatedly
• Measure performance using Measure-Command before optimizing to identify actual bottlenecks
• Consider memory constraints when processing large datasets, using streaming approaches when necessary

✅ Security and Permissions

• Validate write permissions before attempting file operations to provide clear error messages
• Avoid writing sensitive data to temporary directories or locations with broad access permissions
• Implement file locking strategies for concurrent access scenarios to prevent data corruption
• Use secure deletion methods when removing files containing sensitive information

"Best practices emerge from collective experience with failures—each guideline represents lessons learned about what can go wrong when file operations meet real-world complexity."

Common Issues and Troubleshooting

🔧 File Locking and Access Denied Errors

File locking occurs when another process holds an exclusive handle to a file, preventing your script from accessing it. This commonly happens with log files being actively written by applications, or files open in editors.

# Diagnostic: Check which process has a file locked
function Get-FileLockedBy {
    param([string]$FilePath)
    
    $file = Get-Item $FilePath -ErrorAction SilentlyContinue
    if (-not $file) { return $null }
    
    try {
        $fileStream = [System.IO.File]::Open($file.FullName, 'Open', 'Write')
        $fileStream.Close()
        return $null  # File is not locked
    }
    catch {
        # File is locked, try to find the process
        $processes = Get-Process | Where-Object {
            $_.Modules.FileName -contains $file.FullName
        }
        return $processes
    }
}

# Solution: Use file stream with shared read access
function Write-SharedFile {
    param(
        [string]$Path,
        [string]$Content
    )
    
    $fileStream = [System.IO.FileStream]::new(
        $Path,
        [System.IO.FileMode]::Append,
        [System.IO.FileAccess]::Write,
        [System.IO.FileShare]::Read
    )
    
    $streamWriter = [System.IO.StreamWriter]::new($fileStream)
    try {
        $streamWriter.WriteLine($Content)
    }
    finally {
        $streamWriter.Close()
        $fileStream.Close()
    }
}

🔧 Encoding and Character Corruption

Character corruption typically results from encoding mismatches—writing with one encoding and reading with another, or using encodings that don't support the characters in your content.

# Diagnostic: Detect file encoding
function Get-FileEncoding {
    param([string]$Path)
    
    $bytes = [byte[]](Get-Content $Path -Encoding Byte -ReadCount 4 -TotalCount 4)
    
    if ($bytes[0] -eq 0xef -and $bytes[1] -eq 0xbb -and $bytes[2] -eq 0xbf) {
        return "UTF-8 BOM"
    }
    elseif ($bytes[0] -eq 0xff -and $bytes[1] -eq 0xfe) {
        return "UTF-16 LE"
    }
    elseif ($bytes[0] -eq 0xfe -and $bytes[1] -eq 0xff) {
        return "UTF-16 BE"
    }
    else {
        return "ASCII or UTF-8 without BOM"
    }
}

# Solution: Convert file encoding
function Convert-FileEncoding {
    param(
        [string]$Path,
        [string]$TargetEncoding = "UTF8"
    )
    
    $content = Get-Content -Path $Path -Raw
    $encoding = [System.Text.Encoding]::GetEncoding($TargetEncoding)
    [System.IO.File]::WriteAllText($Path, $content, $encoding)
}

🔧 Path Length Limitations

Windows historically imposed a 260-character path length limit, though newer versions support longer paths with specific configuration. Scripts working with deep directory structures may encounter this limitation.

# Diagnostic: Check path length
function Test-PathLength {
    param([string]$Path)
    
    if ($Path.Length -gt 260) {
        Write-Warning "Path exceeds 260 characters ($($Path.Length) chars)"
        
        # Suggest using \\?\ prefix for long paths
        if (-not $Path.StartsWith("\\?\")) {
            $longPath = "\\?\$Path"
            Write-Host "Try using long path format: $longPath"
        }
        
        return $false
    }
    return $true
}

# Solution: Use .NET methods that support long paths
function Write-FileLongPath {
    param(
        [string]$Path,
        [string]$Content
    )
    
    # Prepend \\?\ for long path support
    if (-not $Path.StartsWith("\\?\") -and $Path.Length -gt 260) {
        $Path = "\\?\$Path"
    }
    
    [System.IO.File]::WriteAllText($Path, $Content)
}

🔧 Disk Space Exhaustion

Writing large amounts of data without checking available space can cause scripts to fail partway through operations, potentially corrupting data or leaving systems in inconsistent states.

# Preventive check with automatic cleanup
function Write-FileWithSpaceCheck {
    param(
        [string]$Path,
        [string]$Content,
        [long]$SafetyMarginMB = 100
    )
    
    $drive = [System.IO.Path]::GetPathRoot($Path)
    $driveInfo = Get-PSDrive -Name $drive.TrimEnd(':\') -PSProvider FileSystem
    
    $estimatedSizeMB = [System.Text.Encoding]::UTF8.GetByteCount($Content) / 1MB
    $requiredMB = $estimatedSizeMB + $SafetyMarginMB
    $availableMB = $driveInfo.Free / 1MB
    
    if ($availableMB -lt $requiredMB) {
        Write-Warning "Insufficient disk space. Required: $requiredMB MB, Available: $availableMB MB"
        
        # Attempt to free space by removing old log files
        $directory = Split-Path -Path $Path -Parent
        Get-ChildItem -Path $directory -Filter "*.log" | 
            Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
            Sort-Object LastWriteTime |
            Select-Object -First 10 |
            ForEach-Object {
                Write-Host "Removing old file: $($_.Name)"
                Remove-Item $_.FullName -Force
            }
        
        # Recheck space
        $driveInfo = Get-PSDrive -Name $drive.TrimEnd(':\') -PSProvider FileSystem
        $availableMB = $driveInfo.Free / 1MB
        
        if ($availableMB -lt $requiredMB) {
            throw "Cannot free sufficient disk space"
        }
    }
    
    Set-Content -Path $Path -Value $Content
}

What is the fastest way to write large files in PowerShell?

The StreamWriter class from .NET provides the fastest performance for writing large files. It bypasses PowerShell's formatting pipeline and writes directly to the file system. For files with tens of thousands of lines or more, StreamWriter can be 5-10 times faster than cmdlets like Out-File or Set-Content. However, it requires manual resource management using try-finally blocks to ensure proper disposal.

Should I use Out-File or Set-Content for writing text files?

Set-Content is generally preferred for writing string data because it's more efficient and treats files as content containers rather than output streams. Out-File is better when you want to capture formatted object output exactly as it appears in the console. Set-Content works directly with strings and arrays of strings, while Out-File processes objects through PowerShell's formatting system, which adds overhead but provides formatted output.

How do I append to a file without overwriting existing content?

Use the Add-Content cmdlet or the Out-File cmdlet with the -Append parameter. Add-Content is specifically designed for appending and is more efficient for this purpose. You can also use the append redirection operator (>>) as a shorthand. Add-Content maintains file handles efficiently when making multiple append operations, making it ideal for logging scenarios where you're continuously adding entries.

What encoding should I use for text files in PowerShell?

UTF-8 without BOM (Byte Order Mark) provides the best compatibility across platforms and applications. Use -Encoding UTF8NoBOM in PowerShell 6.0+ or -Encoding UTF8 in earlier versions. UTF-8 supports all Unicode characters while maintaining reasonable file sizes. Always explicitly specify encoding in your scripts to ensure consistent behavior across different PowerShell versions, as the default encoding changed between PowerShell 5.1 and PowerShell Core.

How can I handle file locking errors when writing to files?

Implement retry logic with exponential backoff to handle transient locking issues. Use try-catch blocks to detect IOException exceptions, wait a short period, and retry the operation. For more robust solutions, use .NET FileStream with FileShare.Read to allow other processes to read the file while you're writing. Consider implementing a maximum retry count to prevent infinite loops, and log failures for troubleshooting.

How do I create a file in a directory that doesn't exist?

PowerShell cmdlets like Set-Content and Out-File will fail if the parent directory doesn't exist. Always check for directory existence using Test-Path and create it with New-Item -ItemType Directory -Force before writing files. The -Force parameter creates all intermediate directories in the path. Alternatively, wrap file operations in try-catch blocks and handle DirectoryNotFoundException by creating the directory and retrying the operation.

Can I write to files on network shares using PowerShell?

Yes, PowerShell can write to network shares using UNC paths (\\server\share\file.txt). Ensure you have appropriate permissions and that the remote share is accessible. Network file operations are subject to network latency and potential connectivity issues, so implement robust error handling and consider using retry logic. For better performance with large files over networks, consider using StreamWriter with appropriate buffer sizes.

How do I prevent data loss if my script fails while writing a file?

Implement atomic write operations by writing to a temporary file first, then renaming it to the final filename only after successful completion. Use try-catch-finally blocks to ensure cleanup of temporary files if errors occur. For critical data, create backups before overwriting existing files. Consider using transactions or write-ahead logging patterns for scenarios requiring strong consistency guarantees.