Set-SqlDscDatabaseDefaultFullTextCatalog: add new command

CHANGELOG.md

@@ -36,6 +36,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   isolation for a database in a SQL Server Database Engine instance. This command
   uses the SMO `SetSnapshotIsolation()` method to disable row-versioning and snapshot
   isolation settings ([issue #2329](https://github.com/dsccommunity/SqlServerDsc/issues/2329)).
+- Added public command `Set-SqlDscDatabaseDefaultFullTextCatalog` to set the default
+  full-text catalog for a database in a SQL Server Database Engine instance. This
+  command uses the SMO `SetDefaultFullTextCatalog()` method to configure the default
+  catalog ([issue #2330](https://github.com/dsccommunity/SqlServerDsc/issues/2330)).
 - Added public command `New-SqlDscDatabaseSnapshot` to create database snapshots
   in a SQL Server Database Engine instance using SMO. This command provides an
   automated and DSC-friendly approach to snapshot management by leveraging

azure-pipelines.yml

@@ -344,6 +344,7 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscCompatibilityLevel.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabaseProperty.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabaseOwner.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Set-SqlDscDatabaseDefaultFullTextCatalog.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscIsDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscDatabaseProperty.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscDatabasePermission.Integration.Tests.ps1'

source/Public/Set-SqlDscDatabaseDefaultFullTextCatalog.ps1

@@ -0,0 +1,187 @@
+<#
+    .SYNOPSIS
+        Sets the default full-text catalog for a database in a SQL Server Database Engine instance.
+
+    .DESCRIPTION
+        This command sets the default full-text catalog for a database in a SQL Server
+        Database Engine instance. The catalog name must be a valid full-text catalog
+        that exists in the database. The command uses the SetDefaultFullTextCatalog()
+        method on the SMO Database object to set the default catalog.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER Name
+        Specifies the name of the database to modify.
+
+    .PARAMETER DatabaseObject
+        Specifies the database object to modify (from Get-SqlDscDatabase).
+
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s databases should be refreshed before
+        trying to get the database object. This is helpful when databases could have been
+        modified outside of the **ServerObject**, for example through T-SQL. But
+        on instances with a large amount of databases it might be better to make
+        sure the **ServerObject** is recent enough.
+
+        This parameter is only used when setting the default full-text catalog using
+        **ServerObject** and **Name** parameters.
+
+    .PARAMETER CatalogName
+        Specifies the name of the full-text catalog to set as the default for the database.
+
+    .PARAMETER Force
+        Specifies that the default full-text catalog should be modified without any confirmation.
+
+    .PARAMETER PassThru
+        Specifies that the database object should be returned after modification.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        Set-SqlDscDatabaseDefaultFullTextCatalog -ServerObject $serverObject -Name 'MyDatabase' -CatalogName 'MyCatalog'
+
+        Sets the default full-text catalog of the database named **MyDatabase** to **MyCatalog**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $databaseObject = $serverObject | Get-SqlDscDatabase -Name 'MyDatabase'
+        Set-SqlDscDatabaseDefaultFullTextCatalog -DatabaseObject $databaseObject -CatalogName 'MyCatalog' -Force
+
+        Sets the default full-text catalog using a database object without prompting for confirmation.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        Set-SqlDscDatabaseDefaultFullTextCatalog -ServerObject $serverObject -Name 'MyDatabase' -CatalogName 'MyCatalog' -PassThru
+
+        Sets the default full-text catalog and returns the updated database object.
+
+    .EXAMPLE
+        $databaseObject | Set-SqlDscDatabaseDefaultFullTextCatalog -CatalogName 'MyCatalog'
+
+        Sets the default full-text catalog using pipeline input.
+
+    .INPUTS
+        Microsoft.SqlServer.Management.Smo.Database
+
+        The database object to modify (from Get-SqlDscDatabase).
+
+    .OUTPUTS
+        None.
+
+        When PassThru is specified the output is [Microsoft.SqlServer.Management.Smo.Database].
+#>
+function Set-SqlDscDatabaseDefaultFullTextCatalog
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues.')]
+    [OutputType()]
+    [OutputType([Microsoft.SqlServer.Management.Smo.Database])]
+    [CmdletBinding(DefaultParameterSetName = 'ServerObjectSet', SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
+    param
+    (
+        [Parameter(ParameterSetName = 'ServerObjectSet', Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(ParameterSetName = 'ServerObjectSet', Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Name,
+
+        [Parameter(ParameterSetName = 'ServerObjectSet')]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh,
+
+        [Parameter(ParameterSetName = 'DatabaseObjectSet', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Database]
+        $DatabaseObject,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $CatalogName,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Force,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru
+    )
+
+    begin
+    {
+        if ($Force.IsPresent -and -not $Confirm)
+        {
+            $ConfirmPreference = 'None'
+        }
+    }
+
+    process
+    {
+        # Get the database object based on the parameter set
+        switch ($PSCmdlet.ParameterSetName)
+        {
+            'ServerObjectSet'
+            {
+                $previousErrorActionPreference = $ErrorActionPreference
+                $ErrorActionPreference = 'Stop'
+
+                $sqlDatabaseObject = $ServerObject |
+                    Get-SqlDscDatabase -Name $Name -Refresh:($Refresh.IsPresent) -ErrorAction 'Stop'
+
+                $ErrorActionPreference = $previousErrorActionPreference
+            }
+
+            'DatabaseObjectSet'
+            {
+                $sqlDatabaseObject = $DatabaseObject
+            }
+        }
+
+        $verboseDescriptionMessage = $script:localizedData.DatabaseDefaultFullTextCatalog_Set_ShouldProcessVerboseDescription -f $sqlDatabaseObject.Name, $CatalogName, $sqlDatabaseObject.Parent.InstanceName
+        $verboseWarningMessage = $script:localizedData.DatabaseDefaultFullTextCatalog_Set_ShouldProcessVerboseWarning -f $sqlDatabaseObject.Name, $CatalogName
+        $captionMessage = $script:localizedData.DatabaseDefaultFullTextCatalog_Set_ShouldProcessCaption
+
+        if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
+        {
+            # Check if the default full-text catalog is already correct (idempotence)
+            if ($sqlDatabaseObject.DefaultFullTextCatalog -eq $CatalogName)
+            {
+                Write-Debug -Message ($script:localizedData.DatabaseDefaultFullTextCatalog_AlreadyCorrect -f $sqlDatabaseObject.Name, $CatalogName)
+            }
+            else
+            {
+                Write-Debug -Message ($script:localizedData.DatabaseDefaultFullTextCatalog_Updating -f $sqlDatabaseObject.Name, $CatalogName)
+
+                try
+                {
+                    $sqlDatabaseObject.SetDefaultFullTextCatalog($CatalogName)
+                }
+                catch
+                {
+                    $errorMessage = $script:localizedData.DatabaseDefaultFullTextCatalog_SetFailed -f $sqlDatabaseObject.Name, $CatalogName
+
+                    $PSCmdlet.ThrowTerminatingError(
+                        [System.Management.Automation.ErrorRecord]::new(
+                            [System.InvalidOperationException]::new($errorMessage, $_.Exception),
+                            'SSDDF0004', # cspell: disable-line
+                            [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                            $sqlDatabaseObject
+                        )
+                    )
+                }
+
+                Write-Debug -Message ($script:localizedData.DatabaseDefaultFullTextCatalog_Updated -f $sqlDatabaseObject.Name, $CatalogName)
+            }
+
+            if ($PassThru.IsPresent)
+            {
+                # Refresh the database object to get the updated DefaultFullTextCatalog value from the server
+                $sqlDatabaseObject.Refresh()
+
+                return $sqlDatabaseObject
+            }
+        }
+    }
+}

source/en-US/SqlServerDsc.strings.psd1

@@ -422,6 +422,16 @@ ConvertFrom-StringData @'
     # This string shall not end with full stop (.) since it is used as a title of ShouldProcess messages.
     DatabaseOwner_Set_ShouldProcessCaption = Set database owner on instance
 
+    ## Set-SqlDscDatabaseDefaultFullTextCatalog
+    DatabaseDefaultFullTextCatalog_Updating = Setting default full-text catalog of database '{0}' to '{1}'. (SSDDF0001)
+    DatabaseDefaultFullTextCatalog_Updated = Default full-text catalog of database '{0}' was set to '{1}'. (SSDDF0002)
+    DatabaseDefaultFullTextCatalog_AlreadyCorrect = Default full-text catalog of database '{0}' is already set to '{1}'. (SSDDF0003)
+    DatabaseDefaultFullTextCatalog_SetFailed = Failed to set default full-text catalog of database '{0}' to '{1}'. (SSDDF0004)
+    DatabaseDefaultFullTextCatalog_Set_ShouldProcessVerboseDescription = Setting the default full-text catalog of the database '{0}' to '{1}' on the instance '{2}'.
+    DatabaseDefaultFullTextCatalog_Set_ShouldProcessVerboseWarning = Are you sure you want to change the default full-text catalog of the database '{0}' to '{1}'?
+    # This string shall not end with full stop (.) since it is used as a title of ShouldProcess messages.
+    DatabaseDefaultFullTextCatalog_Set_ShouldProcessCaption = Set database default full-text catalog on instance
+
     ## Enable-SqlDscDatabaseSnapshotIsolation
     DatabaseSnapshotIsolation_Enabling = Enabling snapshot isolation for database '{0}'. (ESDSI0002)
     DatabaseSnapshotIsolation_Enabled = Snapshot isolation for database '{0}' was enabled. (ESDSI0003)

tests/Integration/Commands/README.md

@@ -95,6 +95,7 @@ New-SqlDscDatabaseSnapshot | 5 | 4 (New-SqlDscDatabase), 1 (Install-SqlDscServer
 Get-SqlDscCompatibilityLevel | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Set-SqlDscDatabaseProperty | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Set-SqlDscDatabaseOwner | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
+Set-SqlDscDatabaseDefaultFullTextCatalog | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Test-SqlDscIsDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Test-SqlDscDatabaseProperty | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Get-SqlDscDatabasePermission | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | Test database, Test user