SqlServerDsc: Resources work with SqlServer v22.0.49-preview (#1808)

CHANGELOG.md

@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `ConvertTo-Reason`
     - `Get-ClassName`
     - `Get-LocalizedDataRecursive`
+  - Added documentation how to generate stub modules for the unit tests.
+    The documentation can be found in ['tests/Unit/Stubs`](https://github.com/dsccommunity/SqlServerDsc/tree/main/tests/Unit/Stubs).
 
 ### Added
 
@@ -73,6 +75,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Added compatibility levels for SQL Server 2022 (major version 16).
 - SqlSetup
   - Paths for SQL Server 2022 are correctly returned by Get.
+- SqlRS
+  - Added optional parameter `Encrypt`. Parameter `Encrypt` controls whether
+    the connection used by `Invoke-SqlCmd should enforce encryption. This
+    parameter can only be used together with the module _SqlServer_ v22.x
+    (minimum v22.0.49-preview). The parameter will be ignored if an older
+    major versions of the module _SqlServer_ is used.
+- SqlScript
+  - Added optional parameter `Encrypt`. Parameter `Encrypt` controls whether
+    the connection used by `Invoke-SqlCmd should enforce encryption. This
+    parameter can only be used together with the module _SqlServer_ v22.x
+    (minimum v22.0.49-preview). The parameter will be ignored if an older
+    major versions of the module _SqlServer_ is used.
+- SqlScriptQuery
+  - Added optional parameter `Encrypt`. Parameter `Encrypt` controls whether
+    the connection used by `Invoke-SqlCmd should enforce encryption. This
+    parameter can only be used together with the module _SqlServer_ v22.x
+    (minimum v22.0.49-preview). The parameter will be ignored if an older
+    major versions of the module _SqlServer_ is used.
 - The public commands `Add-SqlDscNode`, `Complete-SqlDscFailoverCluster`,
   `Complete-SqlDscImage`, `Install-SqlDscServer`, and `Repair-SqlDscServer`
   now support the setup argument `ProductCoveredBySA` ([issue #1798](https://github.com/dsccommunity/SqlServerDsc/issues/1798)).
@@ -90,6 +110,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     to be able to run all unit tests, and all tests run by the extension
     are now run in a separate process to be able to handle changes in
     class-based resources.
+  - The AppVeyor configuration file was updated to include the possibility
+    to run integration tests for SQL Server 2022.
+  - The stubs in `SqlServerStub.psm1` are now based on the commands from the
+    module SqlServer v22.0.49-preview.
 - `Install-SqlServerDsc`
   - No longer throws an exception when parameter `AgtSvcAccount` is not specified.
 - SqlAgReplica
@@ -106,6 +130,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Uninstall-SqlDscServer`
   - Was changed to support the SQL Server 2022 GA feature `AzureExtension`
     (that replaced the feature name `ARC`) ([issue #1798](https://github.com/dsccommunity/SqlServerDsc/issues/1798)).
+- SqlReplication
+  - The resource now supports SQL Server 2022. The resource will require
+    the module _SqlServer_ v22.0.49-preview or newer when used against an
+    SQL Server 2022 instance ([issue #1801](https://github.com/dsccommunity/SqlServerDsc/issues/1801)).
+- SqlProtocol
+  - The resource now supports SQL Server 2022. The resource will require
+    the module _SqlServer_ v22.0.49-preview or newer when used against an
+    SQL Server 2022 instance ([issue #1802](https://github.com/dsccommunity/SqlServerDsc/issues/1802)).
+- SqlProtocolTcpIp
+  - The resource now supports SQL Server 2022. The resource will require
+    the module _SqlServer_ v22.0.49-preview or newer when used against an
+    SQL Server 2022 instance ([issue #1805](https://github.com/dsccommunity/SqlServerDsc/issues/1805)).
+- SqlServiceAccount
+  - The resource now supports SQL Server 2022. The resource will require
+    the module _SqlServer_ v22.0.49-preview or newer when used against an
+    SQL Server 2022 instance ([issue #1800](https://github.com/dsccommunity/SqlServerDsc/issues/1800)).
+- SqlSetup
+  - Integration tests now used _SqlServer_ module version 22.0.49-preview
+    when running against _SQL Server 2022_, when testing _SQL Server 2016_,
+    _SQL Server 2017_, and _SQL Server 2019_ the module version 21.1.18256
+    is used.
+  - Integration tests now supports installing preview versions of the module
+    _SqlServer_.
+- SqlServerDsc.Common
+  - `Import-SQLPSModule`
+    - Small changed to the localized string verbose message when the preferred
+      module (_SqlServer_) is not found.
+  - `Invoke-SqlScript`
+    - Added the optional parameter `Encrypt` which controls whether the connection
+      used by `Invoke-SqlCmd` should enforce encryption. This parameter can
+      only be used together with the module _SqlServer_ v22.x (minimum
+      v22.0.49-preview). The parameter will be ignored if an older major
+      versions of the module _SqlServer_ is used.
 
 ### Fixed
 
@@ -326,7 +383,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SqlAlwaysOnService
   - BREAKING CHANGE: The parameter `IsHadrEnabled` is no longer returned by
     `Get-TargetResource`. The `Ensure` parameter now returns `Present` if
-    Always On HADR is enabled and `Absent` if it is disabled.
+    Always On High Availability Diaster Recovery is enabled and `Absent`
+    if it is disabled.
 - SqlDatabasePermission
   - BREAKING CHANGE: The resource has been refactored. The parameters
     `ParameterState` and `Permissions` has been replaced by parameters
@@ -443,8 +501,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `ConvertTo-Reason`
   - Fix to handle `$null` values on Windows PowerShell.
   - If the property name contain the word 'Path' the value will be parsed to
-    replace backslash or slashes at the end of the string, e.g. `'/mypath/'`
-    will become `'/mypath'`.
+    replace backslash or slashes at the end of the string, e.g. `'/myPath/'`
+    will become `'/myPath'`.
 - `ResourceBase`
   - Now handles `Ensure` correctly from derived `GetCurrentState()`. But
     requires that the `GetCurrentState()` only return key property if object

CONTRIBUTING.md

@@ -254,6 +254,18 @@ There are [stub classes](https://github.com/PowerShell/SqlServerDsc/blob/main/Te
 for the SMO classes which can be used and improved on when creating tests where
 SMO classes are used in the code being tested.
 
+#### Using stub modules
+
+There are [stub modules](https://github.com/PowerShell/SqlServerDsc/blob/main/Tests/Unit/Stubs)
+for the modules SQLPS and SqlServer. The stub modules should be used when
+writing unit test so that mocks have something to hook onto without the
+need to have the real modules installed.
+
+There is documentation how to generate the stub modules for the unit tests in
+['tests/Unit/Stubs`](https://github.com/dsccommunity/SqlServerDsc/tree/main/tests/Unit/Stubs).
+The stub modules only need to be updated when there is changes to the source
+module.
+
 ### Integration tests
 
 Integration tests should be written for resources so they can be validated by

RequiredModules.psd1

@@ -47,5 +47,4 @@
     PSDscResources                 = '2.12.0.0'
     StorageDsc                     = '4.9.0.0'
     NetworkingDsc                  = '7.4.0.0'
-    PowerShellGet                  = '2.1.2'
 }

appveyor.yml

@@ -21,6 +21,7 @@ environment:
   - TEST_CONFIGURATION: Integration_SQL2016
   - TEST_CONFIGURATION: Integration_SQL2017
   #- TEST_CONFIGURATION: Integration_SQL2019
+  #- TEST_CONFIGURATION: Integration_SQL2022
 
 # DEBUG: See section on_finish last in this file on how to block build to keep RDP open.
 # DEBUG: If running on own AppVeyor project, comment the line below that skips if it is not a pull request

source/DSCResources/DSC_SqlProtocol/README.md

@@ -25,6 +25,8 @@ For more information about protocol properties look at the following articles:
   not have access then the correct credential must be provided in
   the built-in parameter `PSDscRunAsCredential`. If not the following error
   can appear; `An internal error occurred`.
+* When using the resource against an SQL Server 2022 instance, the module
+  _SqlServer_ v22.0.49-preview or newer must be installed.
 
 ## Known issues
 

source/DSCResources/DSC_SqlProtocolTcpIp/README.md

@@ -20,6 +20,8 @@ For more information about static and dynamic ports read the article
   TcpIp protocol must also set the **Listen All** property to **No**.
   This can be done with the resource `SqlProtocol` using the
   parameter `ListenOnAllIpAddresses`.
+* When using the resource against an SQL Server 2022 instance, the module
+  _SqlServer_ v22.0.49-preview or newer must be installed.
 
 ## Known issues
 

source/DSCResources/DSC_SqlRS/DSC_SqlRS.psm1

@@ -18,6 +18,15 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
 
     .PARAMETER DatabaseInstanceName
         Name of the SQL Server instance to host the Reporting Service database.
+
+    .PARAMETER Encrypt
+        Specifies how encryption should be enforced when using command `Invoke-SqlCmd`.
+        When not specified, the default value is `Mandatory`.
+
+        This value maps to the Encrypt property SqlConnectionEncryptOption
+        on the SqlConnection object of the Microsoft.Data.SqlClient driver.
+
+        This parameter can only be used when the module SqlServer v22.x.x is installed.
 #>
 function Get-TargetResource
 {
@@ -36,7 +45,12 @@ function Get-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.String]
-        $DatabaseInstanceName
+        $DatabaseInstanceName,
+
+        [Parameter()]
+        [ValidateSet('Mandatory', 'Optional', 'Strict')]
+        [System.String]
+        $Encrypt
     )
 
     Write-Verbose -Message (
@@ -53,6 +67,7 @@ function Get-TargetResource
         ReportsReservedUrl           = $null
         UseSsl                       = $false
         IsInitialized                = $false
+        Encrypt                      = $Encrypt
     }
 
     $reportingServicesData = Get-ReportingServicesData -InstanceName $InstanceName
@@ -170,6 +185,15 @@ function Get-TargetResource
         settings change. If this parameter is set to $true, Reporting Services
         will not be restarted, even after initialization.
 
+    .PARAMETER Encrypt
+        Specifies how encryption should be enforced when using command `Invoke-SqlCmd`.
+        When not specified, the default value is `Mandatory`.
+
+        This value maps to the Encrypt property SqlConnectionEncryptOption
+        on the SqlConnection object of the Microsoft.Data.SqlClient driver.
+
+        This parameter can only be used when the module SqlServer v22.x.x is installed.
+
     .NOTES
         To find out the parameter names for the methods in the class
         MSReportServer_ConfigurationSetting it's easy to list them using the
@@ -247,7 +271,12 @@ function Set-TargetResource
 
         [Parameter()]
         [System.Boolean]
-        $SuppressRestart
+        $SuppressRestart,
+
+        [Parameter()]
+        [ValidateSet('Mandatory', 'Optional', 'Strict')]
+        [System.String]
+        $Encrypt
     )
 
     $reportingServicesData = Get-ReportingServicesData -InstanceName $InstanceName
@@ -443,8 +472,23 @@ function Set-TargetResource
                 current directory to SQLSERVER:\ on import.
             #>
             Import-SQLPSModule
-            Invoke-Sqlcmd -ServerInstance $reportingServicesConnection -Query $reportingServicesDatabaseScript.Script
-            Invoke-Sqlcmd -ServerInstance $reportingServicesConnection -Query $reportingServicesDatabaseRightsScript.Script
+
+            $invokeSqlCmdParameters = @{
+                ServerInstance = $reportingServicesConnection
+            }
+
+            if ($PSBoundParameters.ContainsKey('Encrypt'))
+            {
+                $commandInvokeSqlCmd = Get-Command -Name 'Invoke-SqlCmd'
+
+                if ($null -ne $commandInvokeSqlCmd -and $commandInvokeSqlCmd.Parameters.Keys -contains 'Encrypt')
+                {
+                    $invokeSqlCmdParameters.Encrypt = $Encrypt
+                }
+            }
+
+            Invoke-SqlCmd @invokeSqlCmdParameters -Query $reportingServicesDatabaseScript.Script
+            Invoke-SqlCmd @invokeSqlCmdParameters -Query $reportingServicesDatabaseRightsScript.Script
 
             Write-Verbose -Message "Set database connection on $DatabaseServerName\$DatabaseInstanceName to database '$reportingServicesDatabaseName'."
 
@@ -816,7 +860,16 @@ function Set-TargetResource
     .PARAMETER SuppressRestart
         Reporting Services need to be restarted after initialization or
         settings change. If this parameter is set to $true, Reporting Services
-        will not be restarted, even after initialisation.
+        will not be restarted, even after initialization.
+
+    .PARAMETER Encrypt
+        Specifies how encryption should be enforced when using command `Invoke-SqlCmd`.
+        When not specified, the default value is `Mandatory`.
+
+        This value maps to the Encrypt property SqlConnectionEncryptOption
+        on the SqlConnection object of the Microsoft.Data.SqlClient driver.
+
+        This parameter can only be used when the module SqlServer v22.x.x is installed.
 #>
 function Test-TargetResource
 {
@@ -859,7 +912,12 @@ function Test-TargetResource
 
         [Parameter()]
         [System.Boolean]
-        $SuppressRestart
+        $SuppressRestart,
+
+        [Parameter()]
+        [ValidateSet('Mandatory', 'Optional', 'Strict')]
+        [System.String]
+        $Encrypt
     )
 
     $result = $true
@@ -870,6 +928,11 @@ function Test-TargetResource
         DatabaseInstanceName = $DatabaseInstanceName
     }
 
+    if ($PSBoundParameters.ContainsKey('Encrypt'))
+    {
+        $getTargetResourceParameters.Encrypt = $Encrypt
+    }
+
     $currentConfig = Get-TargetResource @getTargetResourceParameters
 
     if (-not $currentConfig.IsInitialized)

source/DSCResources/DSC_SqlRS/DSC_SqlRS.schema.mof

@@ -10,5 +10,6 @@ class DSC_SqlRS : OMI_BaseResource
     [Write, Description("_Report Manager_ or _Report Web App_ URL reservations. Optional. If not specified, `'http://+:80'` URL reservation will be used.")] String ReportsReservedUrl[];
     [Write, Description("If connections to the _Reporting Services_ must use SSL. If this parameter is not assigned a value, the default is that _Reporting Services_ does not use SSL.")] Boolean UseSsl;
     [Write, Description("_Reporting Services_ need to be restarted after initialization or settings change. If this parameter is set to `$true`, _Reporting Services_ will not be restarted, even after initialization.")] Boolean SuppressRestart;
+    [Write, Description("Specifies how encryption should be enforced when using command `Invoke-SqlCmd`. When not specified, the default value is `Mandatory`."), ValueMap{"Mandatory","Optional","Strict"}, Values{"Mandatory","Optional","Strict"}] String Encrypt;
     [Read, Description("Returns if the _Reporting Services_ instance initialized or not.")] Boolean IsInitialized;
 };

source/DSCResources/DSC_SqlRS/README.md

@@ -13,6 +13,22 @@ server.
   specified credential must have permissions to connect to the SQL Server instance
   specified in `DatabaseServerName` and `DatabaseInstanceName`, and have permission
   to create the Reporting Services databases.
+* Parameter `Encrypt` controls whether the connection used by `Invoke-SqlCmd`
+  should enforce encryption. This parameter can only be used together with the
+  module _SqlServer_ v22.x (minimum v22.0.49-preview). The parameter will be
+  ignored if an older major versions of the module _SqlServer_ is used.
+  Encryption is mandatory by default, which generates the following exception
+  when the correct certificates are not present:
+
+  ```plaintext
+  A connection was successfully established with the server, but then
+  an error occurred during the login process. (provider: SSL Provider,
+  error: 0 - The certificate chain was issued by an authority that is
+  not trusted.)
+  ```
+
+  For more details, see the article [Connect to SQL Server with strict encryption](https://learn.microsoft.com/en-us/sql/relational-databases/security/networking/connect-with-strict-encryption?view=sql-server-ver16)
+  and [Configure SQL Server Database Engine for encrypting connections](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-sql-server-encryption?view=sql-server-ver16).
 
 ## Known issues
 
@@ -24,17 +40,23 @@ All issues are not listed here, see [here for all open issues](https://github.co
 
 ## Known error messages
 
-### Error: The parameter is incorrect (HRESULT:-2147024809)
+### Error: `The parameter is incorrect (HRESULT:-2147024809)`
 
 This is caused by trying to add an URL with the wrong format
 i.e. 'htp://+:80'.
 
-### Error: The Url has already been reserved (HRESULT:-2147220932)
+### Error: `The Url has already been reserved (HRESULT:-2147220932)`
 
 This is caused when the URL is already reserved. For example when 'http://+:80'
 already exist.
 
-### Error: Cannot create a file when that file already exists (HRESULT:-2147024713)
+### Error: `Cannot create a file when that file already exists (HRESULT:-2147024713)`
 
 This is caused when trying to add another URL using the same protocol. For example
 when trying to add 'http://+:443' when 'http://+:80' already exist.
+
+### Error: `A connection was successfully established with the server, but then an error occurred during the login process`
+
+This is cause by encryption certificates are not correctly configured. Configure
+the certificates so that encryption works, or turn off the need of encryption
+by setting `Encrypt` to `Optional` (not recommended).