Merge pull request #8 from ActiveDirectoryManagementFramework/2023-march

1.1.9

Author: FriedrichWeinmann

ADMF.Core/ADMF.Core.psd1

@@ -3,7 +3,7 @@
 	RootModule = 'ADMF.Core.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '1.1.6'
+	ModuleVersion = '1.1.9'
 
 	# ID used to uniquely identify this module
 	GUID = '11e2d894-33d7-4020-a65e-f13c2f1893aa'
@@ -47,6 +47,7 @@
 		'Get-AdcExchangeVersion'
 		'New-AdcChange'
 		'Sync-AdcObject'
+		'Write-AdcChangeLog'
 	)
 
 	# Cmdlets to export from this module

ADMF.Core/changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.1.9 (2023-05-16)
+
+- New: Command Write-AdcChangeLog - Writes a log entry for change objects.
+- Upd: New-AdcChange - added `Data` parameter, to accept additional properties to include in the object.
+- Upd: New-AdcChange - added `ToString` parameter, to allow overriding default display styles.
+
 ## 1.1.6 (2023-02-10)
 
 - New: Command Compare-AdcProperty - Helper function simplifying the changes processing of Test-* commands.

ADMF.Core/en-us/strings.psd1

@@ -1,13 +1,15 @@
 # This is where the strings go, that are written by
 # Write-PSFMessage, Stop-PSFFunction or the PSFramework validation scriptblocks
 @{
-	'Get-LdapObject.SearchError'			 = 'Failed to execute ldap request.' # 
-	'Get-LdapObject.Searchfilter'		     = 'Searching with filter: {0}' # $LdapFilter
-	'Get-LdapObject.SearchRoot'			     = 'Searching {0} in {1}' # $SearchScope, $searcher.SearchRoot.Path
+	'Get-LdapObject.SearchError'             = 'Failed to execute ldap request.' # 
+	'Get-LdapObject.Searchfilter'            = 'Searching with filter: {0}' # $LdapFilter
+	'Get-LdapObject.SearchRoot'              = 'Searching {0} in {1}' # $SearchScope, $searcher.SearchRoot.Path
 
-	'Sync-AdcObject.ConnectError'		     = 'Failed to connect to {0}' # $errorObject.TargetObject
+	'Sync-AdcObject.ConnectError'            = 'Failed to connect to {0}' # $errorObject.TargetObject
 
 	'Sync-LdapObject.DestinationAccessError' = 'Failed to connect to destination server {0} | {1}' # $Target, $_
 	'Sync-LdapObject.PerformingReplication'  = 'Performing replication from {0} to {1}' # $Server, $Target
-	'Sync-LdapObject.SourceAccessError'	     = 'Failed to connect to source server {0} | {1}' # $Server, $_
+	'Sync-LdapObject.SourceAccessError'      = 'Failed to connect to source server {0} | {1}' # $Server, $_
+
+	'Write-AdcChangeLog.ChangeEntry'         = 'Updating {0} from {1} to {2} on {3}' # $change.Property, $change.Old, $change.New, $change.Identity
 }

ADMF.Core/functions/New-AdcChange.ps1

@@ -22,6 +22,15 @@
 	
 	.PARAMETER Type
 		The object/component type of the object being changed
+
+	.PARAMETER Data
+		Additional data to include in the change object.
+		Will ignore keys named "Property", "Old", "New" or "Identity"
+
+	.PARAMETER ToString
+		Scriptblock that determines, how the change is being displayed when a property itself.
+		Defaults to '<property> -> <newvalue>'
+		Use $this to refer to the object being displayed.
 	
 	.EXAMPLE
 		PS C:\> New-Change -Property Path -OldValue $adObject.DistinguishedName -NewValue $path -Identity $adObject -Type Object
@@ -43,15 +52,27 @@
 		$Identity,
 
 		[string]
-		$Type = 'Unknown'
+		$Type = 'Unknown',
+
+		[hashtable]
+		$Data = @{ },
+
+		[scriptblock]
+		$ToString = { '{0} -> {1}' -f $this.Property, $this.New }
 	)
 
-	$change = [PSCustomObject]@{
-		PSTypeName = "DomainManagement.$Type.Change"
+	$changeHash = @{
+		PSTypeName = "ADMF.$Type.Change"
 		Property   = $Property
 		Old        = $OldValue
 		New        = $NewValue
 		Identity   = $Identity
 	}
-	Add-Member -InputObject $change -MemberType ScriptMethod -Name ToString -Value { '{0} -> {1}' -f $this.Property, $this.New } -Force -PassThru
+	foreach ($pair in $Data.GetEnumerator()) {
+		if ($pair.Key -in $changeHash.Keys) { continue }
+		$changeHash[$pair.Key] = $pair.Value
+	}
+
+	$change = [PSCustomObject]$changeHash
+	Add-Member -InputObject $change -MemberType ScriptMethod -Name ToString -Value $ToString -Force -PassThru
 }

ADMF.Core/functions/Write-AdcChangeLog.ps1

@@ -0,0 +1,41 @@
+function Write-AdcChangeLog {
+	<#
+	.SYNOPSIS
+		Writes a log entry for change objects.
+	
+	.DESCRIPTION
+		Writes a log entry for change objects.
+		This is designed to provide standardized logging for changes being applied.
+
+		Use New-AdcChange to generate a change object in the format expected by this command.
+	
+	.PARAMETER Changes
+		The list of changes to log
+	
+	.EXAMPLE
+		PS C:\> Write-AdcChangeLog -Changes $testItem.Changed
+		
+		Writes log entries, one for each change in the $testItem variable.
+	#>
+	[CmdletBinding()]
+	param (
+		[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+		[AllowEmptyCollection()]
+		[AllowNull()]
+		$Changes
+	)
+
+	begin {
+		$param = @{
+			Level  = 'SomewhatVerbose'
+			String = 'Write-AdcChangeLog.ChangeEntry'
+			Tag    = 'change'
+		}
+	}
+
+	process {
+		foreach ($change in $Changes) {
+			Write-PSFMessage @param -StringValues $change.Property, $change.Old, $change.New, $change.Identity -Target $change -Data ($change | ConvertTo-PSFHashtable)
+		}
+	}
+}