Merge branch 'dev' into 'master'

jeefo93 · jeefo93 · commit acbe232c9e9e · 2023-09-26T13:59:17.000Z
Adds an option to ignore the source path when determining workload to be migrated; fixes the proactively locked host issue

See merge request fozzy-winadmins/AutomaticMaintenance!25
diff --git a/AutomaticMaintenance-Hosts-Example.json b/AutomaticMaintenance-Hosts-Example.json
@@ -20,9 +20,10 @@
         "Workload": [
             {
                 "Path": "D:\\VMs",
+                "SourcePathFilterDisabled": true,
                 "DestinationName": "SRV05",
                 "DestinationPath": "E:\\VMs",
-                "Filter": "$_.Name -notlike '*-DontMove'"
+                "Filter": "$_.Name -notin @('StaticVM1', 'StaticVM2') -and $_.Location -notlike 'F:\\StaticVMs*'"
             }
         ]
     },
diff --git a/AutomaticMaintenance.psd1 b/AutomaticMaintenance.psd1
@@ -1,6 +1,6 @@
 @{
     RootModule        = 'AutomaticMaintenance.psm1'
-    ModuleVersion     = '2.10.0'
+    ModuleVersion     = '2.11.0'
     GUID              = '8e34abf8-40ba-4c68-8bf8-f235cd001d82'
     Author            = 'Kirill Nikolaev'
     CompanyName       = 'Fozzy Inc.'
diff --git a/AutomaticMaintenance.psm1 b/AutomaticMaintenance.psm1
@@ -29,7 +29,7 @@ $ModuleName = ($MyInvocation.MyCommand.Name).Substring(0, ($MyInvocation.MyComma
 [System.TimeSpan]$ModuleWidePreventiveLockThreshold = New-Object -TypeName 'System.TimeSpan' -ArgumentList @(1, 0, 0)
 [bool]$ModuleWideSkipPreventivelyLocked = $true
 [bool]$ModuleWideSkipNotLockable = $true
-[string]$ModuleWideSkipPreventivelyLockedFullyQualifiedErrorId = 'SkipPreventivelyLockedHost'
+[string]$ModuleWideSkipPreventivelyLockedExceptionTarget = 'SkipPreventivelyLockedHost'
 
 [int]$ModuleWideInstallUpdateTimeout = 60
 [System.TimeSpan]$ModuleWideInstallUpdateThreshold = New-Object -TypeName 'System.TimeSpan' -ArgumentList @(1, 0, 0)
diff --git a/Private/HV/Get-HVFilterString.ps1 b/Private/HV/Get-HVFilterString.ps1
@@ -6,7 +6,8 @@ function Get-HVFilterString {
         [string]$Path,
         [string]$Filter,
         [ValidateSet('HV-SCVMM', 'HV-Vanilla')]
-        [string]$Mode = 'HV-SCVMM'
+        [string]$Mode = 'HV-SCVMM',
+        [switch]$ExcludePathFromFilter
     )
 
     $ErrorActionPreference = 'Stop'
@@ -19,25 +20,27 @@ function Get-HVFilterString {
         Write-Debug -Message ('$Path = ''{0}''' -f $Path)
         Write-Debug -Message ('$Filter = ''{0}''' -f $Filter)
         Write-Debug -Message ('$Mode = ''{0}''' -f $Mode)
+        Write-Debug -Message ('$ExcludePathFromFilter = ${0}' -f $ExcludePathFromFilter)
 
-        Write-Debug -Message '$VMLocationPropertyName = switch ($Mode)'
-        $VMLocationPropertyName = switch ($Mode) {
-            'HV-SCVMM' {
-                Write-Debug -Message 'Location'
-                'Location'
+        Write-Debug -Message 'if ($Path -and -not $ExcludePathFromFilter)'
+        if ($Path -and -not $ExcludePathFromFilter) {
+            Write-Debug -Message '$VMLocationPropertyName = switch ($Mode)'
+            $VMLocationPropertyName = switch ($Mode) {
+                'HV-SCVMM' {
+                    Write-Debug -Message 'Location'
+                    'Location'
+                }
+                'HV-Vanilla' {
+                    Write-Debug -Message 'Path'
+                    'Path'
+                }
+                Default {
+                    Write-Debug -Message 'Location'
+                    'Location'
+                }
             }
-            'HV-Vanilla' {
-                Write-Debug -Message 'Path'
-                'Path'
-            }
-            Default {
-                Write-Debug -Message 'Location'
-                'Location'
-            }
-        }
-        Write-Debug -Message ('$VMLocationPropertyName = ''{0}''' -f $VMLocationPropertyName)
+            Write-Debug -Message ('$VMLocationPropertyName = ''{0}''' -f $VMLocationPropertyName)
 
-        if ($Path) {
             Write-Debug -Message ('$FilterPath = [System.IO.Path]::Combine(''{0}'', ''*'')' -f $Path)
             $FilterPath = [System.IO.Path]::Combine($Path, '*') # Join-Path cannot combine paths on a drive which does not exist on the machine
             Write-Debug -Message ('$FilterPath = ''{0}''' -f $FilterPath)
@@ -57,8 +60,15 @@ function Get-HVFilterString {
         }
         Write-Debug -Message ('$FilterString = ''{0}''' -f $FilterString)
 
-        Write-Debug -Message ('[scriptblock]::Create(''{0}'')' -f $FilterString)
-        [scriptblock]::Create($FilterString)
+        Write-Debug -Message 'if ($FilterString)'
+        if ($FilterString) {
+            Write-Debug -Message ('[scriptblock]::Create(''{0}'')' -f $FilterString)
+            [scriptblock]::Create($FilterString)
+        }
+        else {
+            Write-Debug -Message '$null'
+            $null
+        }
 
         Write-Debug -Message ('EXIT TRY {0}' -f $MyInvocation.MyCommand.Name)
     }
diff --git a/Private/HV/Get-HVFilterStringCompatible.ps1 b/Private/HV/Get-HVFilterStringCompatible.ps1
@@ -41,8 +41,8 @@ function Get-HVFilterStringCompatible {
         }
         Write-Debug -Message ('$Filter = ''{0}''' -f $Filter)
 
-        Write-Debug -Message ('Get-HVFilterString -Path ''{0}'' -Filter ''{1}'' -Mode ''{2}''' -f $Path, $Filter, $Mode)
-        Get-HVFilterString -Path $Path -Filter $Filter -Mode $Mode
+        Write-Debug -Message ('Get-HVFilterString -Path ''{0}'' -Filter ''{1}'' -Mode ''{2}'' -ExcludePathFromFilter:${3}' -f $Path, $Filter, $Mode, [bool]$WorkloadPair.SourcePathFilterDisabled)
+        Get-HVFilterString -Path $Path -Filter $Filter -Mode $Mode -ExcludePathFromFilter:$WorkloadPair.SourcePathFilterDisabled
 
         Write-Debug -Message ('EXIT TRY {0}' -f $MyInvocation.MyCommand.Name)
     }
diff --git a/Private/Initialize-ComputerMaintenance.ps1 b/Private/Initialize-ComputerMaintenance.ps1
@@ -9,7 +9,7 @@ function Initialize-ComputerMaintenance {
         [ref]$DestinationHostLock,
         [switch]$SkipNotLockable,
         [switch]$SkipPreventivelyLocked,
-        [string]$SkipPreventivelyLockedFullyQualifiedErrorId
+        [string]$SkipPreventivelyLockedExceptionTarget
     )
 
     $ErrorActionPreference = 'Stop'
@@ -26,6 +26,7 @@ function Initialize-ComputerMaintenance {
         Write-Debug -Message ('$DestinationHostLock.Value: ''{0}''' -f $DestinationHostLock.Value)
         Write-Debug -Message ('$SkipNotLockable = ${0}' -f $SkipNotLockable)
         Write-Debug -Message ('$SkipPreventivelyLocked = ${0}' -f $SkipPreventivelyLocked)
+        Write-Debug -Message ('SkipPreventivelyLockedExceptionTarget = ''{0}''' -f $SkipPreventivelyLockedExceptionTarget)
 
         Write-Debug -Message '$CallerName = Get-LockCallerName'
         $CallerName = Get-LockCallerName
@@ -77,7 +78,7 @@ function Initialize-ComputerMaintenance {
                         Write-Debug -Message 'if ($SkipPreventivelyLocked)'
                         if ($SkipPreventivelyLocked) {
                             $Message = ('Skipping the computer {0} because it is locked by other sources for more than {1} already and $SkipPreventivelyLocked is {2}.' -f $ComputerName, [string]$PreventiveLockThreshold, [string]$SkipPreventivelyLocked)
-                            $PSCmdlet.ThrowTerminatingError((New-Object -TypeName 'System.Management.Automation.ErrorRecord' -ArgumentList ((New-Object -TypeName 'System.OperationCanceledException' -ArgumentList $Message), $SkipPreventivelyLockedFullyQualifiedErrorId, [System.Management.Automation.ErrorCategory]::OperationStopped, $null)))
+                            $PSCmdlet.ThrowTerminatingError((New-Object -TypeName 'System.Management.Automation.ErrorRecord' -ArgumentList ((New-Object -TypeName 'System.OperationCanceledException' -ArgumentList $Message), 'OperationStopped', [System.Management.Automation.ErrorCategory]::OperationStopped, $SkipPreventivelyLockedExceptionTarget)))
                         }
                         else {
                             $Message = ('Computer {0} is locked by other sources for more than {1} already' -f $ComputerName, [string]$PreventiveLockThreshold)
diff --git a/Public/Invoke-ComputerMaintenance.ps1 b/Public/Invoke-ComputerMaintenance.ps1
@@ -6,7 +6,7 @@ function Invoke-ComputerMaintenance {
         [string]$ComputerName,
         [int]$PreventiveLockTimeout = $ModuleWidePreventiveLockTimeout,
         [System.TimeSpan]$PreventiveLockThreshold = $ModuleWidePreventiveLockThreshold,
-        [string]$SkipPreventivelyLockedFullyQualifiedErrorId = $ModuleWideSkipPreventivelyLockedFullyQualifiedErrorId,
+        [string]$SkipPreventivelyLockedExceptionTarget = $ModuleWideSkipPreventivelyLockedExceptionTarget,
         [switch]$SkipNotLockable = $ModuleWideSkipNotLockable,
         [switch]$SkipPreventivelyLocked = $ModuleWideSkipPreventivelyLocked,
         [switch]$EnableMaintenanceLog = $ModuleWideEnableMaintenanceLog
@@ -22,6 +22,7 @@ function Invoke-ComputerMaintenance {
         Write-Debug -Message ('$ComputerName = ''{0}''' -f $ComputerName)
         Write-Debug -Message ('$PreventiveLockTimeout = {0}' -f $PreventiveLockTimeout)
         Write-Debug -Message ('$PreventiveLockThreshold: ''{0}''' -f [string]$PreventiveLockThreshold)
+        Write-Debug -Message ('SkipPreventivelyLockedExceptionTarget = ''{0}''' -f $SkipPreventivelyLockedExceptionTarget)
         Write-Debug -Message ('$SkipNotLockable = ${0}' -f $SkipNotLockable)
         Write-Debug -Message ('$SkipPreventivelyLocked = ${0}' -f $SkipPreventivelyLocked)
         Write-Debug -Message ('$EnableMaintenanceLog = ${0}' -f $EnableMaintenanceLog)
@@ -45,8 +46,8 @@ function Invoke-ComputerMaintenance {
             Write-Debug -Message 'if ($PendingReboot.ComponentBasedServicing)'
             if ($PendingReboot.ComponentBasedServicing) {
                 # Sometimes, when CBS requires reboot, search for updates hangs up. Therefore, we need to reboot the machine first.
-                Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedFullyQualifiedErrorId ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedFullyQualifiedErrorId)
-                $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedFullyQualifiedErrorId $SkipPreventivelyLockedFullyQualifiedErrorId
+                Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedExceptionTarget ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedExceptionTarget)
+                $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedExceptionTarget $SkipPreventivelyLockedExceptionTarget
                 Write-Debug -Message ('$ComputerWorkload: ''{0}''' -f [string]$ComputerWorkload)
 
                 Write-Debug -Message ('$HostLock: ''{0}''' -f $HostLock)
@@ -73,8 +74,8 @@ function Invoke-ComputerMaintenance {
                 $IsMaintenanceNeeded = Test-MaintenanceNeeded -ComputerName $ComputerName
                 Write-Debug -Message ('$IsMaintenanceNeeded = ${0}' -f $IsMaintenanceNeeded)
                 if ($IsMaintenanceNeeded) {
-                    Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedFullyQualifiedErrorId ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedFullyQualifiedErrorId)
-                    $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedFullyQualifiedErrorId $SkipPreventivelyLockedFullyQualifiedErrorId
+                    Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedExceptionTarget ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedExceptionTarget)
+                    $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedExceptionTarget $SkipPreventivelyLockedExceptionTarget
                     Write-Debug -Message ('$ComputerWorkload: ''{0}''' -f [string]$ComputerWorkload)
                     Write-Debug -Message ('$HostLock: ''{0}''' -f $HostLock)
                     Write-Debug -Message 'if ($HostLock)'
@@ -91,8 +92,8 @@ function Invoke-ComputerMaintenance {
                     # If the machine does not need any updates, but just a reboot, let's reboot it.
                     Write-Debug -Message ('$PendingReboot.IsRebootPending: ''{0}''' -f $PendingReboot.IsRebootPending)
                     if ($PendingReboot.IsRebootPending) {
-                        Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedFullyQualifiedErrorId ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedFullyQualifiedErrorId)
-                        $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedFullyQualifiedErrorId $SkipPreventivelyLockedFullyQualifiedErrorId
+                        Write-Debug -Message ('$ComputerWorkload = Initialize-ComputerMaintenance -ComputerName ''{0}'' -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:${1} -SkipPreventivelyLocked:${2} -SkipPreventivelyLockedExceptionTarget ''{3}''' -f $ComputerName, $SkipNotLockable, $SkipPreventivelyLocked, $SkipPreventivelyLockedExceptionTarget)
+                        $ComputerWorkload = Initialize-ComputerMaintenance -ComputerName $ComputerName -HostLock ([ref]$HostLock) -DestinationHostLock ([ref]$DestinationHostLock) -SkipNotLockable:$SkipNotLockable -SkipPreventivelyLocked:$SkipPreventivelyLocked -SkipPreventivelyLockedExceptionTarget $SkipPreventivelyLockedExceptionTarget
                         Write-Debug -Message ('$ComputerWorkload: ''{0}''' -f [string]$ComputerWorkload)
                         Write-Debug -Message ('$HostLock: ''{0}''' -f $HostLock)
                         Write-Debug -Message 'if ($HostLock)'
@@ -114,9 +115,9 @@ function Invoke-ComputerMaintenance {
     catch {
         Write-Debug -Message ('ENTER CATCH {0}' -f $MyInvocation.MyCommand.Name)
 
-        Write-Debug -Message ('$_.FullyQualifiedErrorId: ''{0}''' -f $_.FullyQualifiedErrorId)
-        Write-Debug -Message ('if ($_.FullyQualifiedErrorId -ne ''{0}'')' -f $SkipPreventivelyLockedFullyQualifiedErrorId)
-        if ($_.FullyQualifiedErrorId -ne $SkipPreventivelyLockedFullyQualifiedErrorId) {
+        Write-Debug -Message ('$_.TargetObject: ''{0}''' -f $_.TargetObject)
+        Write-Debug -Message ('if ($_.TargetObject -ne ''{0}'')' -f $SkipPreventivelyLockedExceptionTarget)
+        if ($_.TargetObject -ne $SkipPreventivelyLockedExceptionTarget) {
 
             Write-Debug -Message ('{0}: $PSCmdlet.ThrowTerminatingError($_)' -f $MyInvocation.MyCommand.Name)
             $PSCmdlet.ThrowTerminatingError($_)
diff --git a/docs-additional/Configuration.md b/docs-additional/Configuration.md
@@ -55,10 +55,13 @@ Each attribute is usually a name of a PowerShell script, located in the `$Module
 
 Workload objects have the following attributes:
 
-* Path - Path where VM's configuration is located.
+* Path - Path where VM's configuration is located and where VM's configuration will be stored after maintenance.
 * DestinationName - Destination host's name where to move virtual machines.
 * DestinationPath - Local path on the destination host.
 * Filter - Defines a filter which will be used to pick VMs from the source host. For example, if you wish for some VMs not to mirate, but stay at the source host during maintenance, you can filter them out here.
+* DestinationFilter - This setting specifies the filter that will be applied to VMs on the migration hypervisor before the migration starts and allows to ignore a workload that is already on the hypervisor. Otherwise, the module's default behavior will stop processing, assuming that the migration hypervisor is already busy. It could be useful when the "Workload" block contains several sets of settings, or the migration hypervisor already has the virtual machines that are not related to ongoing maintenance.
+* SourcePathFilterDisabled - When set to `false` or not specified, the module applies the `Filter` option to the VMs located in the `Path` folder, therefore the module migrates filtered VMs from the `Path` folder only.  When set to `true`, the module applies the `Filter` option to all VMs on the source host and migrates all filtered VMs. If both `SourcePathFilterDisabled` is `true` and `Filter` is not specified, all VMs will be considered as a workload to be migrated.
+
 
 #### HV-Vanilla
 

Original file line number	Diff line number	Diff line change
`@@ -20,9 +20,10 @@`
`20`	`20`	`"Workload": [`
`21`	`21`	`{`
`22`	`22`	`"Path": "D:\\VMs",`
	`23`	`+ "SourcePathFilterDisabled": true,`
`23`	`24`	`"DestinationName": "SRV05",`
`24`	`25`	`"DestinationPath": "E:\\VMs",`
`25`		`- "Filter": "$_.Name -notlike '*-DontMove'"`
	`26`	`+ "Filter": "$_.Name -notin @('StaticVM1', 'StaticVM2') -and $_.Location -notlike 'F:\\StaticVMs*'"`
`26`	`27`	`}`
`27`	`28`	`]`
`28`	`29`	`},`
Original file line number	Diff line number	Diff line change
`@@ -41,8 +41,8 @@ function Get-HVFilterStringCompatible {`
`41`	`41`	`}`
`42`	`42`	`Write-Debug -Message ('$Filter = ''{0}''' -f $Filter)`
`43`	`43`
`44`		`- Write-Debug -Message ('Get-HVFilterString -Path ''{0}'' -Filter ''{1}'' -Mode ''{2}''' -f $Path, $Filter, $Mode)`
`45`		`- Get-HVFilterString -Path $Path -Filter $Filter -Mode $Mode`
	`44`	`+ Write-Debug -Message ('Get-HVFilterString -Path ''{0}'' -Filter ''{1}'' -Mode ''{2}'' -ExcludePathFromFilter:${3}' -f $Path, $Filter, $Mode, [bool]$WorkloadPair.SourcePathFilterDisabled)`
	`45`	`+ Get-HVFilterString -Path $Path -Filter $Filter -Mode $Mode -ExcludePathFromFilter:$WorkloadPair.SourcePathFilterDisabled`
`46`	`46`
`47`	`47`	`Write-Debug -Message ('EXIT TRY {0}' -f $MyInvocation.MyCommand.Name)`
`48`	`48`	`}`