From f96262bf38f01f26aee56a30bbc1277eadcc430a Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Tue, 21 Apr 2026 07:05:58 +0200 Subject: [PATCH 1/2] Add `dism_dsc` reference documentation --- .../examples/export-features-on-demand.md | 151 +++++++ .../examples/get-feature-on-demand.md | 139 +++++++ .../install-remove-feature-on-demand.md | 167 ++++++++ .../Windows/FeatureOnDemandList/index.md | 380 ++++++++++++++++++ .../enable-disable-optional-features.md | 198 +++++++++ .../examples/export-optional-features.md | 144 +++++++ .../examples/get-optional-feature.md | 117 ++++++ .../Windows/OptionalFeatureList/index.md | 367 +++++++++++++++++ docs/reference/resources/overview.md | 4 + 9 files changed, 1667 insertions(+) create mode 100644 docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/export-features-on-demand.md create mode 100644 docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/get-feature-on-demand.md create mode 100644 docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md create mode 100644 docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md create mode 100644 docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md create mode 100644 docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md create mode 100644 docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md create mode 100644 docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md diff --git a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/export-features-on-demand.md b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/export-features-on-demand.md new file mode 100644 index 000000000..7bffc721a --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/export-features-on-demand.md @@ -0,0 +1,151 @@ +--- +description: > + Examples showing how to export and filter Windows Features on Demand (capabilities) using the + Microsoft.Windows/FeatureOnDemandList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Export Features on Demand +--- + +# Export Features on Demand + +This example shows how you can use the `Microsoft.Windows/FeatureOnDemandList` resource to +enumerate Windows Features on Demand (capabilities) on a system, optionally filtering the results +by identity, state, display name, or description. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/FeatureOnDemandList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +## Export all capabilities + +To retrieve a complete list of all capabilities on the system, use the [dsc resource export][01] +command without any input. + +```powershell +dsc resource export --resource Microsoft.Windows/FeatureOnDemandList +``` + +DSC returns a configuration document that includes all capabilities and their current states: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/FeatureOnDemandList + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + - identity: OpenSSH.Server~~~~0.0.1.0 + state: NotPresent + - identity: Language.Basic~~~en-US~0.0.1.0 + state: Installed + # ... additional capabilities +``` + +> [!NOTE] +> When exporting without filters, the resource uses a fast enumeration path that returns only +> `identity` and `state` for each capability. To retrieve additional properties such as +> `displayName`, `description`, `downloadSize`, and `installSize`, use an export filter as shown +> in the examples below. + +## Export only installed capabilities + +To list only the capabilities currently installed on the system, provide a filter with +`state: Installed`. + +```powershell +$filter = @{ + capabilities = @( + @{ state = 'Installed' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/FeatureOnDemandList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/FeatureOnDemandList + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + - identity: Language.Basic~~~en-US~0.0.1.0 + state: Installed + # ... additional installed capabilities +``` + +## Export capabilities by identity pattern + +You can filter capabilities by identity using wildcard (`*`) patterns. The match is +case-insensitive. + +```powershell +$filter = @{ + capabilities = @( + @{ identity = 'OpenSSH*' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/FeatureOnDemandList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/FeatureOnDemandList + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + - identity: OpenSSH.Server~~~~0.0.1.0 + state: NotPresent +``` + +## Export capabilities with full details + +To retrieve full details including `displayName`, `description`, `downloadSize`, and +`installSize`, include those properties as filters. A wildcard (`*`) in a filter property matches +all values for that field and triggers the full-info lookup. + +```powershell +$filter = @{ + capabilities = @( + @{ + identity = 'OpenSSH*' + displayName = '*' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/FeatureOnDemandList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/FeatureOnDemandList + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 0 + installSize: 4894720 + - identity: OpenSSH.Server~~~~0.0.1.0 + state: NotPresent + displayName: OpenSSH Server + description: Open SSH-based secure shell (SSH) server... + downloadSize: 1468500 + installSize: 1839104 +``` + + +[01]: ../../../../../../cli/resource/export.md diff --git a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/get-feature-on-demand.md b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/get-feature-on-demand.md new file mode 100644 index 000000000..22726039f --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/get-feature-on-demand.md @@ -0,0 +1,139 @@ +--- +description: > + Examples showing how to retrieve the current state of Windows features on demand (capabilities) + using the Microsoft.Windows/FeatureOnDemandList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Get feature on demand state +--- + +# Get feature on demand state + +This example shows how you can use the `Microsoft.Windows/FeatureOnDemandList` resource to +retrieve the current state of Windows features on demand (capabilities). The examples use +`OpenSSH.Client~~~~0.0.1.0` as a representative capability identity. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/FeatureOnDemandList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +## Find capability identity strings + +Before you can get the state of a capability, you need its identity string. Use the following +command to list all capabilities and their identities: + +```powershell +dism /Online /Get-Capabilities /Format:Table +``` + +Capability identities follow the format `CapabilityName~~~~LanguageTag~Version`, for example: + +- `OpenSSH.Client~~~~0.0.1.0` +- `OpenSSH.Server~~~~0.0.1.0` +- `Language.Basic~~~en-US~0.0.1.0` + +## Get a single capability + +The following snippet shows how to retrieve the state of the OpenSSH client capability using the +[dsc resource get][01] command. + +```powershell +$instance = @{ + capabilities = @( + @{ identity = 'OpenSSH.Client~~~~0.0.1.0' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +When the capability is installed, DSC returns output similar to the following: + +```yaml +actualState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + displayName: OpenSSH Client + description: >- + Open SSH-based secure shell (SSH) client, required for secure key management and access + to remote machines. + downloadSize: 0 + installSize: 4894720 +``` + +When the capability is not installed, the `state` field reads `NotPresent`: + +```yaml +actualState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: NotPresent + displayName: OpenSSH Client + description: >- + Open SSH-based secure shell (SSH) client, required for secure key management and access + to remote machines. + downloadSize: 4026000 + installSize: 4894720 +``` + +## Get multiple capabilities in a single request + +You can retrieve the state of multiple capabilities in a single call by including multiple entries +in the `capabilities` array. + +```powershell +$instance = @{ + capabilities = @( + @{ identity = 'OpenSSH.Client~~~~0.0.1.0' } + @{ identity = 'OpenSSH.Server~~~~0.0.1.0' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +```yaml +actualState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 0 + installSize: 4894720 + - identity: OpenSSH.Server~~~~0.0.1.0 + state: NotPresent + displayName: OpenSSH Server + description: Open SSH-based secure shell (SSH) server... + downloadSize: 1468500 + installSize: 1839104 +``` + +## Get a non-existent capability + +When you request a capability identity that is not recognized by DISM, the resource returns +`_exist: false` instead of raising an error. + +```powershell +$instance = @{ + capabilities = @( + @{ identity = 'NonExistent.Capability~~~~0.0.1.0' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +```yaml +actualState: + capabilities: + - identity: NonExistent.Capability~~~~0.0.1.0 + _exist: false +``` + +The `_exist: false` response indicates the capability identity is not recognized by DISM on this +system. + + +[01]: ../../../../../../cli/resource/get.md diff --git a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md new file mode 100644 index 000000000..07ca6ca1b --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md @@ -0,0 +1,167 @@ +--- +description: > + Examples showing how to install and remove Windows features on demand (capabilities) using the + Microsoft.Windows/FeatureOnDemandList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Install and remove features on demand +--- + +# Install and remove features on demand + +This example shows how you can use the `Microsoft.Windows/FeatureOnDemandList` resource to install +and remove Windows features on demand (capabilities). The examples use +`OpenSSH.Client~~~~0.0.1.0` as a representative capability identity. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/FeatureOnDemandList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +> [!NOTE] +> Installing a capability may require internet access or an appropriately configured Windows Update +> or WSUS source. Installing large capabilities may take several minutes to complete. + +## Install a capability + +To install a capability, set its `state` to `Installed` and use the [dsc resource set][01] +command. + +```powershell +$instance = @{ + capabilities = @( + @{ + identity = 'OpenSSH.Client~~~~0.0.1.0' + state = 'Installed' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +When the resource installs the capability, DSC returns the updated state: + +```yaml +beforeState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: NotPresent + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 4026000 + installSize: 4894720 +afterState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 0 + installSize: 4894720 +changedProperties: +- capabilities +``` + +If a system restart is required to complete the installation, the response includes a +`_restartRequired` property at the top level: + +```yaml +afterState: + _restartRequired: + - system: MYCOMPUTER + capabilities: + - identity: SomeCapability~~~~0.0.1.0 + state: InstallPending + ... +changedProperties: +- capabilities +``` + +## Remove a capability + +To remove a capability, set its `state` to `NotPresent` and use the [dsc resource set][01] command. + +```powershell +$instance = @{ + capabilities = @( + @{ + identity = 'OpenSSH.Client~~~~0.0.1.0' + state = 'NotPresent' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +```yaml +beforeState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 0 + installSize: 4894720 +afterState: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: NotPresent + displayName: OpenSSH Client + description: Open SSH-based secure shell (SSH) client... + downloadSize: 4026000 + installSize: 4894720 +changedProperties: +- capabilities +``` + +## Manage multiple capabilities in a single operation + +You can install or remove multiple capabilities in a single **Set** call by specifying multiple +entries in the `capabilities` array. The resource processes each entry independently. + +```powershell +$instance = @{ + capabilities = @( + @{ + identity = 'OpenSSH.Client~~~~0.0.1.0' + state = 'Installed' + } + @{ + identity = 'OpenSSH.Server~~~~0.0.1.0' + state = 'NotPresent' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/FeatureOnDemandList --input $instance +``` + +## Use in a configuration document + +You can also use the resource in a DSC configuration document to declaratively manage capabilities +across a system. + +```yaml +# features-on-demand.config.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Manage OpenSSH capabilities + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed + - identity: OpenSSH.Server~~~~0.0.1.0 + state: NotPresent +``` + +Apply the configuration with the [dsc config set][02] command: + +```powershell +dsc config set --file ./features-on-demand.config.dsc.yaml +``` + + +[01]: ../../../../../../cli/resource/set.md +[02]: ../../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md new file mode 100644 index 000000000..1e5e0bbde --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md @@ -0,0 +1,380 @@ +--- +description: Microsoft.Windows/FeatureOnDemandList resource reference documentation +ms.date: 04/21/2026 +ms.topic: reference +title: Microsoft.Windows/FeatureOnDemandList +--- + +# Microsoft.Windows/FeatureOnDemandList + +## Synopsis + +Manage Windows features on demand (capabilities) using the DISM API. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows, dism, capability, featureondemand, fod] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/FeatureOnDemandList + properties: + # Required properties + capabilities: + - identity: string + # Instance properties + state: Installed | NotPresent +``` + +## Description + +The `Microsoft.Windows/FeatureOnDemandList` resource enables you to idempotently manage Windows +features on demand (also known as capabilities) using the DISM API. Features on demand are optional +Windows components that are not part of the base OS image and may need to be downloaded from +Windows Update or a local source before use. Examples include language packs, accessibility tools, +the OpenSSH client and server, and developer tools like the RSAT (Remote Server Administration +Tools) suite. + +The resource can: + +- Retrieve the current state of one or more capabilities by identity. +- Install capabilities (`Installed`), downloading them from Windows Update if necessary. +- Remove capabilities from the system (`NotPresent`). +- Export a list of all capabilities on the system, optionally filtered by identity, state, display + name, or description. + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- All operations require an elevated (administrator) process context. +- Installing capabilities may require internet access or a configured Windows Update / WSUS source. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of one or more capability + instances. +- `set` - You can use the resource to enforce the desired state for one or more capability + instances. +- `export` - You can use the resource to enumerate all capabilities on the system, with optional + filtering. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][01]. + +## Examples + +1. [Get feature on demand state][02] - Shows how to retrieve the current state of a Windows + capability. +1. [Install and remove features on demand][03] - Shows how to install and remove Windows + capabilities using the `dsc resource set` command. +1. [Export features on demand][04] - Shows how to enumerate all capabilities on the system, with + and without filters. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. + + - [capabilities](#capabilities) - An array of capability entries. + +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][05]. + + - [_restartRequired](#_restartrequired) - Indicates that a system restart is required to complete + the state change. + +### capabilities + +
Expand for capabilities property metadata + +```yaml +Type : array +IsRequired : true +IsKey : false +IsReadOnly : false +``` + +
+ +An array of capability entries. Each entry is an object describing a Windows capability (Feature on +Demand). For the **Get** operation, each entry must specify [`identity`](#identity). For the **Set** +operation, each entry must specify both [`identity`](#identity) and [`state`](#state). For the +**Export** operation, the array is optional and each entry can filter results using +[`identity`](#identity), [`state`](#state), [`displayName`](#displayname), or +[`description`](#description) with wildcard support. + +Each entry in `capabilities` has the following properties: + +- [identity](#identity) - The identity string of the capability. +- [_exist](#_exist) - Indicates whether the capability is recognized by DISM. +- [state](#state) - The current or desired state of the capability. +- [displayName](#displayname) - The display name of the capability. +- [description](#description) - The description of the capability. +- [downloadSize](#downloadsize) - The download size of the capability in bytes. +- [installSize](#installsize) - The install size of the capability in bytes. + +#### identity + +
Expand for capabilities[*].identity property metadata + +```yaml +Type : string +IsRequired : true (get, set) / false (export) +IsKey : false +IsReadOnly : false +``` + +
+ +The identity string that uniquely identifies the Windows capability. For **Get** and **Set** +operations, this property is required for each entry. For **Export** operations, it's optional and +supports wildcard (`*`) patterns for case-insensitive filtering. + +Capability identities typically follow the format `CapabilityName~~~~LanguageTag~Version`, for +example `OpenSSH.Client~~~~0.0.1.0` or `Language.Basic~~~en-US~0.0.1.0`. + +Use the `dism /Online /Get-Capabilities` command to list available capability identities on your +system. + +#### _exist + +
Expand for capabilities[*]._exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +Indicates whether the capability exists on the system. The resource sets this property to `false` +in the **Get** response when the requested `identity` is not recognized by DISM. When `_exist` is +`false`, the `state`, `displayName`, `description`, `downloadSize`, and `installSize` properties +are not returned. + +#### state + +
Expand for capabilities[*].state property metadata + +```yaml +Type : string +IsRequired : true (set) / false (get, export) +IsKey : false +IsReadOnly : false (set input) / true (get/export output) +ValidValues : [NotPresent, UninstallPending, Staged, Removed, Installed, + InstallPending, Superseded, PartiallyInstalled] +SetValues : [Installed, NotPresent] +``` + +
+ +The state of the capability. **Get** and **Export** operations return one of the eight DISM +capability state values. **Set** operations accept only the following two values as desired state: + +| Value | Description | +|:-------------|:-------------------------------------------------------------------------------| +| `Installed` | The capability is installed. The resource installs it if not already present. | +| `NotPresent` | The capability is removed from the system. | + +The following table describes all possible state values returned by **Get** and **Export**: + +| Value | Description | +|:---------------------|:--------------------------------------------------------------------------| +| `NotPresent` | The capability is not installed and not staged. | +| `UninstallPending` | A removal operation is pending, requiring a restart to complete. | +| `Staged` | The capability payload is on disk but the capability is not installed. | +| `Removed` | The capability has been removed. | +| `Installed` | The capability is fully installed and operational. | +| `InstallPending` | An install operation is pending, requiring a restart to complete. | +| `Superseded` | The capability has been replaced by another component. | +| `PartiallyInstalled` | The capability is only partially installed. | + +#### displayName + +
Expand for capabilities[*].displayName property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +The human-readable display name of the capability. This property is returned by **Get** and +**Export** operations. For **Export** operations, you can specify this property as a filter value +with wildcard (`*`) support for case-insensitive matching. + +#### description + +
Expand for capabilities[*].description property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +A brief description of the capability. This property is returned by **Get** and **Export** +operations. For **Export** operations, you can specify this property as a filter value with +wildcard (`*`) support for case-insensitive matching. + +#### downloadSize + +
Expand for capabilities[*].downloadSize property metadata + +```yaml +Type : integer +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +The size in bytes that must be downloaded to install the capability. This property is returned by +**Get** and **Export** operations. + +#### installSize + +
Expand for capabilities[*].installSize property metadata + +```yaml +Type : integer +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +The size in bytes that the capability occupies on disk after installation. This property is returned +by **Get** and **Export** operations. + +### _restartRequired + +
Expand for _restartRequired property metadata + +```yaml +Type : array +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +Returned at the top level of the **Set** operation response when DISM reports that a system restart +is required to complete the requested state changes. Each entry in the array is an object with a +`system` property containing the name of the computer. + +When no restart is required, this property is omitted from the response. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": ["capabilities"], + "additionalProperties": false, + "properties": { + "_restartRequired": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "capabilities": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "identity": { "type": "string" }, + "_exist": { "type": "boolean" }, + "state": { + "type": "string", + "enum": [ + "NotPresent", "UninstallPending", "Staged", "Removed", + "Installed", "InstallPending", "Superseded", "PartiallyInstalled" + ] + }, + "displayName": { "type": "string" }, + "description": { "type": "string" }, + "downloadSize": { "type": "integer" }, + "installSize": { "type": "integer" } + } + } + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. The resource writes the result JSON to +stdout. + +### Exit code 1 + +Indicates the resource operation failed. The resource writes a descriptive error message to stderr. +Common causes include: + +- The `capabilities` array is empty. +- The `identity` property is missing from a capability entry in a **Get** or **Set** operation. +- The `state` property is missing from a capability entry in a **Set** operation. +- The desired `state` value is not one of the accepted **Set** values (`Installed`, `NotPresent`). +- The requested capability `identity` is not recognized by DISM. +- The DISM API returned an error while querying or modifying capability state. +- The process is not running with elevated privileges. + +## See also + +- [Microsoft.Windows/OptionalFeatureList resource][06] +- [Windows features on demand documentation][07] + + +[01]: ../../../../../concepts/resources/capabilities.md +[02]: ./examples/get-feature-on-demand.md +[03]: ./examples/install-remove-feature-on-demand.md +[04]: ./examples/export-features-on-demand.md +[05]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[06]: ../OptionalFeatureList/index.md +[07]: /windows-hardware/manufacture/desktop/features-on-demand-v2--capabilities diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md new file mode 100644 index 000000000..14c654c66 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md @@ -0,0 +1,198 @@ +--- +description: > + Examples showing how to enable and disable Windows Optional features using the + Microsoft.Windows/OptionalFeatureList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Enable and disable optional features +--- + +# Enable and disable optional features + +This example shows how you can use the `Microsoft.Windows/OptionalFeatureList` resource to enable +and disable Windows Optional features on a system. The examples use `TelnetClient` as a +representative feature name. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/OptionalFeatureList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +## Enable an optional feature + +To enable an optional feature, set its `state` to `Installed` and use the [dsc resource set][01] +command. + +```powershell +$instance = @{ + features = @( + @{ + featureName = 'TelnetClient' + state = 'Installed' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +When the resource enables the feature, DSC returns the updated state: + +```yaml +beforeState: + features: + - featureName: TelnetClient + state: Disabled + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +afterState: + features: + - featureName: TelnetClient + state: Installed + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +changedProperties: +- features +``` + +If a system restart is required to complete the operation, the response includes a +`_restartRequired` property at the top level: + +```yaml +afterState: + _restartRequired: + - system: MYCOMPUTER + features: + - featureName: SomeFeature + state: InstallPending + ... +changedProperties: +- features +``` + +## Disable an optional feature (keep payload staged) + +To disable a feature while keeping the feature payload on disk (so it can be re-enabled quickly +without source media), set `state` to `NotPresent`. + +```powershell +$instance = @{ + features = @( + @{ + featureName = 'TelnetClient' + state = 'NotPresent' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +```yaml +beforeState: + features: + - featureName: TelnetClient + state: Installed + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +afterState: + features: + - featureName: TelnetClient + state: Disabled + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +changedProperties: +- features +``` + +## Disable an optional feature and remove its payload + +To disable a feature and completely remove its payload from disk, set `state` to `Removed`. This +frees disk space but requires source media (or Windows Update access) to re-enable the feature +later. + +```powershell +$instance = @{ + features = @( + @{ + featureName = 'TelnetClient' + state = 'Removed' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +```yaml +beforeState: + features: + - featureName: TelnetClient + state: Installed + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +afterState: + features: + - featureName: TelnetClient + state: Removed + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +changedProperties: +- features +``` + +## Manage multiple features in a single operation + +You can enable or disable multiple features in a single **Set** call by specifying multiple entries +in the `features` array. + +```powershell +$instance = @{ + features = @( + @{ + featureName = 'TelnetClient' + state = 'Installed' + } + @{ + featureName = 'TFTP' + state = 'NotPresent' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource set --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +## Use in a configuration document + +You can also use the resource in a DSC configuration document to declaratively manage optional +features across a system. + +```yaml +# optional-features.config.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Enable Telnet Client + type: Microsoft.Windows/OptionalFeatureList + properties: + features: + - featureName: TelnetClient + state: Installed + - featureName: TFTP + state: NotPresent +``` + +Apply the configuration with the [dsc config set][02] command: + +```powershell +dsc config set --file ./optional-features.config.dsc.yaml +``` + + +[01]: ../../../../../../cli/resource/set.md +[02]: ../../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md new file mode 100644 index 000000000..578feceb6 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md @@ -0,0 +1,144 @@ +--- +description: > + Examples showing how to export and filter Windows Optional features using the + Microsoft.Windows/OptionalFeatureList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Export optional features +--- + +# Export optional features + +This example shows how you can use the `Microsoft.Windows/OptionalFeatureList` resource to +enumerate Windows Optional features on a system, optionally filtering the results by name, state, +display name, or description. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/OptionalFeatureList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +## Export all optional features + +To retrieve a complete list of all optional features on the system, use the [dsc resource export][01] +command without any input. + +```powershell +dsc resource export --resource Microsoft.Windows/OptionalFeatureList +``` + +DSC returns a configuration document that includes all optional features and their current states: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/OptionalFeatureList + type: Microsoft.Windows/OptionalFeatureList + properties: + features: + - featureName: TFTP + state: Disabled + - featureName: TelnetClient + state: Disabled + - featureName: Containers-DisposableClientVM + state: Disabled + # ... additional features +``` + +> [!NOTE] +> When exporting without filters, the resource uses a fast enumeration path that returns only +> `featureName` and `state` for each feature. To retrieve additional properties such as +> `displayName` and `description`, use an export filter as shown in the examples below. + +## Export only installed features + +To list only the features that are currently enabled, provide a filter with `state: Installed`. + +```powershell +$filter = @{ + features = @( + @{ state = 'Installed' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/OptionalFeatureList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/OptionalFeatureList + type: Microsoft.Windows/OptionalFeatureList + properties: + features: + - featureName: NetFx4-AdvSrvs + state: Installed + - featureName: WCF-Services45 + state: Installed + # ... additional installed features +``` + +## Export features by name pattern + +You can filter features by name using wildcard (`*`) patterns. The match is case-insensitive. + +```powershell +$filter = @{ + features = @( + @{ featureName = 'Hyper-V*' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/OptionalFeatureList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/OptionalFeatureList + type: Microsoft.Windows/OptionalFeatureList + properties: + features: + - featureName: Microsoft-Hyper-V + state: Installed + - featureName: Microsoft-Hyper-V-Management-Clients + state: Installed + - featureName: Microsoft-Hyper-V-Management-PowerShell + state: Installed + - featureName: Microsoft-Hyper-V-Tools-All + state: Installed +``` + +## Export features with full details + +To retrieve full details including `displayName` and `description`, include those properties as +filters. An empty string (`""`) or a wildcard (`*`) matches all values for that field. + +```powershell +$filter = @{ + features = @( + @{ + featureName = 'TelnetClient' + displayName = '*' + } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource export --resource Microsoft.Windows/OptionalFeatureList --input $filter +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.Windows/OptionalFeatureList + type: Microsoft.Windows/OptionalFeatureList + properties: + features: + - featureName: TelnetClient + state: Disabled + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +``` + + +[01]: ../../../../../../cli/resource/export.md diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md new file mode 100644 index 000000000..d69364f08 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md @@ -0,0 +1,117 @@ +--- +description: > + Examples showing how to retrieve the current state of Windows Optional Features using the + Microsoft.Windows/OptionalFeatureList resource. +ms.date: 04/21/2026 +ms.topic: reference +title: Get optional feature state +--- + +# Get optional feature state + +This example shows how you can use the `Microsoft.Windows/OptionalFeatureList` resource to retrieve +the current state of Windows Optional Features. The examples use `TelnetClient` as a +representative feature name. + +> [!IMPORTANT] +> All operations with `Microsoft.Windows/OptionalFeatureList` require an elevated (administrator) +> session. Run your terminal as administrator before executing these commands. + +## Get a single feature + +The following snippet shows how to retrieve the state of the `TelnetClient` feature using the +[dsc resource get][01] command. + +```powershell +$instance = @{ + features = @( + @{ featureName = 'TelnetClient' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +When the feature is disabled, DSC returns output similar to the following: + +```yaml +actualState: + features: + - featureName: TelnetClient + state: Disabled + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +``` + +When the feature is enabled, the `state` field reads `Installed`: + +```yaml +actualState: + features: + - featureName: TelnetClient + state: Installed + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No +``` + +## Get multiple features in a single request + +You can retrieve the state of multiple features in a single call by including multiple entries in +the `features` array. + +```powershell +$instance = @{ + features = @( + @{ featureName = 'TelnetClient' } + @{ featureName = 'TFTP' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +DSC returns the state of all requested features in a single response: + +```yaml +actualState: + features: + - featureName: TelnetClient + state: Disabled + displayName: Telnet Client + description: Includes Telnet Client + restartRequired: No + - featureName: TFTP + state: Disabled + displayName: TFTP Client + description: Includes TFTP Client + restartRequired: No +``` + +## Get a non-existent feature + +When you request a feature name that is not recognized by DISM, the resource returns `_exist: false` +instead of raising an error. + +```powershell +$instance = @{ + features = @( + @{ featureName = 'NonExistent-Feature-XYZ' } + ) +} | ConvertTo-Json -Depth 3 + +dsc resource get --resource Microsoft.Windows/OptionalFeatureList --input $instance +``` + +```yaml +actualState: + features: + - featureName: NonExistent-Feature-XYZ + _exist: false +``` + +The `_exist: false` response indicates the feature name is not recognized by DISM on this system. + + +[01]: ../../../../../../cli/resource/get.md diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md new file mode 100644 index 000000000..3f769bc4c --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md @@ -0,0 +1,367 @@ +--- +description: Microsoft.Windows/OptionalFeatureList resource reference documentation +ms.date: 04/21/2026 +ms.topic: reference +title: Microsoft.Windows/OptionalFeatureList +--- + +# Microsoft.Windows/OptionalFeatureList + +## Synopsis + +Manage Windows Optional features using the DISM API. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows, dism, optionalfeature, feature] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/OptionalFeatureList + properties: + # Required properties + features: + - featureName: string + # Instance properties + state: Installed | NotPresent | Removed +``` + +## Description + +The `Microsoft.Windows/OptionalFeatureList` resource enables you to idempotently manage Windows +Optional features using the DISM API. Optional features are components built into Windows that can +be enabled or disabled without downloading additional content. Examples include Hyper-V, +Windows Subsystem for Linux, and Internet Information Services (IIS). + +The resource can: + +- Retrieve the current state of one or more optional features by name. +- Enable optional features (`Installed`). +- Disable optional features while keeping the feature payload staged (`NotPresent`). +- Disable optional features and remove the associated payload from the system (`Removed`). +- Export a list of all optional features on the system, optionally filtered by name, state, display + name, or description. + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- All operations require an elevated (administrator) process context. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of one or more optional feature + instances. +- `set` - You can use the resource to enforce the desired state for one or more optional feature + instances. +- `export` - You can use the resource to enumerate all optional features on the system, with + optional filtering. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][01]. + +## Examples + +1. [Get optional feature state][02] - Shows how to retrieve the current state of a Windows + Optional Feature. +1. [Enable and disable optional features][03] - Shows how to enable and disable Windows Optional + Features using the `dsc resource set` command. +1. [Export optional features][04] - Shows how to enumerate all optional features on the system, + with and without filters. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. + + - [features](#features) - An array of optional feature entries. + +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][05]. + + - [_restartRequired](#_restartrequired) - Indicates that a system restart is required to complete + the state change. + +### features + +
Expand for features property metadata + +```yaml +Type : array +IsRequired : true +IsKey : false +IsReadOnly : false +``` + +
+ +An array of optional feature entries. Each entry is an object describing a Windows Optional Feature. +For the **Get** operation, each entry must specify [`featureName`](#featurename). For the **Set** +operation, each entry must specify both [`featureName`](#featurename) and [`state`](#state). For +the **Export** operation, the array is optional and each entry can filter results using +[`featureName`](#featurename), [`state`](#state), [`displayName`](#displayname), or +[`description`](#description) with wildcard support. + +Each entry in `features` has the following properties: + +- [featureName](#featurename) - The name of the optional feature. +- [_exist](#_exist) - Indicates whether the feature is recognized by DISM. +- [state](#state) - The current or desired state of the feature. +- [displayName](#displayname) - The display name of the feature. +- [description](#description) - The description of the feature. +- [restartRequired](#restartrequired) - Whether a restart is required after a state change. + +#### featureName + +
Expand for features[*].featureName property metadata + +```yaml +Type : string +IsRequired : true (get, set) / false (export) +IsKey : false +IsReadOnly : false +``` + +
+ +The name of the Windows Optional Feature. For **Get** and **Set** operations, this property is +required for each entry. For the **Export** operation, it's optional and supports wildcard (`*`) +patterns for case-insensitive filtering. + +Use the `dism /Online /Get-Features` command to list available feature names on your system. + +#### _exist + +
Expand for features[*]._exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +Indicates whether the feature exists on the system. The resource sets this property to `false` in +the **Get** response when the requested `featureName` is not recognized by DISM. When `_exist` is +`false`, the `state`, `displayName`, `description`, and `restartRequired` properties are not +returned. + +#### state + +
Expand for features[*].state property metadata + +```yaml +Type : string +IsRequired : true (set) / false (get, export) +IsKey : false +IsReadOnly : false (set input) / true (get/export output) +ValidValues : [NotPresent, UninstallPending, Staged, Removed, Installed, + InstallPending, Superseded, PartiallyInstalled] +SetValues : [Installed, NotPresent, Removed] +``` + +
+ +The state of the optional feature. **Get** and **Export** operations return one of the eight DISM +feature state values. **Set** operations accept only the following three values as desired state: + +| Value | Description | +|:-------------|:--------------------------------------------------------------------------| +| `Installed` | The feature is enabled. The resource enables the feature if not already. | +| `NotPresent` | The feature is disabled but the payload remains on disk (staged). | +| `Removed` | The feature is disabled and the payload is removed from the system. | + +The following table describes all possible state values returned by **Get** and **Export**: + +| Value | Description | +|:---------------------|:--------------------------------------------------------------------| +| `NotPresent` | The feature is disabled with its payload removed or never staged. | +| `UninstallPending` | A disable operation is pending, requiring a restart to complete. | +| `Staged` | The feature payload is on disk but the feature is not enabled. | +| `Removed` | The feature is disabled and its source payload has been removed. | +| `Installed` | The feature is enabled and fully operational. | +| `InstallPending` | An enable operation is pending, requiring a restart to complete. | +| `Superseded` | The feature has been replaced by another component. | +| `PartiallyInstalled` | The feature is only partially installed. | + +#### displayName + +
Expand for features[*].displayName property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +The human-readable display name of the optional feature. This property is returned by **Get** and +**Export** operations. For **Export** operations, you can specify this property as a filter value +with wildcard (`*`) support for case-insensitive matching. + +#### description + +
Expand for features[*].description property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +A brief description of the optional feature. This property is returned by **Get** and **Export** +operations. For **Export** operations, you can specify this property as a filter value with +wildcard (`*`) support for case-insensitive matching. + +#### restartRequired + +
Expand for features[*].restartRequired property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +ValidValues : [No, Possible, Required] +``` + +
+ +Indicates whether a system restart is required after enabling or disabling the feature. This +property is returned by **Get** and **Export** operations and cannot be set. + +| Value | Description | +|:-----------|:----------------------------------------------------------| +| `No` | No restart is required after the state change. | +| `Possible` | A restart may be required depending on system conditions. | +| `Required` | A restart is required to complete the state change. | + +### _restartRequired + +
Expand for _restartRequired property metadata + +```yaml +Type : array +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +
+ +Returned at the top level of the **Set** operation response when DISM reports that a system restart +is required to complete the requested state changes. Each entry in the array is an object with a +`system` property containing the name of the computer. + +When no restart is required, this property is omitted from the response. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": ["features"], + "additionalProperties": false, + "properties": { + "_restartRequired": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "features": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "featureName": { "type": "string" }, + "_exist": { "type": "boolean" }, + "state": { + "type": "string", + "enum": [ + "NotPresent", "UninstallPending", "Staged", "Removed", + "Installed", "InstallPending", "Superseded", "PartiallyInstalled" + ] + }, + "displayName": { "type": "string" }, + "description": { "type": "string" }, + "restartRequired": { + "type": "string", + "enum": ["No", "Possible", "Required"] + } + } + } + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. The resource writes the result JSON to +stdout. + +### Exit code 1 + +Indicates the resource operation failed. The resource writes a descriptive error message to stderr. +Common causes include: + +- The `features` array is empty. +- The `featureName` property is missing from a feature entry in a **Get** or **Set** operation. +- The `state` property is missing from a feature entry in a **Set** operation. +- The desired `state` value is not one of the accepted **Set** values (`Installed`, `NotPresent`, + `Removed`). +- The DISM API returned an error while querying or modifying feature state. +- The process is not running with elevated privileges. + +## See also + +- [Microsoft.Windows/FeatureOnDemandList resource][06] +- [Windows Optional Features documentation][07] + + +[01]: ../../../../../concepts/resources/capabilities.md +[02]: ./examples/get-optional-feature.md +[03]: ./examples/enable-disable-optional-features.md +[04]: ./examples/export-optional-features.md +[05]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[06]: ../FeatureOnDemandList/index.md +[07]: /windows-server/administration/windows-commands/dism/dism-operating-system-package-servicing-command-line-options diff --git a/docs/reference/resources/overview.md b/docs/reference/resources/overview.md index 050999f1b..00118ec15 100644 --- a/docs/reference/resources/overview.md +++ b/docs/reference/resources/overview.md @@ -12,6 +12,8 @@ This document lists the available resources and links to the reference documenta - [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) - [Microsoft.DSC.Debug/Echo](./microsoft/dsc/debug/echo/resource.md) - [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) +- [Microsoft.Windows/FeatureOnDemandList](./Microsoft/Windows/FeatureOnDemandList/index.md) +- [Microsoft.Windows/OptionalFeatureList](./Microsoft/Windows/OptionalFeatureList/index.md) - [Microsoft.Windows/RebootPending](./microsoft/windows/rebootpending/resource.md) - [Microsoft.Windows/Registry](./microsoft/windows/registry/resource.md) - [Microsoft.Windows/WindowsPowerShell](./microsoft/windows/windowspowershell/resource.md) @@ -40,6 +42,8 @@ Manifest: The following built-in resources to change the state of a machine directly: - [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) +- [Microsoft.Windows/FeatureOnDemandList](./Microsoft/Windows/FeatureOnDemandList/index.md) +- [Microsoft.Windows/OptionalFeatureList](./Microsoft/Windows/OptionalFeatureList/index.md) - [Microsoft.Windows/Registry](./microsoft/windows/registry/resource.md) ## Built-in debugging resources From 59206416356c5174d70ac1babef2f7ee33220255 Mon Sep 17 00:00:00 2001 From: Gijs <26114636+Gijsreyn@users.noreply.github.com> Date: Tue, 21 Apr 2026 08:26:38 +0200 Subject: [PATCH 2/2] Update optional feature documentation to reflect state changes from 'Disabled' to 'NotPresent' --- .../Microsoft/Windows/FeatureOnDemandList/index.md | 2 +- .../examples/enable-disable-optional-features.md | 4 ++-- .../examples/export-optional-features.md | 8 ++++---- .../OptionalFeatureList/examples/get-optional-feature.md | 6 +++--- .../Microsoft/Windows/OptionalFeatureList/index.md | 4 ++-- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md index 1e5e0bbde..9e03909ab 100644 --- a/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md +++ b/docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md @@ -121,7 +121,7 @@ Demand). For the **Get** operation, each entry must specify [`identity`](#identi operation, each entry must specify both [`identity`](#identity) and [`state`](#state). For the **Export** operation, the array is optional and each entry can filter results using [`identity`](#identity), [`state`](#state), [`displayName`](#displayname), or -[`description`](#description) with wildcard support. +[`description`](#description) Wildcards are supported for [`identity`](#identity). Each entry in `capabilities` has the following properties: diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md index 14c654c66..8c0c1ac7c 100644 --- a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md @@ -41,7 +41,7 @@ When the resource enables the feature, DSC returns the updated state: beforeState: features: - featureName: TelnetClient - state: Disabled + state: NotPresent displayName: Telnet Client description: Includes Telnet Client restartRequired: No @@ -100,7 +100,7 @@ beforeState: afterState: features: - featureName: TelnetClient - state: Disabled + state: NotPresent displayName: Telnet Client description: Includes Telnet Client restartRequired: No diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md index 578feceb6..357278012 100644 --- a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md @@ -36,11 +36,11 @@ resources: properties: features: - featureName: TFTP - state: Disabled + state: NotPresent - featureName: TelnetClient - state: Disabled + state: NotPresent - featureName: Containers-DisposableClientVM - state: Disabled + state: NotPresent # ... additional features ``` @@ -134,7 +134,7 @@ resources: properties: features: - featureName: TelnetClient - state: Disabled + state: NotPresent displayName: Telnet Client description: Includes Telnet Client restartRequired: No diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md index d69364f08..1e3f0c4a9 100644 --- a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md @@ -38,7 +38,7 @@ When the feature is disabled, DSC returns output similar to the following: actualState: features: - featureName: TelnetClient - state: Disabled + state: NotPresent displayName: Telnet Client description: Includes Telnet Client restartRequired: No @@ -78,12 +78,12 @@ DSC returns the state of all requested features in a single response: actualState: features: - featureName: TelnetClient - state: Disabled + state: NotPresent displayName: Telnet Client description: Includes Telnet Client restartRequired: No - featureName: TFTP - state: Disabled + state: NotPresent displayName: TFTP Client description: Includes TFTP Client restartRequired: No diff --git a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md index 3f769bc4c..f08d4bd47 100644 --- a/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md +++ b/docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md @@ -119,7 +119,7 @@ For the **Get** operation, each entry must specify [`featureName`](#featurename) operation, each entry must specify both [`featureName`](#featurename) and [`state`](#state). For the **Export** operation, the array is optional and each entry can filter results using [`featureName`](#featurename), [`state`](#state), [`displayName`](#displayname), or -[`description`](#description) with wildcard support. +[`description`](#description) with wildcard support, or by exact [`state`](#state) value. Each entry in `features` has the following properties: @@ -196,7 +196,7 @@ The following table describes all possible state values returned by **Get** and | Value | Description | |:---------------------|:--------------------------------------------------------------------| -| `NotPresent` | The feature is disabled with its payload removed or never staged. | +| `NotPresent` | The feature is disabled but the payload remains on disk (staged). | | `UninstallPending` | A disable operation is pending, requiring a restart to complete. | | `Staged` | The feature payload is on disk but the feature is not enabled. | | `Removed` | The feature is disabled and its source payload has been removed. |