Set-SqlDscAudit: Add AllowAuditGuidChange for opt-in GUID change

CHANGELOG.md

@@ -96,6 +96,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added integration tests for `Add-SqlDscTraceFlag` command to ensure it functions
   correctly in real environments
   [issue #2214](https://github.com/dsccommunity/SqlServerDsc/issues/2214).
+- `Set-SqlDscAudit`
+  - Added `AllowAuditGuidChange` parameter to enable modifying the audit GUID
+    by dropping and recreating the audit with the new GUID. This parameter is
+    required when changing the `AuditGuid` property because SQL Server does not
+    allow direct modification of the audit GUID ([issue #2287](https://github.com/dsccommunity/SqlServerDsc/issues/2287)).
 
 ### Changed
 

source/Private/ConvertTo-AuditNewParameterSet.ps1

@@ -0,0 +1,144 @@
+<#
+    .SYNOPSIS
+        Converts audit object properties to parameters for New-SqlDscAudit.
+
+    .DESCRIPTION
+        This helper function analyzes an existing audit object and returns a hashtable
+        of parameters that can be splatted to New-SqlDscAudit to recreate the audit
+        with the same configuration.
+
+    .PARAMETER AuditObject
+        The audit object to analyze.
+
+    .PARAMETER AuditGuid
+        Optional GUID to set on the audit. If not specified, the existing GUID is used.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine
+        $auditObject = $serverObject.Audits['MyAudit']
+        $parameters = ConvertTo-AuditNewParameterSet -AuditObject $auditObject
+
+        Converts an existing audit object to a parameter set that can be used with New-SqlDscAudit.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine
+        $auditObject = $serverObject.Audits['MyAudit']
+        $parameters = ConvertTo-AuditNewParameterSet -AuditObject $auditObject -AuditGuid '12345678-1234-1234-1234-123456789012'
+
+        Converts an existing audit object to a parameter set with a custom GUID.
+
+    .INPUTS
+        None
+
+        This function does not accept pipeline input.
+
+    .OUTPUTS
+        System.Collections.Hashtable
+
+        Returns a hashtable of parameters for New-SqlDscAudit.
+#>
+function ConvertTo-AuditNewParameterSet
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.Audit]
+        $AuditObject,
+
+        [Parameter()]
+        [System.String]
+        $AuditGuid
+    )
+
+    $parameters = @{
+        ServerObject = $AuditObject.Parent
+        Name         = $AuditObject.Name
+    }
+
+    # Determine LogType or Path based on DestinationType
+    switch ($AuditObject.DestinationType)
+    {
+        'ApplicationLog'
+        {
+            $parameters['LogType'] = 'ApplicationLog'
+        }
+
+        'SecurityLog'
+        {
+            $parameters['LogType'] = 'SecurityLog'
+        }
+
+        'File'
+        {
+            $parameters['Path'] = $AuditObject.FilePath
+
+            # Add file size parameters if set (not unlimited)
+            if ($AuditObject.MaximumFileSize -gt 0)
+            {
+                $parameters['MaximumFileSize'] = $AuditObject.MaximumFileSize
+
+                # Convert SMO unit to parameter value
+                $parameters['MaximumFileSizeUnit'] = switch ($AuditObject.MaximumFileSizeUnit)
+                {
+                    'MB'
+                    {
+                        'Megabyte'
+                    }
+                    'GB'
+                    {
+                        'Gigabyte'
+                    }
+                    'TB'
+                    {
+                        'Terabyte'
+                    }
+                }
+            }
+
+            # Add MaximumFiles or MaximumRolloverFiles (mutually exclusive)
+            if ($AuditObject.MaximumFiles -gt 0)
+            {
+                $parameters['MaximumFiles'] = $AuditObject.MaximumFiles
+
+                if ($AuditObject.ReserveDiskSpace)
+                {
+                    $parameters['ReserveDiskSpace'] = $true
+                }
+            }
+            elseif ($AuditObject.MaximumRolloverFiles -gt 0)
+            {
+                $parameters['MaximumRolloverFiles'] = $AuditObject.MaximumRolloverFiles
+            }
+        }
+    }
+
+    # Add optional parameters if they have values
+    if ($null -ne $AuditObject.OnFailure)
+    {
+        $parameters['OnFailure'] = $AuditObject.OnFailure
+    }
+
+    if ($AuditObject.QueueDelay -gt 0)
+    {
+        $parameters['QueueDelay'] = $AuditObject.QueueDelay
+    }
+
+    if ($AuditObject.Filter)
+    {
+        $parameters['AuditFilter'] = $AuditObject.Filter
+    }
+
+    # Use provided GUID or existing GUID
+    if ($PSBoundParameters.ContainsKey('AuditGuid'))
+    {
+        $parameters['AuditGuid'] = $AuditGuid
+    }
+    elseif ($AuditObject.Guid -and $AuditObject.Guid -ne '00000000-0000-0000-0000-000000000000')
+    {
+        $parameters['AuditGuid'] = $AuditObject.Guid
+    }
+
+    return $parameters
+}