Edit

Share via

Install or uninstall a Windows feature

  • Article

Description

This example shows how you can use the WindowsFeature resource to ensure a Windows Feature is:

  • Installed or uninstalled
  • Whether it's installed with its subfeatures
  • Whether it's installed as a specific account

All the resource's values are user-provided, not hard-coded. The parameters map to the resource's properties, changing its behavior.

Name

If you don't specify the Name parameter, the resource's Name property is set to Telnet-Client. This the Windows feature the resource installs or uninstalls.

Ensure

If you don't specify the Ensure parameter, the resource's Ensure property is set to Present and the resource installs the Windows feature if it isn't already installed.

If you specify Ensure as Absent, the resource uninstalls the Windows feature if it's installed.

IncludeAllSubFeature

If you don't specify the IncludeAllSubFeature parameter, the resource's IncludeAllSubFeature property is set to $false and the resource doesn't install the Windows feature's subfeatures if Ensure is set to Present.

If Ensure is set to Absent, the resource always uninstalls the subfeatures for any Windows feature it removes.

Credential

If you don't specify the Credential parameter, the resource doesn't set the Credential property and installs or uninstalls of the Windows feature under the default account.

LogPath

If you don't specify the LogPath parameter, the resource doesn't set the LogPath property and doesn't write the logs for installing or uninstalling the Windows feature to a file.

With Invoke-DscResource

This script shows how you can use the WindowsFeature resource with the Invoke-DscResource cmdlet to ensure a Windows Feature is installed or installed with user-provided settings.

By default, it ensures the Telnet-Client Windows feature is installed without subfeatures and doesn't write the installation logs to a file.

[CmdletBinding()]
param(
    [System.String]
    $Name = 'Telnet-Client',

    [ValidateSet('Present', 'Absent')]
    [System.String]
    $Ensure = 'Present',

    [System.Boolean]
    $IncludeAllSubFeature = $false,

    [System.Management.Automation.PSCredential]
    [System.Management.Automation.Credential()]
    $Credential,

    [ValidateNotNullOrEmpty()]
    [System.String]
    $LogPath
)

begin {
    $SharedParameters = @{
        Name       = 'WindowsFeature'
        ModuleName = 'PSDscResource'
        Properties = @{
            Name                 = $Name
            Ensure               = $Ensure
            IncludeAllSubFeature = $IncludeAllSubFeature
        }
    }

    $NonGetProperties = @(
        'Ensure'
        'IncludeAllSubFeature'
    )
}

process {
    if ($PSBoundParameters.ContainsKey('Credential')) {
        $SharedParameters.Properties.Credential = $Credential
        $NonGetProperties += 'Credential'
    }

    if ($PSBoundParameters.ContainsKey('LogPath')) {
        $SharedParameters.Properties.LogPath = $LogPath
        $NonGetProperties += 'LogPath'
    }

    $TestResult = Invoke-DscResource -Method Test @SharedParameters

    if ($TestResult.InDesiredState) {
        $QueryParameters = $SharedParameters.Clone()

        foreach ($Property in $NonGetProperties) {
            $QueryParameters.Properties.Remove($Property)
        }

        Invoke-DscResource -Method Get @QueryParameters
    } else {
        Invoke-DscResource -Method Set @SharedParameters
    }
}

With a Configuration

This snippet shows how you can define a Configuration with a WindowsFeature resource block to ensure a Windows Feature is installed or installed with user-provided settings.

By default, it ensures the Telnet-Client Windows feature is installed without subfeatures and doesn't write the installation logs to a file.

Important

There's a limitation in machine configuration that prevents a DSC Resource from using any PowerShell cmdlets not included in PowerShell itself or in a module on the PowerShell Gallery. This example is provided for demonstrative purposes, but because the DSC Resource uses cmdlets from the DISM module, which ships as one of the Windows modules, it won't work in machine configuration.

Configuration Example {
    param(
        [System.String]
        $Name = 'Telnet-Client',

        [ValidateSet('Present', 'Absent')]
        [System.String]
        $Ensure = 'Present',

        [System.Boolean]
        $IncludeAllSubFeature = $false,

        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential,

        [ValidateNotNullOrEmpty()]
        [System.String]
        $LogPath
    )

    Import-DscResource -ModuleName 'PSDscResources'

    $HasCredential = $null -ne $Credential
    $HasLogPath = ![string]::IsNullOrEmpty($LogPath)

    Node Localhost {
        if ($HasCredential -and $HasLogPath) {
            WindowsFeature ExampleWindowsFeature {
                Name                 = $Name
                Ensure               = $Ensure
                IncludeAllSubFeature = $IncludeAllSubFeature
                Credential           = $Credential
                LogPath              = $LogPath
            }
        } elseif ($HasCredential) {
            WindowsFeature ExampleWindowsFeature {
                Name                 = $Name
                Ensure               = $Ensure
                IncludeAllSubFeature = $IncludeAllSubFeature
                Credential           = $Credential
            }
        } elseif ($HasLogPath) {
            WindowsFeature ExampleWindowsFeature {
                Name                 = $Name
                Ensure               = $Ensure
                IncludeAllSubFeature = $IncludeAllSubFeature
                LogPath              = $LogPath
            }
        } else {
            WindowsFeature ExampleWindowsFeature {
                Name                 = $Name
                Ensure               = $Ensure
                IncludeAllSubFeature = $IncludeAllSubFeature
            }
        }
    }
}