Added support for Windows RSAT Modules

PSDepend/PSDependMap.psd1

@@ -95,4 +95,10 @@
         Description = 'Support dependencies by handling simple tasks'
         Supports    = 'windows', 'core', 'macos', 'linux'
     }
+
+    WindowsRSAT = @{
+        Script = 'WindowsRSAT.ps1'
+        Description = 'Install a WindowsRSAT PowerShell module using Add-WindowsCapability or Install-WindowsFeature, depending on OS'
+        Supports = 'windows'
+    }
 }

PSDepend/PSDependScripts/WindowsRSAT.ps1

@@ -0,0 +1,183 @@
+<#
+    .SYNOPSIS
+        'Install a WindowsRSAT PowerShell module using Add-WindowsCapability or Install-WindowsFeature, depending on OS'
+
+    .DESCRIPTION
+        Installs a RSAT Module in Windows.
+
+        The Install action requires an elevated (administrator) session, on both
+        Workstation (Add-WindowsCapability) and Server (Install-WindowsFeature).
+        The Test action does not require elevation. If the module is already
+        present, all actions short-circuit and succeed without elevation.
+
+        Relevant Dependency metadata:
+            Name: The name for the module to install
+
+    .PARAMETER PSDependAction
+        Test, Install, or Import the module.  Defaults to Install
+
+        Test: Return true or false on whether the dependency is in place
+        Install: Install the dependency
+        Import: Import the dependency
+
+    .EXAMPLE
+        @{
+            ActiveDirectory = @{
+                DependencyType = 'WindowsRSAT'
+                Name = 'ActiveDirectory'
+            }
+        }
+#>
+[cmdletbinding()]
+param(
+    [PSTypeName('PSDepend.Dependency')]
+    [psobject[]]$Dependency,
+
+    [ValidateSet('Test', 'Install', 'Import')]
+    [string[]]$PSDependAction = @('Install')
+)
+
+
+$RSAT_MODULE_MAP = @{
+    'ActiveDirectory'           = @{
+        'WindowsFeature'    = 'RSAT-AD-Powershell'
+        'WindowsCapability' = 'Rsat.ActiveDirectory.DS-LDS.Tools'
+    }
+    'ADDSDeployment'            = @{
+        'WindowsFeature'    = 'RSAT-AD-Powershell'
+        'WindowsCapability' = 'Rsat.ActiveDirectory.DS-LDS.Tools'
+    }
+    'ADCSAdministration'        = @{
+        'WindowsFeature'    = 'RSAT-ADCS-Mgmt'
+        'WindowsCapability' = 'Rsat.CertificateServices.Tools'
+    }
+    'ADCSDeployment'            = @{
+        'WindowsFeature'    = 'RSAT-ADCS-Mgmt'
+        'WindowsCapability' = 'Rsat.CertificateServices.Tools'
+    }
+    'ADRMS'                     = @{
+        'WindowsFeature' = 'RSAT-ADRMS'
+        #'WindowsCapability' = 'Rsat.CertificateServices.Tools'
+    }
+    'ADRMSAdmin'                = @{
+        'WindowsFeature' = 'RSAT-ADRMS'
+        #'WindowsCapability' = 'Rsat.CertificateServices.Tools'
+    }
+    'BitLocker'                 = @{
+        'WindowsFeature'    = 'RSAT-Feature-Tools-BitLocker-RemoteAdminTool'
+        'WindowsCapability' = 'Rsat.BitLocker.Recovery.Tools'
+    }
+    'DFSN'                      = @{
+        'WindowsFeature' = 'RSAT-DFS-Mgmt-Con'
+        #'WindowsCapability' = 'Rsat.BitLocker.Recovery.Tools'
+    }
+    'DFSR'                      = @{
+        'WindowsFeature' = 'RSAT-DFS-Mgmt-Con'
+        #'WindowsCapability' = 'Rsat.BitLocker.Recovery.Tools'
+    }
+    'DHCP'                      = @{
+        'WindowsFeature'    = 'RSAT-DHCP'
+        'WindowsCapability' = 'Rsat.DHCP.Tools'
+    }
+    'DNSClient'                 = @{
+        'WindowsFeature'    = 'RSAT-DNS-Server'
+        'WindowsCapability' = 'Rsat.Dns.Tools'
+    }
+    'DNSServer'                 = @{
+        'WindowsFeature'    = 'RSAT-DNS-Server'
+        'WindowsCapability' = 'Rsat.Dns.Tools'
+    }
+    'FailoverClusters'          = @{
+        'WindowsFeature'    = 'RSAT-Clustering-PowerShell'
+        'WindowsCapability' = 'Rsat.FailoverCluster.Management.Tools'
+    }
+    'FileServerResourceManager' = @{
+        'WindowsFeature' = 'RSAT-FSRM-Mgmt'
+        #'WindowsCapability' = 'Rsat.FileServices.Tools'
+    }
+    'GroupPolicy'               = @{
+        'WindowsFeature'    = 'GPMC'
+        'WindowsCapability' = 'Rsat.GroupPolicy.Management.Tools'
+    }
+    'Hyper-V'                   = @{
+        'WindowsFeature' = 'RSAT-Hyper-V-Tools'
+        #'WindowsCapability' = 'Rsat.GroupPolicy.Management.Tools'
+    }
+    'IISAdministration'         = @{
+        'WindowsFeature' = 'web-mgmt-console'
+        #'WindowsCapability' = 'Rsat.GroupPolicy.Management.Tools'
+    }
+    'RemoteAccess'              = @{
+        'WindowsFeature'    = 'RSAT-RemoteAccess-Powershell'
+        'WindowsCapability' = 'Rsat.RemoteAccess.Management.Tools'
+    }
+    'VAMT'                      = @{
+        'WindowsFeature'    = 'RSAT-VA-Tools'
+        'WindowsCapability' = 'Rsat.VolumeActivation.Tools'
+    }
+}
+
+# Extract data from Dependency
+$ModuleName = $Dependency.Name
+if (-not $ModuleName) {
+    $ModuleName = $Dependency.DependencyName
+}
+
+if (Get-Module -ListAvailable -Name $ModuleName -ErrorAction SilentlyContinue) {
+    Write-Verbose "Found existing module [$ModuleName]"
+    if ($PSDependAction -contains 'Test') {
+        return $True
+    }
+    return $null
+}
+
+#No dependency found, return false if we're testing alone...
+if ( $PSDependAction -contains 'Test' -and $PSDependAction.count -eq 1) {
+    return $False
+}
+
+if ($PSDependAction -contains 'Install') {
+
+    if (-not (Test-Administrator)) {
+        throw "Installing RSAT module '$ModuleName' requires an elevated session. Re-run from a PowerShell started with 'Run as administrator'."
+    }
+
+    #Server
+    $Type = 'WindowsFeature'
+    if ((Get-CimInstance -ClassName Win32_OperatingSystem).ProductType -eq 1) {
+        # Workstation
+        $Type = 'WindowsCapability'
+    }
+
+    if (-not $RSAT_MODULE_MAP.ContainsKey($ModuleName)) {
+        throw "Unknown module '$ModuleName'. No RSAT mapping is defined for it."
+    }
+
+    $mapping = $RSAT_MODULE_MAP[$ModuleName]
+    if (-not $mapping.ContainsKey($Type) -or [string]::IsNullOrEmpty($mapping[$Type])) {
+        # In the table, but no entry for this OS install path. Most commonly a
+        # module that ships only as a Server feature (e.g. Hyper-V, ADRMS) and
+        # has no equivalent Windows capability on a Workstation.
+        throw "Module '$ModuleName' is not available via $Type on this system (it may be server-only)."
+    }
+
+    if ($Type -eq 'WindowsFeature') {
+        $null = Install-WindowsFeature -Name $mapping[$Type]
+    }
+    else {
+        # Resolve the exact capability identity (e.g.
+        # 'Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0') from the stable short
+        # name in the map. DISM does accept the short base name directly, but
+        # that relies on undocumented prefix matching and the version suffix
+        # varies by Windows build -- so look it up and pass the canonical name.
+        $capabilityName = $mapping[$Type]
+        $capability = Get-WindowsCapability -Online -Name "$capabilityName*" | Select-Object -First 1
+        if (-not $capability) {
+            throw "No Windows capability matching '$capabilityName' was found on this system."
+        }
+        $null = Add-WindowsCapability -Online -Name $capability.Name
+    }
+}
+
+# Conditional import
+Import-PSDependModule -Name $ModuleName -Action $PSDependAction

PSDepend/Private/Test-Administrator.ps1

@@ -0,0 +1,9 @@
+function Test-Administrator {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param()
+
+    ([Security.Principal.WindowsPrincipal]::new(
+        [Security.Principal.WindowsIdentity]::GetCurrent()
+    )).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}

Tests/WindowsRSAT.Type.Tests.ps1

@@ -0,0 +1,183 @@
+#requires -Module @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+BeforeDiscovery {
+    Import-Module (Join-Path $PSScriptRoot 'Shared/TestHelpers.psm1') -Force
+    $script:SkipUnsupported = -not (Test-PSDependTypeSupportedHere -DependencyType 'WindowsRSAT')
+}
+
+BeforeAll {
+    if (-not $env:BHProjectPath) {
+        & "$PSScriptRoot\..\build.ps1" -Task 'Build'
+    }
+    Remove-Module $env:BHProjectName -ErrorAction SilentlyContinue
+    Import-Module (Join-Path $env:BHProjectPath $env:BHProjectName) -Force
+
+    Import-Module (Join-Path $PSScriptRoot 'Shared/TestHelpers.psm1') -Force
+
+    $script:ScriptPath = Join-Path $env:BHProjectPath 'PSDepend/PSDependScripts/WindowsRSAT.ps1'
+
+    # Inject stub functions for the install-side cmdlets into the PSDepend
+    # module scope so Pester's Mock attaches to a regular PowerShell function
+    # rather than to the underlying CDXML/binary cmdlets. PowerShell resolves
+    # functions before cmdlets in the same scope, so on hosts where the real
+    # cmdlets exist (Windows Server PS 5.1 with ServerManager, Windows client
+    # with DISM) the stub still wins. Mocking the real CDXML cmdlets has been
+    # observed to silently not intercept on Windows PowerShell 5.1 -- the
+    # stub-function approach makes mocking work consistently across PS 5.1,
+    # PS 7, and all platforms.
+    InModuleScope PSDepend {
+        function script:Install-WindowsFeature { [CmdletBinding()] param([string]$Name) }
+        function script:Add-WindowsCapability  { [CmdletBinding()] param([switch]$Online, [string]$Name) }
+        function script:Get-WindowsCapability  { [CmdletBinding()] param([switch]$Online, [string]$Name) }
+    }
+}
+
+Describe 'WindowsRSAT script' -Tag 'WindowsOnly' -Skip:$SkipUnsupported {
+
+    BeforeAll {
+        InModuleScope PSDepend {
+            Mock Get-Module             { } -ParameterFilter { $ListAvailable }
+            Mock Install-WindowsFeature { }
+            Mock Add-WindowsCapability  { }
+            # Mirror the real resolver: the script queries with a 'Rsat.X*'
+            # prefix and the live system returns the full version-suffixed
+            # identity, which is what gets passed to Add-WindowsCapability.
+            Mock Get-WindowsCapability  { [PSCustomObject]@{ Name = ($Name -replace '\*$', '') + '~~~~0.0.1.0'; State = 'NotPresent' } }
+            Mock Get-CimInstance        { [PSCustomObject]@{ ProductType = 3 } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+            Mock Import-PSDependModule  { }
+            Mock Test-Administrator     { $true }
+        }
+    }
+
+    Context 'PSDependAction = Test only' {
+        It 'Returns $false when the module is not installed' {
+            $dep = New-PSDependFixture -DependencyName 'ActiveDirectory' -DependencyType 'WindowsRSAT'
+            $result = InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                & $ScriptPath -Dependency $Dep -PSDependAction Test
+            }
+            $result | Should -Be $false
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 0
+        }
+
+        It 'Returns $true when the module is already available' {
+            InModuleScope PSDepend {
+                Mock Get-Module { [PSCustomObject]@{ Name = 'ActiveDirectory' } } -ParameterFilter { $ListAvailable }
+            }
+            $dep = New-PSDependFixture -DependencyName 'ActiveDirectory' -DependencyType 'WindowsRSAT'
+            $result = InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                & $ScriptPath -Dependency $Dep -PSDependAction Test
+            }
+            $result | Should -Be $true
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+        }
+    }
+
+    Context 'PSDependAction = Install on Server' {
+
+        It 'Dispatches to Install-WindowsFeature with the mapped name (<ModuleName> -> <Feature>)' -TestCases @(
+            @{ ModuleName = 'ActiveDirectory'; Feature = 'RSAT-AD-Powershell' }
+            @{ ModuleName = 'BitLocker';       Feature = 'RSAT-Feature-Tools-BitLocker-RemoteAdminTool' }
+            @{ ModuleName = 'Hyper-V';         Feature = 'RSAT-Hyper-V-Tools' }
+            @{ ModuleName = 'GroupPolicy';     Feature = 'GPMC' }
+        ) {
+            param($ModuleName, $Feature)
+
+            $dep = New-PSDependFixture -DependencyName $ModuleName -DependencyType 'WindowsRSAT'
+            InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                & $ScriptPath -Dependency $Dep -PSDependAction Install
+            }
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 1 -Exactly -ParameterFilter {
+                $Name -eq $Feature
+            }
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 0
+        }
+
+        It 'Throws when the module name is not in the mapping table' {
+            $dep = New-PSDependFixture -DependencyName 'NotARealModule' -DependencyType 'WindowsRSAT'
+            {
+                InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                    & $ScriptPath -Dependency $Dep -PSDependAction Install
+                }
+            } | Should -Throw '*No RSAT mapping*'
+        }
+    }
+
+    Context 'PSDependAction = Install on Workstation' {
+
+        BeforeAll {
+            InModuleScope PSDepend {
+                Mock Get-CimInstance { [PSCustomObject]@{ ProductType = 1 } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+            }
+        }
+
+        It 'Resolves and dispatches to Add-WindowsCapability with the full identity (<ModuleName> -> <Capability>~~~~*)' -TestCases @(
+            @{ ModuleName = 'ActiveDirectory'; Capability = 'Rsat.ActiveDirectory.DS-LDS.Tools' }
+            @{ ModuleName = 'BitLocker';       Capability = 'Rsat.BitLocker.Recovery.Tools' }
+            @{ ModuleName = 'GroupPolicy';     Capability = 'Rsat.GroupPolicy.Management.Tools' }
+            @{ ModuleName = 'DNSServer';       Capability = 'Rsat.Dns.Tools' }
+        ) {
+            param($ModuleName, $Capability)
+
+            $dep = New-PSDependFixture -DependencyName $ModuleName -DependencyType 'WindowsRSAT'
+            InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                & $ScriptPath -Dependency $Dep -PSDependAction Install
+            }
+            # Script must look the capability up by prefix...
+            Should -Invoke -CommandName Get-WindowsCapability -ModuleName PSDepend -Times 1 -Exactly -ParameterFilter {
+                $Name -eq "$Capability*"
+            }
+            # ...and install the full version-suffixed identity it returns, not the short name.
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 1 -Exactly -ParameterFilter {
+                $Name -eq "$Capability~~~~0.0.1.0"
+            }
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+        }
+
+        It 'Throws a clear server-only error for modules with no capability mapping (<ModuleName>)' -TestCases @(
+            @{ ModuleName = 'Hyper-V' }
+            @{ ModuleName = 'ADRMS' }
+        ) {
+            param($ModuleName)
+
+            $dep = New-PSDependFixture -DependencyName $ModuleName -DependencyType 'WindowsRSAT'
+            {
+                InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                    & $ScriptPath -Dependency $Dep -PSDependAction Install
+                }
+            } | Should -Throw '*not available*server-only*'
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 0
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+        }
+    }
+
+    Context 'PSDependAction = Install gated by admin check' {
+        It 'Throws when Test-Administrator returns $false' {
+            InModuleScope PSDepend {
+                Mock Test-Administrator { $false }
+            }
+            $dep = New-PSDependFixture -DependencyName 'ActiveDirectory' -DependencyType 'WindowsRSAT'
+            {
+                InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                    & $ScriptPath -Dependency $Dep -PSDependAction Install
+                }
+            } | Should -Throw '*elevated session*'
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 0
+        }
+    }
+
+    Context 'PSDependAction = Test, Install short-circuits when installed' {
+        It 'Skips Install when the module is already available' {
+            InModuleScope PSDepend {
+                Mock Get-Module { [PSCustomObject]@{ Name = 'ActiveDirectory' } } -ParameterFilter { $ListAvailable }
+            }
+            $dep = New-PSDependFixture -DependencyName 'ActiveDirectory' -DependencyType 'WindowsRSAT'
+            InModuleScope PSDepend -Parameters @{ Dep = $dep; ScriptPath = $script:ScriptPath } {
+                & $ScriptPath -Dependency $Dep -PSDependAction Test, Install
+            }
+            Should -Invoke -CommandName Install-WindowsFeature -ModuleName PSDepend -Times 0
+            Should -Invoke -CommandName Add-WindowsCapability  -ModuleName PSDepend -Times 0
+        }
+    }
+}