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,123 @@
+<#
+    .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.
+
+    .OUTPUTS
+        System.Collections.Hashtable
+#>
+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
+}

source/Public/Set-SqlDscAudit.ps1

@@ -32,6 +32,13 @@
         Specifies the GUID found in the mirrored database. To support scenarios such
         as database mirroring an audit needs a specific GUID.
 
+    .PARAMETER AllowAuditGuidChange
+        Specifies that the audit GUID can be changed by dropping and recreating the
+        audit. This parameter is required when modifying the AuditGuid property because
+        SQL Server does not allow direct modification of the audit GUID. When specified,
+        the audit will be dropped and recreated with all existing properties plus the
+        new GUID value. This is a destructive operation that requires explicit opt-in.
+
     .PARAMETER Force
         Specifies that the audit should be updated without any confirmation.
 
@@ -158,6 +165,10 @@ function Set-SqlDscAudit
         [System.String]
         $AuditGuid,
 
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $AllowAuditGuidChange,
+
         [Parameter()]
         [System.Management.Automation.SwitchParameter]
         $Force,
@@ -250,7 +261,7 @@ function Set-SqlDscAudit
             $ConfirmPreference = 'None'
         }
 
-        if ($PSCmdlet.ParameterSetName -eq 'ServerObject')
+        if ($PSCmdlet.ParameterSetName -match '^ServerObject')
         {
             $getSqlDscAuditParameters = @{
                 ServerObject = $ServerObject
@@ -277,79 +288,137 @@ function Set-SqlDscAudit
 
         if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
         {
-            if ($PSBoundParameters.ContainsKey('Path'))
-            {
-                $AuditObject.FilePath = $Path
-            }
-
-            if ($PSCmdlet.ParameterSetName -match 'WithSize')
+            # Check if GUID change is requested early, before any other modifications
+            if ($PSBoundParameters.ContainsKey('AuditGuid'))
             {
-                $queryMaximumFileSizeUnit = (
-                    @{
-                        Megabyte = 'MB'
-                        Gigabyte = 'GB'
-                        Terabyte = 'TB'
+                # Check if the GUID is actually changing
+                if ($AuditObject.Guid -ne $AuditGuid)
+                {
+                    # Validate that AllowAuditGuidChange is present
+                    if (-not $AllowAuditGuidChange.IsPresent)
+                    {
+                        $errorMessage = $script:localizedData.Audit_AuditGuidChangeRequiresAllowParameter -f $AuditObject.Name
+
+                        $PSCmdlet.ThrowTerminatingError(
+                            [System.Management.Automation.ErrorRecord]::new(
+                                $errorMessage,
+                                'SSDA0001', # cspell: disable-line
+                                [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                                $AuditObject.Name
+                            )
+                        )
                     }
-                ).$MaximumFileSizeUnit
 
-                $AuditObject.MaximumFileSize = $MaximumFileSize
-                $AuditObject.MaximumFileSizeUnit = $queryMaximumFileSizeUnit
-            }
+                    Write-Verbose -Message ($script:localizedData.Audit_RecreatingAuditForGuidChange -f $AuditObject.Name, $AuditObject.Parent.InstanceName, $AuditGuid)
 
-            if ($PSCmdlet.ParameterSetName -match 'MaxFiles')
-            {
-                if ($AuditObject.MaximumRolloverFiles)
-                {
-                    # Switching to MaximumFiles instead of MaximumRolloverFiles.
-                    $AuditObject.MaximumRolloverFiles = 0
+                    # Convert audit properties to parameters for New-SqlDscAudit
+                    $newAuditParameters = ConvertTo-AuditNewParameterSet -AuditObject $AuditObject -AuditGuid $AuditGuid
+
+                    # Drop the existing audit using Remove-SqlDscAudit
+                    # Use -Confirm:$false since we're already in a confirmed ShouldProcess context
+                    $AuditObject | Remove-SqlDscAudit -Confirm:$false
 
-                    # Must run method Alter() before setting MaximumFiles.
-                    $AuditObject.Alter()
+                    # Create new audit with the same properties using New-SqlDscAudit
+                    # Use -Confirm:$false and -PassThru since we're already in a confirmed context and need the object
+                    $AuditObject = New-SqlDscAudit @newAuditParameters -Confirm:$false -PassThru
+
+                    # Remove parameters that should not be passed to recursive call
+                    $null = $PSBoundParameters.Remove('AuditGuid')
+                    $null = $PSBoundParameters.Remove('AllowAuditGuidChange')
+                    $null = $PSBoundParameters.Remove('ServerObject')
+                    $null = $PSBoundParameters.Remove('Name')
+                    $null = $PSBoundParameters.Remove('Force')
+                    $null = $PSBoundParameters.Remove('Refresh')
+                    $null = $PSBoundParameters.Remove('PassThru')
+
+                    # Remove common parameters and get the resulting hashtable
+                    $remainingParameters = Remove-CommonParameter -Hashtable $PSBoundParameters
+
+                    # If there are other property-changing parameters to apply, recursively call Set-SqlDscAudit
+                    if ($remainingParameters.Count -gt 0)
+                    {
+                        # Add the new AuditObject parameter
+                        $remainingParameters['AuditObject'] = $AuditObject
+
+                        # Recursively call to apply remaining changes
+                        $AuditObject = Set-SqlDscAudit @remainingParameters -Confirm:$false -PassThru
+                    }
                 }
+            }
+            else
+            {
+                # No GUID change, proceed with normal property updates
 
-                $AuditObject.MaximumFiles = $MaximumFiles
+                # Apply other parameter changes
+                if ($PSBoundParameters.ContainsKey('Path'))
+                {
+                    $AuditObject.FilePath = $Path
+                }
 
-                if ($PSBoundParameters.ContainsKey('ReserveDiskSpace'))
+                if ($PSCmdlet.ParameterSetName -match 'WithSize')
                 {
-                    $AuditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent
+                    $queryMaximumFileSizeUnit = (
+                        @{
+                            Megabyte = 'MB'
+                            Gigabyte = 'GB'
+                            Terabyte = 'TB'
+                        }
+                    ).$MaximumFileSizeUnit
+
+                    $AuditObject.MaximumFileSize = $MaximumFileSize
+                    $AuditObject.MaximumFileSizeUnit = $queryMaximumFileSizeUnit
                 }
-            }
 
-            if ($PSCmdlet.ParameterSetName -match 'MaxRolloverFiles')
-            {
-                if ($AuditObject.MaximumFiles)
+                if ($PSCmdlet.ParameterSetName -match 'MaxFiles')
                 {
-                    # Switching to MaximumRolloverFiles instead of MaximumFiles.
-                    $AuditObject.MaximumFiles = 0
+                    if ($AuditObject.MaximumRolloverFiles)
+                    {
+                        # Switching to MaximumFiles instead of MaximumRolloverFiles.
+                        $AuditObject.MaximumRolloverFiles = 0
 
-                    # Must run method Alter() before setting MaximumRolloverFiles.
-                    $AuditObject.Alter()
+                        # Must run method Alter() before setting MaximumFiles.
+                        $AuditObject.Alter()
+                    }
+
+                    $AuditObject.MaximumFiles = $MaximumFiles
+
+                    if ($PSBoundParameters.ContainsKey('ReserveDiskSpace'))
+                    {
+                        $AuditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent
+                    }
                 }
 
-                $AuditObject.MaximumRolloverFiles = $MaximumRolloverFiles
-            }
+                if ($PSCmdlet.ParameterSetName -match 'MaxRolloverFiles')
+                {
+                    if ($AuditObject.MaximumFiles)
+                    {
+                        # Switching to MaximumRolloverFiles instead of MaximumFiles.
+                        $AuditObject.MaximumFiles = 0
 
-            if ($PSBoundParameters.ContainsKey('OnFailure'))
-            {
-                $AuditObject.OnFailure = $OnFailure
-            }
+                        # Must run method Alter() before setting MaximumRolloverFiles.
+                        $AuditObject.Alter()
+                    }
 
-            if ($PSBoundParameters.ContainsKey('QueueDelay'))
-            {
-                $AuditObject.QueueDelay = $QueueDelay
-            }
+                    $AuditObject.MaximumRolloverFiles = $MaximumRolloverFiles
+                }
 
-            if ($PSBoundParameters.ContainsKey('AuditGuid'))
-            {
-                $AuditObject.Guid = $AuditGuid
-            }
+                if ($PSBoundParameters.ContainsKey('OnFailure'))
+                {
+                    $AuditObject.OnFailure = $OnFailure
+                }
 
-            if ($PSBoundParameters.ContainsKey('AuditFilter'))
-            {
-                $AuditObject.Filter = $AuditFilter
-            }
+                if ($PSBoundParameters.ContainsKey('QueueDelay'))
+                {
+                    $AuditObject.QueueDelay = $QueueDelay
+                }
+
+                if ($PSBoundParameters.ContainsKey('AuditFilter'))
+                {
+                    $AuditObject.Filter = $AuditFilter
+                }
 
-            $AuditObject.Alter()
+                $AuditObject.Alter()
+            }
 
             if ($PassThru.IsPresent)
             {

source/en-US/SqlServerDsc.strings.psd1

@@ -84,6 +84,8 @@ ConvertFrom-StringData @'
     Audit_Update_ShouldProcessCaption = Update audit on instance
     Audit_MaximumFileSizeParameterValueInvalid = The maximum file size must be set to a value of 0 or a value between 2 and 2147483647.
     Audit_QueueDelayParameterValueInvalid = The queue delay must be set to a value of 0 or a value between 1000 and 2147483647.
+    Audit_AuditGuidChangeRequiresAllowParameter = Cannot modify the AuditGuid property of the audit '{0}'. SQL Server does not allow direct modification of the audit GUID. Use the parameter AllowAuditGuidChange to permit dropping and recreating the audit with the new GUID.
+    Audit_RecreatingAuditForGuidChange = Recreating the audit '{0}' on instance '{1}' to change the audit GUID to '{2}'.
 
     ## Get-SqlDscAudit
     Audit_Missing = There is no audit with the name '{0}'.