BREAKING CHANGE: SqlDatabasePermission: Refactored resource (class-based resource)

.vscode/analyzersettings.psd1

@@ -7,48 +7,49 @@
     IncludeDefaultRules = $true
     IncludeRules        = @(
         # DSC Community style guideline rules from the module ScriptAnalyzer.
-        'PSAvoidDefaultValueForMandatoryParameter',
-        'PSAvoidDefaultValueSwitchParameter',
-        'PSAvoidInvokingEmptyMembers',
-        'PSAvoidNullOrEmptyHelpMessageAttribute',
-        'PSAvoidUsingCmdletAliases',
-        'PSAvoidUsingComputerNameHardcoded',
-        'PSAvoidUsingDeprecatedManifestFields',
-        'PSAvoidUsingEmptyCatchBlock',
-        'PSAvoidUsingInvokeExpression',
-        'PSAvoidUsingPositionalParameters',
-        'PSAvoidShouldContinueWithoutForce',
-        'PSAvoidUsingWMICmdlet',
-        'PSAvoidUsingWriteHost',
-        'PSDSCReturnCorrectTypesForDSCFunctions',
-        'PSDSCStandardDSCFunctionsInResource',
-        'PSDSCUseIdenticalMandatoryParametersForDSC',
-        'PSDSCUseIdenticalParametersForDSC',
-        'PSMisleadingBacktick',
-        'PSMissingModuleManifestField',
-        'PSPossibleIncorrectComparisonWithNull',
-        'PSProvideCommentHelp',
-        'PSReservedCmdletChar',
-        'PSReservedParams',
-        'PSUseApprovedVerbs',
-        'PSUseCmdletCorrectly',
-        'PSUseOutputTypeCorrectly',
-        'PSAvoidGlobalVars',
-        'PSAvoidUsingConvertToSecureStringWithPlainText',
-        'PSAvoidUsingPlainTextForPassword',
-        'PSAvoidUsingUsernameAndPasswordParams',
-        'PSDSCUseVerboseMessageInDSCResource',
-        'PSShouldProcess',
-        'PSUseDeclaredVarsMoreThanAssignments',
-        'PSUsePSCredentialType',
+        'PSAvoidDefaultValueForMandatoryParameter'
+        'PSAvoidDefaultValueSwitchParameter'
+        'PSAvoidInvokingEmptyMembers'
+        'PSAvoidNullOrEmptyHelpMessageAttribute'
+        'PSAvoidUsingCmdletAliases'
+        'PSAvoidUsingComputerNameHardcoded'
+        'PSAvoidUsingDeprecatedManifestFields'
+        'PSAvoidUsingEmptyCatchBlock'
+        'PSAvoidUsingInvokeExpression'
+        'PSAvoidUsingPositionalParameters'
+        'PSAvoidShouldContinueWithoutForce'
+        'PSAvoidUsingWMICmdlet'
+        'PSAvoidUsingWriteHost'
+        'PSDSCReturnCorrectTypesForDSCFunctions'
+        'PSDSCStandardDSCFunctionsInResource'
+        'PSDSCUseIdenticalMandatoryParametersForDSC'
+        'PSDSCUseIdenticalParametersForDSC'
+        'PSMisleadingBacktick'
+        'PSMissingModuleManifestField'
+        'PSPossibleIncorrectComparisonWithNull'
+        'PSProvideCommentHelp'
+        'PSReservedCmdletChar'
+        'PSReservedParams'
+        'PSUseApprovedVerbs'
+        'PSUseCmdletCorrectly'
+        'PSUseOutputTypeCorrectly'
+        'PSAvoidGlobalVars'
+        'PSAvoidUsingConvertToSecureStringWithPlainText'
+        'PSAvoidUsingPlainTextForPassword'
+        'PSAvoidUsingUsernameAndPasswordParams'
+        'PSDSCUseVerboseMessageInDSCResource'
+        'PSShouldProcess'
+        'PSUseDeclaredVarsMoreThanAssignments'
+        'PSUsePSCredentialType'
 
         # Additional rules from the module ScriptAnalyzer
-        'PSUseConsistentWhitespace',
-        'UseCorrectCasing',
-        'PSPlaceOpenBrace',
-        'PSPlaceCloseBrace',
-        'AlignAssignmentStatement',
-        'AvoidUsingDoubleQuotesForConstantString',
+        'PSUseConsistentWhitespace'
+        'UseCorrectCasing'
+        'PSPlaceOpenBrace'
+        'PSPlaceCloseBrace'
+        'AlignAssignmentStatement'
+        'AvoidUsingDoubleQuotesForConstantString'
+        'UseShouldProcessForStateChangingFunctions'
 
         # Rules from the modules DscResource.AnalyzerRules and SqlServerDsc.AnalyzerRules
         'Measure-*'
@@ -70,6 +71,11 @@
         'UseSyntacticallyCorrectExamples'
     )
 
+    # TODO: This is not excluded correctly, see test QA/ScriptAnalyzer.Tests.ps1 for more information.
+    ExcludeRules        = @(
+        'TypeNotFound'
+    )
+
     Rules               = @{
         PSUseConsistentWhitespace  = @{
             Enable                          = $true
@@ -80,7 +86,7 @@
             CheckSeparator                  = $true
             CheckPipe                       = $true
             CheckPipeForRedundantWhitespace = $true
-            CheckParameter                  = $true
+            CheckParameter                  = $false
         }
 
         PSPlaceOpenBrace           = @{

CHANGELOG.md

@@ -38,6 +38,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     the existing DSC Community rules and style guideline were added.
   - Added the Visual Studio Code extension _Code Spell Checker_ to the list
     of recommended Visual Studio Code extensions.
+  - Added a file `prefix.ps1` which content is placed first in the built module
+    (.psm1). This file imports dependent modules, and imports localized strings
+    used by private and public commands.
+  - The following classes were added to the module:
+    - `DatabasePermission` - complex type for the DSC resource SqlDatabasePermission.
+    - `Ensure` - Enum to be used for the property `Ensure` in class-based
+      resources.
+    - `Reason` - Used by method `Get()` to return the reason a property is not
+      in desired state.
+    - `ResourceBase` - class that can be inherited by class-based resource and
+      provides functionality meant simplify the creating of class-based resource.
+  - The following private functions were added to the module (see comment-based
+    help for more information):
+    - `ConvertFrom-CompareResult`
+    - `ConvertTo-Reason`
+    - `Get-ClassName`
+    - `Get-DscProperty`
+    - `Get-LocalizedDataRecursive`
+    - `Test-ResourceHasDscProperty`
+    - `Test-ResourceDscPropertyIsAssigned`
+  - The following public functions were added to the module (see comment-based
+    help for more information):
+    - `Connect-SqlDscDatabaseEngine`
+    - `ConvertFrom-SqlDscDatabasePermission`
+    - `ConvertTo-SqlDscDatabasePermission`
+    - `Get-SqlDscDatabasePermission`
+    - `Set-SqlDscDatabasePermission`
+    - `Test-SqlDscIsDatabasePrincipal`
 - CommonTestHelper
   - `Import-SqlModuleStub`
     - Added the optional parameter **PasThru** that, if used, will return the
@@ -59,8 +87,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Bumped Stale task to v5 in the GitHub workflow.
   - Make it possible to publish code coverage on failed test runs, and
     when re-run a fail job.
+  - Exclude Script Analyzer rule **TypeNotFound** in the file `.vscode/analyzersettings.psd1`.
+  - Update CONTRIBUTING.md describing error handling in commands and class-based
+    resources.
+  - The QA tests are now run in Windows PowerShell due to a bug in PowerShell 7
+    that makes class-based resource using inheritance to not work.
+  - The QA test are excluding the rule **TypeNotFound** because it cannot
+    run on the source files (there is a new issue that is tracking so this
+    rule is only run on the built module).
+  - The Pester code coverage has been switched to use the older functionality
+    that uses breakpoints to calculate coverage. Newer functionality sometimes
+    throw an exception when used in conjunction with class-based resources.¨
+  - The SMO stubs (used in the unit tests) was updated to remove a bug related
+    to the type `DatabasePermissionInfo` when used with the type `DatabasePermissionSet`.
+    The stubs suggested that the property `PermissionType` (of type `DatabasePermissionSet`)
+     in `DatabasePermissionInfo` should have been a array `DatabasePermissionSet[]`.
+     This conflicted with real SMO as it does not pass an array, but instead
+     a single `DatabasePermissionSet`. The stubs was modified to mimic the
+     real SMO. At the same time some old mock code in the SMO stubs was removed
+     as it was no longer in use.
 - Wiki
   - add introduction and links to DSC technology
+- SqlServerDsc.Common
+  - The parameter `SetupCredential` of the function `Connect-SQL` was renamed
+    to `Credential` and the parameter name `SetupCredential` was made a
+    parameter alias.
 - SqlLogin
   - BREAKING CHANGE: The parameters `LoginMustChangePassword`, `LoginPasswordExpirationEnabled`,
     and `LoginPasswordPolicyEnforced` no longer have a default value of `$true`.
@@ -128,6 +179,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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.
+- SqlDatabasePermission
+  - BREAKING CHANGE: The resource has been refactored. The parameters
+    `ParameterState` and `Permissions` has been replaced by parameters
+    `Permission`, `PermissionToInclude`, and `PermissionToExclude`. These
+    permissions parameters are now an instance of the type `DatabasePermission`.
+    The type `DatabasePermission` contains two properties; `State` and
+    `Permission`.
+  - The resource was refactored into a class-based resource.
 
 ### Fixed
 
@@ -203,6 +262,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     step for each iteration. A line of code was moved outside of the loop.
   - The `SourcePath` parameter is now mandatory for all `*-TargetResource`
     ([issue #1755](https://github.com/dsccommunity/SqlServerDsc/issues/1755)).
+- SqlDatabasePermission
+  - It is no longer possible to have one permission that has two different
+    states in the same configuration, e.g. denying and granting `update`
+    in the same configuration.
 
 ## [15.2.0] - 2021-09-01
 

CONTRIBUTING.md

@@ -217,7 +217,7 @@ class DSC_SqlConfiguration : OMI_BaseResource
 ### Composite or class-based resource
 
 Any composite (with a Configuration) or class-based resources should be prefixed
-with just 'Sql'
+with 'Sql'
 
 ### Localization
 
@@ -277,3 +277,103 @@ SQL Server 2016, SQL Server 2017 and SQL Server 2019.
 
 When sending in a Pull Request (PR) all example files will be tested so they can
 be compiled to a .mof file. If the tests find any errors the build will fail.
+
+### Class-based DSC resource
+
+#### Terminating Error
+
+A terminating error is an error that prevents the resource to continue further.
+If a DSC resource shall throw an terminating error the commands of the module
+**DscResource.Common** shall be used primarily; [`New-InvalidArgumentException`](https://github.com/dsccommunity/DscResource.Common#new-invalidargumentexception),
+[`New-InvalidDataExcpetion`](https://github.com/dsccommunity/DscResource.Common#new-invaliddataexception),
+[`New-InvalidOperationException`](https://github.com/dsccommunity/DscResource.Common#new-invalidoperationexception),
+[`New-InvalidResultException`](https://github.com/dsccommunity/DscResource.Common#new-invalidresultexception),
+or [`New-NotImplementedException`](https://github.com/dsccommunity/DscResource.Common#new-notimplementedexception).
+If neither of those commands works in the scenarion then `throw` shall be used.
+
+### Commands
+
+Commands are publicly exported commands from the module, and the source for
+commands are located in the folder `./source/Public`.
+
+#### Non-Terminating Error
+
+A non-terminating error should only be used when a command shall be able to
+handle (ignoring) an error and continue processing and still give the user
+an expected outcome.
+
+With a non-terminating error the user is able to decide whether the command
+should throw or continue processing on error. The user can pass the
+parameter and value `-ErrorAction 'SilentlyContinue'` to the command  to
+ignore the error and allowing the command to continue, for example the
+command could then return `$null`. But if the user passes the parameter
+and value `-ErrorAction 'Stop'` the same error will throw a terminating
+error telling the user the expected outcome could not be achieved.
+
+The below example checks to see if a database exist, if it doesn't a
+non-terminating error are called. The user is able to either ignore the
+error or have it throw depending on what value the user specifies
+in parameter `ErrorAction` (or `$ErrorActionPreference`).
+
+```powershell
+if (-not $databaseExist)
+{
+    $errorMessage = $script:localizedData.MissingDatabase -f $DatabaseName
+
+    Write-Error -Message $errorMessage -Category 'InvalidOperation' -ErrorId 'GS0001' -TargetObject $DatabaseName
+}
+```
+
+#### Terminating Error
+
+A terminating error is an error that the user are not able to ignore by
+passing a parameter to the command (like for non-terminating errors).
+
+If a command shall throw an terminating error the statement `throw` shall
+not be used, neither shall the command `Write-Error` be used with the parameter
+`-ErrorAction `Stop``. Instead the method `$PSCmdlet.ThrowTerminatingError()`
+shall be used to throw a terminating error.
+
+
+>**NOTE:** Below output assumes `$ErrorView` is set to `'NormalView'` in the
+>PowerShell session.
+
+When using `throw` it will fail on the line with the throw statement
+making it look like it is that statement inside the function that failed,
+which is not correct since it is either a previous command or evaluation
+that failed resulting in the line with the `throw` being called. This is
+an example when using `throw`:
+
+```plaintext
+Exception:
+Line |
+   2 |  throw 'My error'
+     |  ~~~~~~~~~~~~~~~~
+     | My error
+```
+
+When instead using `$PSCmdlet.ThrowTerminatingError()`:
+
+```powershell
+$PSCmdlet.ThrowTerminatingError(
+    [System.Management.Automation.ErrorRecord]::new(
+        'MyError',
+        'GS0001',
+        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+        'MyObjectOrValue'
+    )
+)
+```
+
+The result from `$PSCmdlet.ThrowTerminatingError()` shows that the command
+failed (in this example `Get-Something`) and returns a clear category and
+error code.
+
+```plaintext
+Get-Something : My Error
+At line:1 char:1
++ Get-Something
++ ~~~~~~~~~~~~~
++ CategoryInfo          : InvalidOperation: (MyObjectOrValue:String) [Get-Something], Exception
++ FullyQualifiedErrorId : GS0001,Get-Something
+```

azure-pipelines.yml

@@ -68,7 +68,11 @@ stages:
               buildType: 'current'
               artifactName: $(buildArtifactName)
               targetPath: '$(Build.SourcesDirectory)/$(buildFolderName)'
-          - pwsh: |
+          # This task need to use Windows PowerShell due to a bug in PS7 that cannot
+          # find/use class-based DSC resources that uses inheritance, which result in
+          # the examples cannot compile. See the following issue for more information:
+          # https://github.com/dsccommunity/DnsServerDsc/issues/268#issuecomment-918505230
+          - powershell: |
               # Workaround for issue https://github.com/dsccommunity/DscResource.Test/issues/100
               ./build.ps1 -Task noop
 
@@ -78,7 +82,7 @@ stages:
               $pesterConfig.Output.Verbosity = 'Detailed'
 
               Invoke-Pester -Configuration $pesterConfig
-            name: qualitytest
+            name: qualityTest
             displayName: 'Run SqlServerDsc QA Test'
           - task: PowerShell@2
             name: test

build.yaml

@@ -38,6 +38,7 @@ CopyPaths:
   - DSCResources
   - en-US
   - Modules
+Prefix: prefix.ps1
 Encoding: UTF8
 VersionedOutputDirectory: true
 
@@ -88,7 +89,9 @@ Pester:
       CoveragePercentTarget: 85
       OutputPath: JaCoCo_coverage.xml
       OutputEncoding: ascii
-      UseBreakpoints: false
+      # There is a bug in Pester when running unit tests for classes when 'UseBreakpoints' is turned off.
+      # See error in gist: https://gist.github.com/johlju/c16dfd9587c7e066e8825fc54b33a703
+      UseBreakpoints: true
     TestResult:
       OutputFormat: NUnitXML
       OutputEncoding: ascii
@@ -116,6 +119,8 @@ DscTest:
       - output
     ExcludeModuleFile:
       - Modules/DscResource.Common
+      # Must exclude built module file because it should not be tested like MOF-based resources
+      - SqlServerDsc.psm1
     MainGitBranch: main
 
 ####################################################