BREAKING CHANGE: ADDomain: Change Domain Install Tracking File to NetLogon Registry Test and Refactor

.markdownlint.json

@@ -3,7 +3,9 @@
     "MD029": {
         "style": "one"
     },
-    "MD013": true,
+    "MD013": {
+        "line_length": 120
+    },
     "MD024": false,
     "MD034": false,
     "no-hard-tabs": true

CHANGELOG.md

@@ -12,25 +12,52 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
 - ActiveDirectoryDsc
   - Added [Codecov.io](https://codecov.io) support.
   - Fixed miscellaneous spelling errors.
+- ADDomain
+  - Added integration tests
+    ([issue #302](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/302)).
 - ADForestProperties
-  - Added TombstoneLifetime property ([issue #302](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/302)).
-  - Added Integration tests ([issue #349](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/349)).
+  - Added TombstoneLifetime property
+    ([issue #302](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/302)).
+  - Added Integration tests
+    ([issue #349](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/349)).
 
 ### Fixed
 
 - ADForestProperties
-  - Fixed ability to clear `ServicePrincipalNameSuffix` and `UserPrincipalNameSuffix` ([issue #548](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/548)).
+  - Fixed ability to clear `ServicePrincipalNameSuffix` and `UserPrincipalNameSuffix`
+    ([issue #548](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/548)).
 - ADObjectPermissionEntry
-    - Fixed issue where Get-DscConfiguration / Test-DscConfiguration throw an exception when target object path does not yet exist ([issue #552](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/552))
-    - Fixed issue where Get-TargetResource throw an exception, `Cannot find drive. A drive with the name 'AD' does not exist`, when running soon after domain controller restart ([issue #547](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/547))
+  - Fixed issue where Get-DscConfiguration / Test-DscConfiguration throw an exception when target object path does not
+    yet exist
+    ([issue #552](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/552))
+  - Fixed issue where Get-TargetResource throw an exception, `Cannot find drive. A drive with the name 'AD' does not
+    exist`, when running soon after domain controller restart
+    ([issue #547](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/547))
 - ADOrganizationalUnit
-  - Fixed issue where Get-DscConfiguration / Test-DscConfiguration throw an exception when parent path does not yet exist ([issue #553](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/553))
+  - Fixed issue where Get-DscConfiguration / Test-DscConfiguration throw an exception when parent path does not yet exist
+    ([issue #553](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/553))
 
 ### Changed
 
 - ActiveDirectoryDsc
-  - Updated Azure Pipeline Windows image ([issue #551](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/551)).
-  - Updated license copyright ([issue #550](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/550)).
+  - BREAKING CHANGE: Required PowerShell version increased from v4.0 to v5.0
+  - Updated Azure Pipeline Windows image
+    ([issue #551](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/551)).
+  - Updated license copyright
+    ([issue #550](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/550)).
+- ADDomain
+  - Changed Domain Install Tracking File to use NetLogon Registry Test.
+    ([issue #560](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/560)).
+  - Updated the Get-TargetResource function with the following:
+    - Removed unused parameters.
+    - Removed unnecessary domain membership check.
+    - Removed unneeded catch exception blocks.
+    - Changed Get-ADDomain and Get-ADForest to use localhost as the server.
+    - Improved Try/Catch blocks to only cover cmdlet calls.
+    - Simplified retry timing loop.
+  - Refactored unit tests.
+  - Updated NewChildDomain example to clarify the contents of the credential parameter and use Windows 2016 rather than
+    2012 R2.
 - ADForestProperties
   - Refactored unit tests.
 
@@ -39,65 +66,87 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
 ### Added
 
 - ADServicePrincipalName
-  - Added Integration tests ([issue #358](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/358)).
+  - Added Integration tests
+    ([issue #358](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/358)).
 - ADManagedServiceAccount
   - Added Integration tests.
 - ADKDSKey
-  - Added Integration tests ([issue #351](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/351)).
+  - Added Integration tests
+    ([issue #351](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/351)).
 
 ### Changed
 
 - ADManagedServiceAccount
-  - KerberosEncryptionType property added. ([issue #511](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/511)).
-  - BREAKING CHANGE: AccountType parameter ValidateSet changed from ('Group', 'Single') to ('Group', 'Standalone') - Standalone is the correct terminology. Ref: [Service Accounts](https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/service-accounts).
-  ([issue #515](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/515)).
+  - KerberosEncryptionType property added.
+    ([issue #511](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/511)).
+  - BREAKING CHANGE: AccountType parameter ValidateSet changed from ('Group', 'Single') to ('Group', 'Standalone') -
+    Standalone is the correct terminology.
+    Ref: [Service Accounts](https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/service-accounts).
+    ([issue #515](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/515)).
   - BREAKING CHANGE: AccountType parameter default of Single removed. - Enforce positive choice of account type.
-  - BREAKING CHANGE: MembershipAttribute parameter ValidateSet member SID changed to ObjectSid to match result property of Get-AdObject. Previous code does not work if SID is specified.
+  - BREAKING CHANGE: MembershipAttribute parameter ValidateSet member SID changed to ObjectSid to match result property
+    of Get-AdObject. Previous code does not work if SID is specified.
   - BREAKING CHANGE: AccountTypeForce parameter removed - unnecessary complication.
-  - BREAKING CHANGE: Members parameter renamed to ManagedPasswordPrincipals - to closer match Get-AdServiceAccount result property PrincipalsAllowedToRetrieveManagedPassword. This is so that a DelegateToAccountPrincipals parameter can be added later.
-  - Common Compare-ResourcePropertyState function used to replace function specific Compare-TargetResourceState and code refactored.
-  ([issue #512](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/512)).
+  - BREAKING CHANGE: Members parameter renamed to ManagedPasswordPrincipals - to closer match Get-AdServiceAccount result
+    property PrincipalsAllowedToRetrieveManagedPassword. This is so that a DelegateToAccountPrincipals parameter can be
+    added later.
+  - Common Compare-ResourcePropertyState function used to replace function specific Compare-TargetResourceState and code
+    refactored.
+    ([issue #512](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/512)).
   - Resource unit tests refactored to use nested contexts and follow the logic of the module.
 - ActiveDirectoryDsc
   - Updated PowerShell help files.
   - Updated Wiki link in README.md.
   - Remove verbose parameters from unit tests.
   - Fix PowerShell script file formatting and culture string alignment.
   - Add the `pipelineIndentationStyle` setting to the Visual Studio Code settings file.
-  - Remove unused common function Test-DscParameterState ([issue #522](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/522)).
+  - Remove unused common function Test-DscParameterState
+    ([issue #522](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/522)).
 
 ### Fixed
 
 - ActiveDirectoryDsc
   - Fix tests ErrorAction on DscResource.Test Import-Module.
 - ADObjectPermissionEntry
-  - Updated Assert-ADPSDrive with PSProvider Checks ([issue #527](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/527)).
+  - Updated Assert-ADPSDrive with PSProvider Checks
+    ([issue #527](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/527)).
 - ADReplicationSite
-  - Fixed incorrect evaluation of site configuration state when no description is defined ([issue #534](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/534)).
+  - Fixed incorrect evaluation of site configuration state when no description is defined
+    ([issue #534](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/534)).
 - ADReplicationSiteLink
-  - Fix RemovingSites verbose message ([issue #518](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/518)).
+  - Fix RemovingSites verbose message
+    ([issue #518](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/518)).
 - ADComputer
-  - Fixed the SamAcountName property description ([issue #529](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/529)).
+  - Fixed the SamAcountName property description
+    ([issue #529](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/529)).
 
 ## 4.2.0.0
 
 ### Added
 
 - ADReplicationSite
-  - Added 'Description' attribute parameter ([issue #500](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/500)).
-  - Added Integration testing ([issue #355](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/355)).
+  - Added 'Description' attribute parameter
+    ([issue #500](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/500)).
+  - Added Integration testing
+    ([issue #355](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/355)).
 - ADReplicationSubnet
-  - Added 'Description' attribute parameter ([issue #503](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/500)).
-  - Added Integration testing ([issue #357](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/357)).
+  - Added 'Description' attribute parameter
+    ([issue #503](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/500)).
+  - Added Integration testing
+    ([issue #357](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/357)).
 - ADReplicationSiteLink
-  - Added Integration testing ([issue #356](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/356)).
-  - Added ability to set 'Options' such as Change Notification Replication ([issue #504](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/504)).
+  - Added Integration testing
+    ([issue #356](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/356)).
+  - Added ability to set 'Options' such as Change Notification Replication
+    ([issue #504](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/504)).
 
 ### Fixed
 
 - ActiveDirectoryDsc
   - Resolved custom Script Analyzer rules that was added to the test framework.
 - ActiveDirectoryDsc.Common
-  - Fix `Test-DscPropertyState` Failing when Comparing $Null and Arrays. ([issue #513](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/513)).
+  - Fix `Test-DscPropertyState` Failing when Comparing $Null and Arrays.
+    ([issue #513](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/513)).
 - ADReplicationSite
-  - Correct value returned for RenameDefaultFirstSiteName ([issue #502](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/502)).
+  - Correct value returned for RenameDefaultFirstSiteName
+    ([issue #502](https://github.com/dsccommunity/ActiveDirectoryDsc/issues/502)).

Tests/Integration/MSFT_ADDomain.Child.Integration.Tests.ps1

@@ -0,0 +1,112 @@
+<#
+    .SYNOPSIS
+        Pester integration test for the ADDomain Resource of the ActiveDirectoryDsc Module
+        This Subtest creates a child domain in an existing forest
+
+    .DESCRIPTION
+        Verbose/Debug output can be set by running:
+
+        Invoke-pester -Script @{Path='.\MSFT_ADDomain.Child.Integration.Tests.ps1';Parameters=@{Verbose=$true;Debug=$true}}
+#>
+
+[CmdletBinding()]
+param ()
+
+Set-StrictMode -Version 1.0
+
+$script:dscModuleName = 'ActiveDirectoryDsc'
+$script:dscResourceFriendlyName = 'ADDomain'
+$script:dscResourceName = "MSFT_$($script:dscResourceFriendlyName)"
+$script:subTestName = 'Child'
+
+try
+{
+    Import-Module -Name DscResource.Test -Force -ErrorAction 'Stop'
+}
+catch [System.IO.FileNotFoundException]
+{
+    throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -Tasks build" first.'
+}
+
+$script:testEnvironment = Initialize-TestEnvironment `
+    -DSCModuleName $script:dscModuleName `
+    -DSCResourceName $script:dscResourceName `
+    -ResourceType 'Mof' `
+    -TestType 'Integration'
+
+try
+{
+    $configFile = Join-Path -Path $PSScriptRoot -ChildPath "$($script:dscResourceName).$($script:subTestName).config.ps1"
+    . $configFile
+
+    Describe "$($script:dscResourceName).$($script:subTestName)_Integration" {
+        BeforeAll {
+            $resourceId = "[$($script:dscResourceFriendlyName)]Integration_Test"
+        }
+
+
+        foreach ($testName in $ConfigurationData.AllNodes.Tests.Keys )
+        {
+            $configurationName = "$($script:dscResourceName)_$($testName)_Config"
+
+            Context ('When using configuration {0}' -f $configurationName) {
+                It 'Should compile and apply the MOF without throwing' {
+                    {
+                        $configurationParameters = @{
+                            OutputPath        = $TestDrive
+                            # The variable $ConfigurationData was dot-sourced above.
+                            ConfigurationData = $ConfigurationData
+                        }
+
+                        & $configurationName @configurationParameters
+
+                        $startDscConfigurationParameters = @{
+                            Path         = $TestDrive
+                            ComputerName = 'localhost'
+                            Wait         = $true
+                            Force        = $true
+                            ErrorAction  = 'Stop'
+                        }
+
+                        Start-DscConfiguration @startDscConfigurationParameters
+                    } | Should -Not -Throw
+                }
+
+                $DscConfigurationStatus = Get-DscConfigurationStatus
+                if ($DscConfigurationStatus.RebootRequested)
+                {
+                    Write-Warning 'A Reboot has been requested by the DSC. Please reboot then re-run the test'
+                    Return
+                }
+
+                It 'Should be able to call Get-DscConfiguration without throwing' {
+                    {
+                        $script:currentConfiguration = Get-DscConfiguration -ErrorAction Stop
+                    } | Should -Not -Throw
+                }
+
+                $resourceCurrentState = $script:currentConfiguration | Where-Object -FilterScript {
+                    $_.ConfigurationName -eq $configurationName `
+                        -and $_.ResourceId -eq $resourceId
+                }
+
+                foreach ($property in $ConfigurationData.AllNodes.Tests.$testName.Keys)
+                {
+                    It "Should have set the correct $property property" {
+                        $resourceCurrentState.$property | Should -Be $ConfigurationData.AllNodes.Tests.$testName.$property
+                    }
+                }
+
+                It 'Should return $true when Test-DscConfiguration is run' {
+                    Test-DscConfiguration | Should -Be 'True'
+                }
+            }
+        }
+    }
+}
+finally
+{
+    #region FOOTER
+    Restore-TestEnvironment -TestEnvironment $script:testEnvironment
+    #endregion
+}

Tests/Integration/MSFT_ADDomain.Child.config.ps1

@@ -0,0 +1,100 @@
+#region HEADER
+# Integration Test Config Template Version: 1.2.0
+#endregion
+
+$configFile = [System.IO.Path]::ChangeExtension($MyInvocation.MyCommand.Path, 'json')
+if (Test-Path -Path $configFile)
+{
+    <#
+        Allows reading the configuration data from a JSON file, for real testing
+        scenarios outside of the CI.
+    #>
+    $ConfigurationData = Get-Content -Path $configFile | ConvertFrom-Json
+}
+else
+{
+    $ConfigurationData = @{
+        AllNodes = @(
+            @{
+                NodeName           = 'localhost'
+                CertificateFile    = $env:DscPublicCertificatePath
+                CredentialUserName = '[email protected]'
+                CredentialPassword = 'password'
+                SafeModePassword   = 'SafemodePassword@1'
+                Tests              = [Ordered]@{
+                    FeatureInstall   = @{ }
+                    ForestChildDomain = @{
+                        DomainName        = 'child'
+                        ParentDomainName  = 'contoso.com'
+                        DomainNetbiosName = 'CHILD-CONTOSO'
+                        DatabasePath      = 'C:\NTDS'
+                        LogPath           = 'C:\NTDS'
+                        SysvolPath        = 'C:\SysVol'
+                        DomainMode        = 'WinThreshold'
+                    }
+                }
+            }
+        )
+    }
+}
+
+<#
+    .SYNOPSIS
+        Initialise Config
+#>
+Configuration MSFT_ADDomain_FeatureInstall_Config
+{
+    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'
+
+    $testName = 'FeatureInstall'
+
+    node $AllNodes.NodeName
+    {
+        WindowsFeature 'ADDS'
+        {
+            Name = 'AD-Domain-Services'
+        }
+    }
+}
+
+<#
+    .SYNOPSIS
+        Initialise Config
+#>
+Configuration MSFT_ADDomain_ForestChildDomain_Config
+{
+    Import-DscResource -ModuleName 'ActiveDirectoryDsc'
+
+    $testName = 'ForestChildDomain'
+
+    node $AllNodes.NodeName
+    {
+        $SecureCredentialPassword = ConvertTo-SecureString `
+            -String $Node.CredentialPassword `
+            -AsPlainText -Force
+
+        $Credential = [System.Management.Automation.PSCredential]::new(
+            $Node.CredentialUserName,
+            $SecureCredentialPassword
+        )
+
+        $SafeModePassword = ConvertTo-SecureString `
+            -String $Node.SafeModePassword `
+            -AsPlainText -Force
+
+        $SafemodeCredential = [System.Management.Automation.PSCredential]::new('n/a', $SafemodePassword)
+
+        ADDomain Integration_Test
+        {
+            DomainName                    = $Node.Tests.$testName.DomainName
+            ParentDomainName              = $Node.Tests.$testName.ParentDomainName
+            Credential                    = $Credential
+            SafemodeAdministratorPassword = $SafeModeCredential
+            DomainNetbiosName             = $Node.Tests.$testName.DomainNetbiosName
+            DatabasePath                  = $Node.Tests.$testName.DatabasePath
+            LogPath                       = $Node.Tests.$testName.LogPath
+            SysvolPath                    = $Node.Tests.$testName.SysvolPath
+            DomainMode                    = $Node.Tests.$testName.DomainMode
+        }
+    }
+}