SqlServerDsc: Using dbatools as a preferred module (#1904)

CHANGELOG.md

@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Now able to use [DbaTools](https://dbatools.io) as a preferred module
+  (with some restrictions).
 - Gitversion no longer evaluates bumping major version using the word "major".
 - Update private commands:
   - `Assert-SetupActionProperties` was changed to throw

azure-pipelines.yml

@@ -19,7 +19,7 @@ variables:
   sourceFolderName: source
   defaultBranch: main
 
-# cSpell: ignore setvariable updatebuildnumber DSCSQLTEST hqrmtest quickconfig
+# cSpell: ignore setvariable updatebuildnumber DSCSQLTEST hqrmtest quickconfig dbatools
 stages:
   - stage: Build
     jobs:
@@ -172,6 +172,8 @@ stages:
         pool:
           vmImage: $(JOB_VMIMAGE)
         timeoutInMinutes: 0
+        variables:
+          SMODefaultModuleName: 'SqlServer'
         steps:
           - task: DownloadPipelineArtifact@2
             displayName: 'Download Build Artifact'
@@ -239,6 +241,96 @@ stages:
               testResultsFiles: '$(buildFolderName)/$(testResultFolderName)/NUnit*.xml'
               testRunTitle: 'Integration ($(TEST_CONFIGURATION) / $(JOB_VMIMAGE))'
 
+      - job: Test_Integration_dbatools
+        displayName: 'Integration (dbatools)'
+        dependsOn: Test_Integration
+        strategy:
+          matrix:
+            SQL2016_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2016'
+            SQL2017_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2017'
+            SQL2019_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2019'
+            SQL2022_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2022'
+        pool:
+          vmImage: $(JOB_VMIMAGE)
+        timeoutInMinutes: 0
+        variables:
+          SMODefaultModuleName: 'dbatools'
+        steps:
+          - task: DownloadPipelineArtifact@2
+            displayName: 'Download Build Artifact'
+            inputs:
+              buildType: 'current'
+              artifactName: $(buildArtifactName)
+              targetPath: '$(Build.SourcesDirectory)/$(buildFolderName)'
+          - task: PowerShell@2
+            name: configureWinRM
+            displayName: 'Configure WinRM'
+            inputs:
+              targetType: 'inline'
+              script: 'winrm quickconfig -quiet'
+              pwsh: false
+          - powershell: |
+              Import-Module -Name ./tests/TestHelpers/CommonTestHelper.psm1
+              # Make sure to keep SQLPS so that Invoke-SqlCmd is available.
+              Remove-PowerShellModuleFromCI -Name @('SqlServer')
+              Remove-Module -Name CommonTestHelper
+            name: cleanCIWorker
+            displayName: 'Clean CI worker'
+          - powershell: |
+              ./build.ps1 -Tasks test -CodeCoverageThreshold 0 -PesterTag $(TEST_CONFIGURATION) -PesterPath @(
+                  # Run the integration tests in a specific group order.
+                  # Group 1
+                  'tests/Integration/DSC_SqlSetup.Integration.Tests.ps1'
+                  # Group 2
+                  'tests/Integration/DSC_SqlAgentAlert.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlLogin.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlEndpoint.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabaseMail.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlRSSetup.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabaseDefaultLocation.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabase.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlAlwaysOnService.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlServiceAccount.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlAgentFailsafe.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlTraceFlag.Integration.Tests.ps1'
+                  # Group 3
+                  'tests/Integration/DSC_SqlRole.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlRS_Default.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabaseUser.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlReplication.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlAudit.Integration.Tests.ps1'
+                  # Group 4
+                  'tests/Integration/DSC_SqlScript.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabasePermission.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlPermission.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlWindowsFirewall.Integration.Tests.ps1'
+                  # Group 5
+                  'tests/Integration/DSC_SqlSecureConnection.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlScriptQuery.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlProtocol.Integration.Tests.ps1'
+                  # Group 6 (tests makes changes that could make SQL Server to loose connectivity)
+                  'tests/Integration/DSC_SqlProtocolTcpIp.Integration.Tests.ps1'
+                  'tests/Integration/DSC_SqlDatabaseObjectPermission.Integration.Tests.ps1'
+              )
+            name: test
+            displayName: 'Run Integration Test'
+          - task: PublishTestResults@2
+            displayName: 'Publish Test Results'
+            condition: succeededOrFailed()
+            inputs:
+              testResultsFormat: 'NUnit'
+              testResultsFiles: '$(buildFolderName)/$(testResultFolderName)/NUnit*.xml'
+              testRunTitle: 'Integration (dbatools) ($(TEST_CONFIGURATION) / $(JOB_VMIMAGE))'
+
       - job: Test_Integration_RS
         displayName: 'Integration Reporting Services'
         strategy:
@@ -314,6 +406,65 @@ stages:
               testResultsFiles: '$(buildFolderName)/$(testResultFolderName)/NUnit*.xml'
               testRunTitle: 'Integration RS ($(TEST_CONFIGURATION) / $(JOB_VMIMAGE))'
 
+      - job: Test_Integration_RS_dbatools
+        displayName: 'Integration Reporting Services (dbatools)'
+        dependsOn: Test_Integration_RS
+        strategy:
+          matrix:
+            SQL2016_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2016'
+            SQL2017_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2017'
+            SQL2019_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2019'
+            SQL2022_WIN2022:
+              JOB_VMIMAGE: 'windows-2022'
+              TEST_CONFIGURATION: 'Integration_SQL2022'
+        variables:
+          SKIP_DATABASE_ENGINE_DEFAULT_INSTANCE: true
+          SKIP_ANALYSIS_MULTI_INSTANCE: true
+          SKIP_ANALYSIS_TABULAR_INSTANCE: true
+          SMODefaultModuleName: 'dbatools'
+        pool:
+          vmImage: $(JOB_VMIMAGE)
+        timeoutInMinutes: 0
+        steps:
+          - task: DownloadPipelineArtifact@2
+            displayName: 'Download Build Artifact'
+            inputs:
+              buildType: 'current'
+              artifactName: $(buildArtifactName)
+              targetPath: '$(Build.SourcesDirectory)/$(buildFolderName)'
+          - task: PowerShell@2
+            name: configureWinRM
+            displayName: 'Configure WinRM'
+            inputs:
+              targetType: 'inline'
+              script: 'winrm quickconfig -quiet'
+              pwsh: false
+          - powershell: |
+              ./build.ps1 -Tasks test -CodeCoverageThreshold 0 -PesterTag $(TEST_CONFIGURATION) -PesterPath @(
+                  # Run the integration tests in a specific group order.
+                  # Group 1
+                  'tests/Integration/DSC_SqlSetup.Integration.Tests.ps1'
+                  # Group 2
+                  'tests/Integration/DSC_SqlRSSetup.Integration.Tests.ps1'
+                  # Group 3
+                  'tests/Integration/DSC_SqlRS.Integration.Tests.ps1'
+              )
+            name: test
+            displayName: 'Run Reporting Services Integration Test'
+          - task: PublishTestResults@2
+            displayName: 'Publish Test Results'
+            condition: succeededOrFailed()
+            inputs:
+              testResultsFormat: 'NUnit'
+              testResultsFiles: '$(buildFolderName)/$(testResultFolderName)/NUnit*.xml'
+              testRunTitle: 'Integration RS (dbatools) ($(TEST_CONFIGURATION) / $(JOB_VMIMAGE))'
+
       - job: Code_Coverage
         displayName: 'Publish Code Coverage'
         dependsOn: Test_Unit

source/Public/Get-SqlDscPreferredModule.ps1

@@ -51,13 +51,25 @@ function Get-SqlDscPreferredModule
     (
         [Parameter()]
         [System.String[]]
-        $Name = @('SqlServer', 'SQLPS'),
+        $Name,
 
         [Parameter()]
         [System.Management.Automation.SwitchParameter]
         $Refresh
     )
 
+    if (-not $PSBoundParameters.ContainsKey('Name'))
+    {
+        $Name = if ($env:SMODefaultModuleName)
+        {
+            @($env:SMODefaultModuleName, 'SQLPS')
+        }
+        else
+        {
+            @('SqlServer', 'SQLPS')
+        }
+    }
+
     if ($Refresh.IsPresent)
     {
         # Only run on Windows that has Machine state.

source/Public/Import-SqlDscPreferredModule.ps1

@@ -40,13 +40,25 @@ function Import-SqlDscPreferredModule
     (
         [Parameter()]
         [System.String]
-        $PreferredModule = 'SqlServer',
+        $PreferredModule,
 
         [Parameter()]
         [System.Management.Automation.SwitchParameter]
         $Force
     )
 
+    if (-not $PSBoundParameters.ContainsKey('PreferredModule'))
+    {
+        $PreferredModule = if ($env:SMODefaultModuleName)
+        {
+            $env:SMODefaultModuleName
+        }
+        else
+        {
+            'SqlServer'
+        }
+    }
+
     if ($Force.IsPresent)
     {
         Write-Verbose -Message $script:localizedData.PreferredModule_ForceRemoval

source/WikiSource/Home.md

@@ -45,7 +45,9 @@ Get-DscResource -Module SqlServerDsc
 
 - Familiarity with Powershell DSC Framework
 - Powershell 5.0 or higher
-- SqlServer powershell module (optional)
+- PowerShell module containing SMO assemblies (optional)
+  - For example the SqlServer PowerShell module or the dbatools PowerShell
+    module.
 
 ### Familiarity with Powershell DSC Framework
 
@@ -67,11 +69,23 @@ on Windows 7 SP1, Windows 8.1, Windows Server 2012, and Windows Server 2012 R2.
 These resource might not work on PowerShell 7.x because they depend on
 *SQL Server* modules which only works in PowerShell 5.x.
 
-### SqlServer powershell module (optional)
+### PowerShell module containing SMO assemblies (optional)
 
-Optionally the PowerShell Module [*SqlServer*](https://www.powershellgallery.com/packages/SqlServer)
-can be installed which then will be used instead of the PowerShell module
-*SQLPS* that is installed with SQL Server.
+There are two options, installing the [*SqlServer*](https://www.powershellgallery.com/packages/SqlServer)
+*PowerShell* module or the *dbatools PowerShell* module.
+
+If the *SqlServer* module is present it will be used instead of *SQLPS*
+automatically.
+
+To use the [*dbatools*](https://www.powershellgallery.com/packages/dbatools)
+module as a replacement for *SQLPS* the environment variable `SMODefaultModuleName`
+must be set to the value `dbatools`. This environment variable can be set
+machine-wide, or at minimum set for each user that runs DSC resources, on
+the target node. Make sure you comply with any license terms that is part
+of dbatools.
+
+>**NOTE:** It is also possible to use any module as a preferred module if
+>its name is set as the value of the environment variable `SMODefaultModuleName`.
 
 ## Change log
 

tests/Integration/DSC_SqlSetup.Integration.Tests.ps1

@@ -215,7 +215,7 @@ Describe "$($script:dscResourceName)_Integration" -Tag @('Integration_SQL2016',
     }
 
     Context ('When using configuration <_>') -ForEach @(
-        "$($script:dscResourceName)_InstallSqlServerModule_Config"
+        "$($script:dscResourceName)_InstallSMOModule_Config"
     ) {
         BeforeAll {
             $configurationName = $_