PsBackupUtil.psm1

#------------------------------------------------------------------------------
# PSBackupUtil™
# Copyright (c) 2019-2023 Zareh DerGevorkian
#------------------------------------------------------------------------------
# Creates a Zip file containing the contents of the specified folder, 
# excluding any specified subfolders, files, and file types.
#
# Each time the script executes, it determines whether a full or partial 
# backup should be performed based on the date/time and type of the last 
# backup. Full backups are created initially, then every N days. Partial 
# backups are created in the interim to archive only files that have 
# changed since the last full or partial backup.
#
# Zip file names are formated as follows:
#  <base-name>-<yyyy>-<MM>-<dd>-<HH>-<mm>-<ss>[-<archive-mode-marker>].<extension>
#  Where:
#    <base-name> => User specified, or name of folder to be archived
#    y, M, d, H, m, s => components of current date/time in 24-hour format
#    <archive-mode-Marker> => Full | Part | <blank>
#    <extension> => User sepcified (default: 'zip')
#------------------------------------------------------------------------------


using namespace System.IO


function Backup-FolderContents {
    [CmdletBinding()]
    param (
        # Folder (contents of which are) to be archived.
        [parameter(Mandatory, HelpMessage = "The folder (contents of which are) to be archived.")]
        [ValidateScript( { Test-Path $_ } )]
        [ValidateNotNullOrEmpty()]
        [string] $SourceFolder,

        # Folder where the archive file for the backup will be placed.
        #[ValidateScript( { Test-Path $_ } )]
        [parameter(Mandatory, HelpMessage = "Folder where the archive file for the backup will be placed.")]
        [ValidateNotNullOrEmpty()]
        [string] $DestinationFolder,

        # The base name to use for naming the backup file (default: source folder name).
        [parameter(HelpMessage = "The base name to use for naming the backup file (default: source folder name).")]
        [string] $BaseName,

        # Extension for backup file name (default: 'zip').
        [parameter(HelpMessage = "Extension for backup file name (default: 'zip').")]
        [string]
        $Extension = "zip",

        # Number of days between full backups. Default = 7
        [Parameter(HelpMessage = "Number of days between full backups. Defaults to 7.")]
        [int] $FullBackupInterval = 7,

        # Remove prior period partial backup file(s) after creating a full-backup.
        [Parameter(HelpMessage = "Remove prior period partial backup file(s) after creating a full-backup.")]
        [switch] $RemovePartialsAfterFull,

        # Marker text for Full backup archive-file names (default: 'Full').
        [Parameter(HelpMessage = "Marker text for Full backup archive-file names (default: 'Full').")]
        [string] $FullBackupMarker = "Full",

        # Marker text for Partial backup archive-file names (default: 'Part').
        [Parameter(HelpMessage = "Marker text for Partial backup archive-file names (default: 'Part').")]
        [string] $PartialBackupMarker = "Part",

        # Names of folders to omit from the backup.
        [string[]] $IgnoreFolders,

        # File extensions for file types to omit from the backup,
        [string[]] $IgnoreFileTypes,

        # Names of files (name & extensions, no path) to omit from the backup.
        [string[]] $IgnoreFiles
    )

    try {
        $sw = [System.Diagnostics.Stopwatch]::StartNew()

        $src = $SourceFolder
        $dst = $DestinationFolder
        $base = $BaseName

        Invoke-UpdateNameFormatOfExistingFiles $dst $Extension

        if ([string]::IsNullOrWhiteSpace($base)) {
            $base = Split-Path $src -Leaf
        }        

        $base = $base -replace "-", "_"

        $Mode = Get-NextBackupMode $base $dst $FullBackupInterval $Extension

        $type = if ($Mode -eq ([ArchiveMode]::Unknown)) { $null } else { "$Mode " }
        Write-Information "Performing $($type)Backup for $base" -InformationAction Continue

        Invoke-RunBackup `
            $src $dst $Mode $base $Extension `
            -IgnoreFolders $IgnoreFolders `
            -IgnoreFileTypes $IgnoreFileTypes `
            -IgnoreFiles $IgnoreFiles

        Write-Information `
            "Operation completed in $($sw.Elapsed.TotalSeconds) seconds for $base ($SourceFolder)" `
            -InformationAction Continue
    }
    catch {
        Write-Error $_
    }
}


function Invoke-RunBackup {
    param (
        # Folder containing fiels to be backed up.
        [parameter(Mandatory)]
        [ValidateScript( { Test-Path $_ } )]
        [ValidateNotNullOrEmpty()]
        [string] $SourceFolder,

        # Folder where the archive file for the backup will be created/placed.
        #[ValidateScript( { Test-Path $_ } )]
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $DestinationFolder,

        # Backup mode: Full or Partial?
        [parameter(Mandatory)]
        [ValidateScript( { $_ -ne ([ArchiveMode]::Unknown) } )]
        [ArchiveMode] $ArchiveMode,

        # Base name for backup file.
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $Basename,

        # File extension (default: 'zip').
        [string]
        $Extension = "zip",

        [string[]] $IgnoreFolders,
        [string[]] $IgnoreFileTypes,
        [string[]] $IgnoreFiles
    )

    $ArchiveName = Get-NewArchiveName $Basename $ArchiveMode $Extension
    $ArchiveName = join-path -Path $DestinationFolder -ChildPath $ArchiveName
    Write-Verbose "Invoke-RunBackup: ArchiveName = $ArchiveName"


    $Files = Get-FilesForBackup `
        $SourceFolder `
        -IgnoreFolders $IgnoreFolders `
        -IgnoreFileTypes $IgnoreFileTypes `
        -IgnoreFiles $IgnoreFiles

    $CountFiles = ($Files).Count
    
    Write-Debug "Invoke-RunBackup: Count All Files = $CountFiles"
    
    # $Files | Select-Object -Property FullName

    if (($null -eq $Files) -or (0 -ge $CountFiles)) {
        Write-Warning "Invoke-RunBackup: Source folder contains no files that can be archived."
        return
    }


    $DtLastFull = Get-DateMostRecentArchive $DestinationFolder $Basename ([ArchiveMode]::Full) $Extension
    $DtChangedAfter = $DtLastFull
    if ($null -eq $DtLastFull) { 
        $DtChangedAfter = [datetime]::MinValue
    }

    if ([ArchiveMode]::Partial -eq $ArchiveMode) {
        $DtLastPartial = Get-DateMostRecentArchive $DestinationFolder $Basename ([ArchiveMode]::Partial) $Extension
        if (($null -ne $DtLastPartial) -and ($DtLastPartial -gt $DtLastFull)) {
            $DtChangedAfter = $DtLastPartial 
        }

        $Files = $Files | Where-Object {
            $_.PSIsContainer -or
            $(!$_.PSIsContainer -and $_.LastWriteTime -gt $DtChangedAfter)
        }

        $CountFiles = ($Files).Count

        Write-Debug "Invoke-RunBackup: ArchiveMode = $ArchiveMode, DtChangedAfter = $DtChangedAfter, Count Changed Files = $CountFiles"

        if (($null -eq $Files) -or (0 -ge $CountFiles)) {
            Write-Information "Nothing to do. No changed files since last backup." -InformationAction Continue
            return
        }
    }

    if ([ArchiveMode]::Partial -ne $ArchiveMode) {
        if ([datetime]::MinValue -ne $DtChangedAfter) {
            $CountChangedSinceLastFull = $($Files | Where-Object {
                    $_.PSIsContainer -or
                    $(!$_.PSIsContainer -and $_.LastWriteTime -gt $DtChangedAfter)
                }).Count
            # } | Measure-Object -Property Length).Count

            Write-Debug "Invoke-RunBackup: ArchiveMode = $ArchiveMode, DtChangedAfter = $DtChangedAfter"

            if (0 -ge $CountChangedSinceLastFull) {
                Write-Information "Nothing to do. No changed files since last full backup." -InformationAction Continue
                return
            }
        }
    }

    Write-Information "Backing Up $CountFiles file(s)..." -InformationAction Continue
    Invoke-CreateArchive $SourceFolder $DestinationFolder $ArchiveName $Files
}

function Get-FilesForBackup {
    param (
        # Folder containing fiels to be backed up.
        [parameter(Mandatory)]
        [ValidateScript( { Test-Path $_ } )]
        [ValidateNotNullOrEmpty()]
        [string] $SourceFolder,

        [string[]] $IgnoreFolders,
        [string[]] $IgnoreFileTypes,
        [string[]] $IgnoreFiles
    )

    $ignore = $IgnoreFiles + $IgnoreFileTypes

    $Files = `
        Get-ChildItem $SourceFolder -File -Exclude $ignore -Recurse -Force | `
        Where-Object { 
        $(
            # $(!$_.PSIsContainer -and $_.LastWriteTime -gt $DtChangedAfter) -or
            !$_.PSIsContainer -or
            $($_.PSIsContainer -and $_.Name -inotin $IgnoreFolders)
        ) -and $(
            foreach ($fig in $IgnoreFolders) { 
                if (($_ -imatch "\\$fig\\" ) -or ($_ -imatch "/$fig/" )) {
                    return $false
                }
            }
            $true # return $true
        ) } | `
        Select-Object | `
        Sort-Object -Property FullName, Name

    return $Files
}

function Invoke-CreateArchive {
    param (
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $SourceFolder,

        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $DestinationFolder,

        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $ArchiveName,

        [parameter(Mandatory)]
        [string[]] $Files
    )

    if (0 -ge $Files.Length) {
        Write-Warning "Nothing to do: No files to archive."
        return 
    }
    
    $FolderSeparator = [Path]::DirectorySeparatorChar.ToString()
    [bool] $haveFiles = $false

    $TempFolder = Join-Path -Path $DestinationFolder -ChildPath $(Split-Path $SourceFolder -Leaf)
    if (Test-path $TempFolder) {
        Remove-Item $TempFolder -Recurse -Force
    }
    New-Item -Path $TempFolder -ItemType Directory -ErrorAction Stop | Out-Null
    
    $Files | ForEach-Object {
        $relPath = $_.SubString($SourceFolder.Length) | Split-Path -Parent
        if (-not $relPath.Equals($FolderSeparator)) {
            $tempPath = Join-Path -Path $TempFolder -ChildPath $relPath
            if (-not (Test-Path $tempPath)) {
                New-Item -ItemType Directory -Path $tempPath -ErrorAction Stop | Out-Null
            }
        }
        else {
            $tempPath = $TempFolder
        }
        Copy-Item $_ -Destination $tempPath -ErrorAction Stop 
        if ($haveFiles -ne $true) { $haveFiles = $true }
    }

    if ($haveFiles) {
        Compress-Archive -Path $TempFolder -DestinationPath $ArchiveName -CompressionLevel Optimal
    }
    Remove-Item $TempFolder -Recurse -Force
}


function Get-NewArchiveName {
    param (
        # Base name for archive file.
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]
        $BaseName,

        # Optional archive mode (default: Unknown).
        [parameter()]
        [ArchiveMode]
        $ArchiveType,
 
        # Optional file extension (default: 'zip').
        [parameter()]
        [string]
        $Extension = "zip"
    )
    $DtNow = [datetime]::Now
    $Marker = Get-ArchiveModeMarker $ArchiveType
    if (-not [string]::IsNullOrWhiteSpace($Marker)) { $Marker = "-$Marker" }

    return "$($BaseName)-$($DtNow.ToString('yyyy-MM-dd-HH-mm-ss'))$($Marker).$($Extension)"
}

function Get-NextBackupMode {
    param (
        # The base name for the archived files.
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $Basename,

        # Folder in which backups are stored.
        [parameter(Mandatory)]
        [string] $BackupsFolder,

        # Number of days between full backups.
        [parameter(Mandatory)]
        [int] $DaysBetweenFullBackups,
        
        # The archive file extension (default: 'zip').
        [string]
        $Extension = "zip"
    )

    if (-not $(Test-Path $BackupsFolder)) {
        return [ArchiveMode]::Full
    }

    $DtLastFullBackup = Get-DateMostRecentArchive $BackupsFolder $Basename ([ArchiveMode]::Full) $Extension

    if ($null -eq $DtLastFullBackup) {
        return [ArchiveMode]::Full
    }

    $NumDaysSince = ([timespan] ([datetime]::Now - $DtLastFullBackup)).Days
    if ($NumDaysSince -ge $DaysBetweenFullBackups) {
        return [ArchiveMode]::Full
    }
    else {
        return [ArchiveMode]::Partial
    }
}

function Get-DateMostRecentArchive {
    param (
        # Folder where backup files are stored.
        #[ValidateScript( { Test-Path $_ } )]
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]
        $BackupsFolder,

        # Base name of archive file.
        [parameter(Mandatory)]
        [string]
        $BaseName,

        # Archive type to look for: Full or Partial?
        [parameter(Mandatory)]
        [ArchiveMode]
        $ArchiveType,

        # Archive file name extension (defaults to 'zip').
        [parameter()]
        [string]
        $Extension = "zip"
    )

    if (-not $(Test-Path $BackupsFolder)) { return $null }

    $OldCwd = [Directory]::GetCurrentDirectory()
    $Cwd = Get-Location
    [Directory]::SetCurrentDirectory($Cwd)
    try {
        $Marker = Get-ArchiveModeMarker $ArchiveType
        if (-not [string]::IsNullOrWhiteSpace($Marker)) { $Marker = "-$Marker" }

        $Path = Join-Path -Path $BackupsFolder -ChildPath "$($BaseName)*$($Marker).$($Extension)"
        $Path = [Path]::GetFullPath($Path)

        # if (0 -ge (Get-ChildItem $Path | Measure-Object -Property Length).Count) {
        if (0 -ge (Get-ChildItem $Path).Count) {
            return $null
        }

        $ArchiveName = Get-ChildItem $Path | Sort-Object -Property FullName | Select-Object -Last 1 | Split-Path -Leaf
        Write-Verbose "Get-DateMostRecentArchive: Mode = $ArchiveType, Archive = $ArchiveName"

        return Get-DateFromArchiveName $ArchiveName
    }
    finally {
        [Directory]::SetCurrentDirectory($OldCwd)
    }
}

function Get-DateFromArchiveName {
    param (
        # The name of the archive file (expected format: [<base-name>][-<marker>]-<yyyy>-<MM>-<dd>-<HH>-<mm>.<extension>).
        #[ValidateRegEx()]
        [parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string] $ArchiveName
    )

    $Name = [Path]::GetFileNameWithoutExtension($ArchiveName)

    $DtParts = $Name.Split("-") | Select-Object -Skip 1 -First 6
    $DtString = $DtParts | Select-Object -First 3 | Join-String -Separator "-"
    $DtString += " " + $($DtParts | Select-Object -Last 3 | Join-String -Separator ":")

    Write-Verbose "Get-DateFromArchiveName: DtString = $DtString"

    return [datetime]::ParseExact($DtString, "yyyy-MM-dd HH:mm:ss", $null)
}

function Get-ArchiveModeMarker {
    param (
        [parameter(Mandatory)]
        [ArchiveMode]
        $ArchiveMode
    )
    
    $Marker = [ArchiveMode]::Unknown

    switch ($ArchiveMode) {
        ([ArchiveMode]::Full) { $Marker = "Full" }
        ([ArchiveMode]::Partial) { $Marker = "Part" }
        Default { $Marker = "" }
    }

    return $Marker
}


enum ArchiveMode {
    Unknown
    Full
    Partial
}


function Invoke-UpdateNameFormatOfExistingFiles {
    [CmdletBinding()]
    param (
        # Folder where archive files are located
        [parameter(Mandatory, HelpMessage = "Folder containing archive files with old naming style.")]
        # [ValidateNotNullOrEmpty()]
        # [ValidateScript( { Test-Path $_ } )]
        [string] $ArchiveFolder,

        # Extension for backup file name (default: 'zip').
        [parameter(HelpMessage = "Extension for backup file name (default: 'zip').")]
        [string]
        $Extension = "zip"
    )
    try {
        if ([string]::IsNullOrWhiteSpace($ArchiveFolder) -or
            ($true -ne (Test-Path $ArchiveFolder))) {
            return
        }
    
        $MarkerFull = Get-ArchiveModeMarker ([ArchiveMode]::Full)
        $MarkerPart = Get-ArchiveModeMarker ([ArchiveMode]::Partial)
        $FileSpec = Join-Path $ArchiveFolder "*.$($Extension)"
        $Files = Get-ChildItem $FileSpec -File -Recurse -Force

        $Files | ForEach-Object {
            $PathName = $_.FullName
            $FileName = [Path]::GetFileNameWithoutExtension($PathName)
            $FileExt = [Path]::GetExtension($PathName)

            $NameParts = $FileName.Split("-")
            $BaseName = $NameParts | Select-Object -First 1
            $Mode = $NameParts | Select-Object -Skip 1 -First 1

            $IsMode = $Mode -iin ($MarkerFull, $MarkerPart) -and -not "$Mode".StartsWith("20")

            if ($IsMode) {
                $DtParts = $NameParts | Select-Object -Last 5
                $DtString = $DtParts | Join-String -Separator "-"
            
                $NewName = "$BaseName-$DtString-00-$Mode$FileExt"
            
                Rename-Item -Path $PathName $NewName
            }
        }
    }
    catch {
        Write-Error $_
    }
}



Export-ModuleMember "Backup-FolderContents"