SqlSetup: Add better validation of features (#1911)

- New public command: - `Test-SqlDscIsSupportedFeature` - Evaluates if a feature is supported by a specific Microsoft SQL Server major version. _This command must be extended with_ _a full list of when features were added and removed in each major_ _version to fully work_. - New private commands: - `Get-FileVersionInformation` - Returns the version information for a file. - `Assert-Feature` - Throws an exception if a feature is not supported for a specific Microsoft SQL Server major version. - Update private command: - `Assert-SetupActionProperties` was changed to throw an exception when a feature is not supported (uses `Assert-Feature`). The private function indirectly used by the setup action commands. - SqlSetup - Update to support checking non-supported features using the command `SqlDscIsSupportedFeature` ([issue #1872).
dsccommunity · Apr 16, 2023 · a7366c2 · a7366c2
1 parent 2ea2c07
commit a7366c2
Show file tree

Hide file tree

Showing 13 changed files with 731 additions and 13 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,12 +14,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - SqlServerDsc
-  - New public command:
+  - New public commands:
     - `Disconnect-SqlDscDatabaseEngine` - Disconnects from a SQL Server instance
       that was previously connected to using `Connect-SqlDscDatabaseEngine`.
-  - New private command:
+    - `Test-SqlDscIsSupportedFeature` - Evaluates if a feature is supported by a specific
+      Microsoft SQL Server major version. _This command must be extended with_
+      _a full list of when features were added and removed in each major_
+      _version to fully work_.
+  - New private commands:
     - `ConvertTo-RedactedText` - Used to redact sensitive information from
       text that then can be used in console output like verbose messages.
+    - `Get-FileVersionInformation` - Returns the version information
+      for a file.
+    - `Assert-Feature` - Throws an exception if a feature is not supported
+      for a specific Microsoft SQL Server major version.
+
+### Changed
+
+- Private functions:
+  - `Assert-SetupActionProperties` was changed to throw
+    an exception when a feature is not supported (uses `Assert-Feature`).
+    The private function indirectly used by the setup action commands.
+- SqlSetup
+  - Update to support checking non-supported features using the command
+    `SqlDscIsSupportedFeature` ([issue #1872](https://github.com/dsccommunity/SqlServerDsc/issues/1872)).
 
 ## [16.2.0] - 2023-04-10
 

diff --git a/source/DSCResources/DSC_SqlSetup/DSC_SqlSetup.psm1 b/source/DSCResources/DSC_SqlSetup/DSC_SqlSetup.psm1
@@ -1022,7 +1022,7 @@ function Set-TargetResource
 
     foreach ($feature in $featuresArray)
     {
-        if (($sqlVersion -in ('13', '14', '15', '16')) -and ($feature -in ('ADV_SSMS', 'SSMS')))
+        if (-not ($feature | Test-SqlDscIsSupportedFeature -ProductVersion $sqlVersion))
         {
             $errorMessage = $script:localizedData.FeatureNotSupported -f $feature
             New-InvalidOperationException -Message $errorMessage

diff --git a/source/Modules/SqlServerDsc.Common/SqlServerDsc.Common.psm1 b/source/Modules/SqlServerDsc.Common/SqlServerDsc.Common.psm1
@@ -2218,6 +2218,10 @@ function ConvertTo-ServerInstanceName
 
     .PARAMETER Path
         String containing the path to the SQL Server setup.exe executable.
+
+    .NOTES
+        This function should be removed when it is not longer used, and instead
+        the private function Get-FileVersionInformation shall be used.
 #>
 function Get-FilePathMajorVersion
 {

diff --git a/source/Private/Assert-Feature.ps1 b/source/Private/Assert-Feature.ps1
@@ -0,0 +1,54 @@
+<#
+    .SYNOPSIS
+        Assert that a feature is supported by a Microsoft SQL Server major version.
+
+    .DESCRIPTION
+        Assert that a feature is supported by a Microsoft SQL Server major version.
+
+    .PARAMETER Feature
+       Specifies the feature to evaluate.
+
+    .PARAMETER ProductVersion
+       Specifies the product version of the Microsoft SQL Server. At minimum the
+       major version must be provided.
+
+    .EXAMPLE
+        Assert-Feature -Feature 'RS' -ProductVersion '14'
+
+        Throws an exception if the feature is not supported.
+
+    .OUTPUTS
+        None.
+#>
+function Assert-Feature
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [System.String[]]
+        $Feature,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ProductVersion
+    )
+
+    process
+    {
+        foreach ($currentFeature in $Feature)
+        {
+            if (-not ($currentFeature | Test-SqlDscIsSupportedFeature -ProductVersion $ProductVersion))
+            {
+                $PSCmdlet.ThrowTerminatingError(
+                    [System.Management.Automation.ErrorRecord]::new(
+                        ($script:localizedData.Feature_Assert_NotSupportedFeature -f $currentFeature, $ProductVersion),
+                        'AF0001', # cSpell: disable-line
+                        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                        $currentFeature
+                    )
+                )
+            }
+        }
+    }
+}
diff --git a/source/Private/Assert-SetupActionProperties.ps1 b/source/Private/Assert-SetupActionProperties.ps1
@@ -39,6 +39,16 @@ function Assert-SetupActionProperties
         $SetupAction
     )
 
+    if ($Property.ContainsKey('Features'))
+    {
+        $setupExecutableFileVersion = $Property.MediaPath |
+            Join-Path -ChildPath 'setup.exe' |
+            Get-FileVersionInformation
+
+        $Property.Features |
+            Assert-Feature -ProductVersion $setupExecutableFileVersion.ProductVersion
+    }
+
     # If one of the properties PBStartPortRange and PBEndPortRange are specified, then both must be specified.
     $assertParameters = @('PBStartPortRange', 'PBEndPortRange')
 

diff --git a/source/Private/Get-FileVersionInformation.ps1 b/source/Private/Get-FileVersionInformation.ps1
@@ -0,0 +1,53 @@
+<#
+    .SYNOPSIS
+        Returns the version information for a file.
+
+    .DESCRIPTION
+        Returns the version information for a file.
+
+    .PARAMETER FilePath
+        Specifies the file for which to return the version information.
+
+    .EXAMPLE
+        Get-FileVersionInformation -FilePath 'E:\setup.exe'
+
+        Returns the version information for the file setup.exe.
+
+    .EXAMPLE
+        Get-FileVersionInformation -FilePath (Get-Item -Path 'E:\setup.exe')
+
+        Returns the version information for the file setup.exe.
+
+    .OUTPUTS
+        [System.String]
+#>
+function Get-FileVersionInformation
+{
+    [OutputType([System.Diagnostics.FileVersionInfo])]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [System.IO.FileInfo]
+        $FilePath
+    )
+
+    process
+    {
+        $file = Get-Item -Path $FilePath -ErrorAction 'Stop'
+
+        if ($file.PSIsContainer)
+        {
+            $PSCmdlet.ThrowTerminatingError(
+                [System.Management.Automation.ErrorRecord]::new(
+                    $script:localizedData.FileVersionInformation_Get_FilePathIsNotFile,
+                    'GFPVI0001', # cSpell: disable-line
+                    [System.Management.Automation.ErrorCategory]::InvalidArgument,
+                    $file.FullName
+                )
+            )
+        }
+
+        return $file.VersionInfo
+    }
+}
diff --git a/source/Public/Test-SqlDscIsSupportedFeature.ps1 b/source/Public/Test-SqlDscIsSupportedFeature.ps1
@@ -0,0 +1,99 @@
+<#
+    .SYNOPSIS
+        Tests that a feature is supported by a Microsoft SQL Server major version.
+
+    .DESCRIPTION
+        Tests that a feature is supported by a Microsoft SQL Server major version.
+
+    .PARAMETER Feature
+       Specifies the feature to evaluate.
+
+    .PARAMETER ProductVersion
+       Specifies the product version of the Microsoft SQL Server. At minimum the
+       major version must be provided.
+
+    .EXAMPLE
+        Test-SqlDscIsSupportedFeature -Feature 'RS' -ProductVersion '13'
+
+        Returns $true if the feature is supported.
+
+    .OUTPUTS
+        [System.Boolean]
+#>
+function Test-SqlDscIsSupportedFeature
+{
+    [OutputType([System.Boolean])]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [System.String]
+        $Feature,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ProductVersion
+    )
+
+    begin
+    {
+        $targetMajorVersion = ($ProductVersion -split '\.')[0]
+
+        <#
+            List of features that was removed from a specific major version (and later).
+            Feature list: https://learn.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt#Feature
+        #>
+        $removedFeaturesPerMajorVersion = @{
+            13 = @('ADV_SSMS', 'SSMS') # cSpell: disable-line
+            14 = @('RS', 'RS_SHP', 'RS_SHPWFE') # cSpell: disable-line
+            16 = @('Tools', 'BC', 'CONN', 'BC', 'DREPLAY_CTLR', 'DREPLAY_CLT', 'SNAC_SDK', 'SDK', 'PolyBaseJava', 'SQL_INST_MR', 'SQL_INST_MPY', 'SQL_SHARED_MPY', 'SQL_SHARED_MR') # cSpell: disable-line
+        }
+
+        <#
+            List of features that was added to a specific major version.
+            Feature list: https://learn.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt#Feature
+        #>
+        $addedFeaturesPerMajorVersion = @{
+            13 = @('SQL_INST_MR', 'SQL_INST_MPY', 'SQL_INST_JAVA')
+            15 = @('PolyBaseCore', 'PolyBaseJava', 'SQL_INST_JAVA') # cSpell: disable-line
+        }
+
+        # Evaluate features that was removed and are unsupported for the target's major version.
+        $targetUnsupportedFeatures = $removedFeaturesPerMajorVersion.Keys |
+            Where-Object -FilterScript {
+                $_ -le $targetMajorVersion
+            } |
+            ForEach-Object -Process {
+                $removedFeaturesPerMajorVersion.$_
+            }
+
+        <#
+            Evaluate features that was added to higher major versions than the
+            target's major version which will be unsupported for the target's
+            major version.
+        #>
+        $targetUnsupportedFeatures += $addedFeaturesPerMajorVersion.Keys |
+            Where-Object -FilterScript {
+                $_ -gt $targetMajorVersion
+            } |
+            ForEach-Object -Process {
+                $addedFeaturesPerMajorVersion.$_
+            }
+
+        $supported = $true
+    }
+
+    process
+    {
+        # This does case-insensitive match against the list of unsupported features.
+        if ($targetUnsupportedFeatures -and $Feature -in $targetUnsupportedFeatures)
+        {
+            $supported = $false
+        }
+    }
+
+    end
+    {
+        return $supported
+    }
+}
diff --git a/source/en-US/SqlServerDsc.strings.psd1 b/source/en-US/SqlServerDsc.strings.psd1
@@ -172,4 +172,10 @@ ConvertFrom-StringData @'
     DatabaseEngine_Disconnect_ShouldProcessVerboseWarning = Are you sure you want to disconnect from the instance '{0}'?
     # This string shall not end with full stop (.) since it is used as a title of ShouldProcess messages.
     DatabaseEngine_Disconnect_ShouldProcessCaption = Disconnect from instance
+
+    ## Assert-Feature
+    Feature_Assert_NotSupportedFeature = The feature '{0}' is not supported for Microsoft SQL Server product version {1}. See the Microsoft SQL Server documentation https://learn.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt#Feature for more information.
+
+    ## Get-FileVersionInformation
+    FileVersionInformation_Get_FilePathIsNotFile = The specified path is not a file.
 '@