Connect-SQL: Returns clear error message when status is not Online

CHANGELOG.md

@@ -168,6 +168,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `Connect-SQL`
     - Was updated to handle both `-ErrorAction 'Stop'` and `-ErrorAction 'SilentlyContinue'`
       when passed to the command ([issue #1837](https://github.com/dsccommunity/SqlServerDsc/issues/1837)).
+    - Now returns a more clear error message when the status of a database
+      instance is not `Online`.
 
 ### Fixed
 

source/Modules/SqlServerDsc.Common/SqlServerDsc.Common.psm1

@@ -553,7 +553,15 @@ function Connect-SQL
     {
         $sqlConnectionContext.Connect()
 
-        if ($sqlServerObject.Status -match '^Online$')
+        $instanceStatus = $sqlServerObject.Status
+
+        if ($instanceStatus)
+        {
+            # Property Status is of type Enum ServerStatus, we return the string equivalent.
+            $instanceStatus = $instanceStatus.ToString()
+        }
+
+        if ($instanceStatus -match '^Online$')
         {
             Write-Verbose -Message (
                 $script:localizedData.ConnectedToDatabaseEngineInstance -f $databaseEngineInstance
@@ -563,7 +571,31 @@ function Connect-SQL
         }
         else
         {
-            throw
+            if ([System.String]::IsNullOrEmpty($instanceStatus))
+            {
+                $instanceStatus = 'Unknown'
+            }
+
+            $errorMessage = $script:localizedData.DatabaseEngineInstanceNotOnline -f @(
+                $databaseEngineInstance,
+                $instanceStatus
+            )
+
+            $invalidOperationException = New-Object -TypeName 'InvalidOperationException' -ArgumentList @($errorMessage)
+
+            $newObjectParameters = @{
+                TypeName     = 'System.Management.Automation.ErrorRecord'
+                ArgumentList = @(
+                    $invalidOperationException.ToString(),
+                    'CS0001',
+                    'InvalidOperation',
+                    $databaseEngineInstance
+                )
+            }
+
+            $errorRecordToThrow = New-Object @newObjectParameters
+
+            Write-Error -ErrorRecord $errorRecordToThrow
         }
     }
     catch
@@ -576,7 +608,7 @@ function Connect-SQL
             TypeName     = 'System.Management.Automation.ErrorRecord'
             ArgumentList = @(
                 $invalidOperationException.ToString(),
-                'CS0001',
+                'CS0002',
                 'InvalidOperation',
                 $databaseEngineInstance
             )

source/Modules/SqlServerDsc.Common/en-US/SqlServerDsc.Common.strings.psd1

@@ -56,4 +56,5 @@ ConvertFrom-StringData @'
     LoadedAssembly = Loaded the assembly '{0}'. (SQLCOMMON0068)
     FailedToLoadAssembly = Failed to load the assembly '{0}'. (SQLCOMMON0069)
     FailedToObtainServerInstance = Failed to obtain a SQL Server instance with name '{0}' on server '{1}'. Ensure the SQL Server instance exists on the server and that the 'SQLServer' module references a version of the 'Microsoft.SqlServer.Management.Smo.Wmi' library that supports the version of the SQL Server instance. (SQLCOMMON0070)
+    DatabaseEngineInstanceNotOnline = The SQL instance '{0}' was expected to have the status 'Online', but had status '{1}'. (SQLCOMMON0071)
 '@

source/Modules/SqlServerDsc.Common/sv-SE/SqlServerDsc.Common.strings.psd1

@@ -62,4 +62,5 @@ ConvertFrom-StringData @'
     LoadedAssembly = Loaded the assembly '{0}'. (SQLCOMMON0068)
     FailedToLoadAssembly = Failed to load the assembly '{0}'. (SQLCOMMON0069)
     FailedToObtainServerInstance = Failed to obtain a SQL Server instance with name '{0}' on server '{1}'. Ensure the SQL Server instance exists on the server and that the 'SQLServer' module references a version of the 'Microsoft.SqlServer.Management.Smo.Wmi' library that supports the version of the SQL Server instance. (SQLCOMMON0070)
+    DatabaseEngineInstanceNotOnline = The SQL instance '{0}' was expected to have the status 'Online', but had status '{1}'. (SQLCOMMON0071)
 '@