Install or uninstall a Windows feature
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
}
}
}
}