#Requires -Version 7.0
#Requires -Modules @{ ModuleName='Microsoft.PowerShell.SecretManagement'; ModuleVersion='1.1.0' }

$ErrorActionPreference = 'Stop'
Set-StrictMode -Version Latest

function Invoke-DataBackup {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$TargetPath,

        [Parameter()]
        [switch]$Compress
    )

    begin {
        Write-Verbose "Starting backup to $TargetPath"
    }

    process {
        try {
            # Business logic here
        }
        catch [System.IO.IOException] {
            Write-Error "IO error during backup: $_"
            throw
        }
        catch {
            Write-Error "Unexpected error: $_"
            throw
        }
    }

    end {
        Write-Verbose "Backup complete"
    }
}

# Register a vault (one-time setup)
Register-SecretVault -Name 'AzureKeyVault' -ModuleName 'Az.KeyVault'

# Retrieve secret at runtime
$apiKey = Get-Secret -Name 'MyApiKey' -Vault 'AzureKeyVault' -AsPlainText

# Use in automation (never log the value)
$headers = @{ 'Authorization' = "Bearer $apiKey" }
Invoke-RestMethod -Uri $endpoint -Headers $headers

# Process structured data through the pipeline
Get-ChildItem -Path $target -Filter *.json |
    ForEach-Object {
        $data = Get-Content -Path $_.FullName | ConvertFrom-Json
        [PSCustomObject]@{
            FileName  = $_.Name
            ItemCount = $data.items.Count
            LastModified = $_.LastWriteTime
        }
    } |
    Sort-Object -Property ItemCount -Descending |
    Export-Csv -Path 'report.csv' -NoTypeInformation

# Invoke-DataBackup.Tests.ps1
Describe 'Invoke-DataBackup' {
    BeforeAll {
        . $PSScriptRoot/Invoke-DataBackup.ps1
    }

    Context 'When target path exists' {
        It 'Should create backup file' {
            $result = Invoke-DataBackup -TargetPath $TestDrive
            $result | Should -Not -BeNullOrEmpty
            Test-Path "$TestDrive/backup.zip" | Should -BeTrue
        }
    }

    Context 'When target path is invalid' {
        It 'Should throw IO exception' {
            { Invoke-DataBackup -TargetPath '/nonexistent/path' } |
                Should -Throw -ExceptionType ([System.IO.IOException])
        }
    }
}

# Use Join-Path for all path operations
$configPath = Join-Path -Path $HOME -ChildPath '.config' -AdditionalChildPath 'myapp', 'settings.json'

# Check platform before using platform-specific features
if ($IsWindows) {
    # Windows-specific: registry, WMI, COM
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
} elseif ($IsLinux -or $IsMacOS) {
    # Unix-specific: /proc, systemctl
    $os = uname -a
}