Updated Set-RsDatabase and Set-RsDatabaseCredentials scripts to support new parameters of Invoke-Sqlcmd.

[wrthmn]

Motivation:

Set-RsDatabase script started to result in failure with the following error:

Executing database creation script... Failed!
Invoke-Sqlcmd : 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.)

After investigation, I discovered that this behavior is a result of the recent update of SQL Strict Connection Encryption, which introduced some changes to the defaults of SQL connection encryption.

Since v22, Invoke-Sqlcmd cmdlet from PowerShell SqlServer module has three new parameters:

• -Encrypt;
• -TrustServerCertificate;
• -HostNameInCertificate.

According to the documentation on Invoke-Sqlcmd cmdlet, the default value for -Encrypt parameter is now Mandatory, which seems to be the reason of the connection failure, since currently no value for -Encrypt parameter is specified for Invoke-Sqlcmd invocation in Set-RsDatabase script.

Previously the encryption of the connection depended on -EncryptConnection switch of Invoke-Sqlcmd cmdlet, which was not specified in the script and is considered deprecated since v22 of SqlServer module.

So, basically, if the user has the SqlServer module v22 or higher installed, the Set-RsDatabase/Set-RsDatabaseCredentials script uses the recently updated version of Invoke-Sqlcmd cmdlet, which makes the connection Mandatory encrypted by default.

I consider the ability to specify the newly introduced parameters a required improvment for Set-RsDatabase and Set-RsDatabaseCredentials scripts functionality.

Changes proposed in this pull request:

• Added new parameters to Set-RsDatabase and Set-RsDatabaseCredentials scripts according to updated Invoke-Sqlcmd parameters:

  • -Encrypt;
  • -TrustServerCertificate;
  • -HostNameInCertificate.

• Refactored parameters specification for Invoke-Sqlcmd invocation.

• I also tried to ensure compatibility of the modified scripts with different versions of Invoke-Sqlcmd cmdlet, since it is present in SqlServer , PsSqlLegacy and SQLPS modules:

  • If user doesn't have SqlServer module v22 or higher installed and no recently introduced parameters were specified, the behavior of the scripts will not be affected by these changes and the connection will not be encrypted (as before);
  • If the user has SqlServer module v22 or higher installed, PowerShell will most likely use the latest version of Invoke-Sqlcmd cmdlet from this module, and user will have to specify the recently introduced parameters to prevent the default encryption of the connection (-Encrypt=Optional and -TrustServerCertificate is advised);
  • If no installed SqlServer module v22 or higher was found, but the recently introduced parameters were specified, the user will receive an error, suggesting them to install the SqlServer module v22 or higher required for these parameters support.

How to test this code:

• Import the updated module, as described in ReadMe ("Local testing and development");
• Manually execute Set-RsDatabase/Set-RsDatabaseCredentials script in different environments (various versions of SqlServer and other modules installed/removed);
• Ensure that scripts and parameters work as described.

Has been tested on:

• PowerShell 5.1
• PowerShell modules:
  • SqlServer 21.1.18256
  • SqlServer 22.0.59
  • SQLPS 15.0
  • SQLPS 16.0
• SQL Server 2019
• SQL Server 2022
• Windows 11 Enterprise

[wrthmn]

@wrthmn please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree company="Akvelon"

[jtarquino]

this code is duplicated twice in this cmdlet consider moving up so its only done once

[wrthmn]

Moved Invoke-Sqlcmd general parameters composition to a separated region.

[jtarquino]

please enhance the comment mentioning what need to support it

If supported by?

[wrthmn]

By "If supported" I meant having the required version of SQLServer PowerShell module installed to use this parameter (as mentioned on the next line) .
Tried to make the comment more comprehensible and added IMPORTANT: warning, since the default value of this parameter is the most significant change in the Invoke-Sqlcmd (as well as the related scripts) behavior.