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

Version    : 0.1.0
Kind       : resource
Tags       : [Windows, dism, capability, featureondemand, fod]
Author     : Microsoft

Instance definition syntax

resources:
  - name: <instance 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.

Examples

Get feature on demand state - Shows how to retrieve the current state of a Windows capability.
Install and remove features on demand - Shows how to install and remove Windows capabilities using the dsc resource set command.
Export features on demand - 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 - An array of capability entries.
Instance properties: The following properties are optional. They define the desired state for an instance of the resource.
- sourcePaths - The location of the source files to use for installation if necessary.
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.
- _restartRequired - Indicates that a system restart is required to complete the state change.

capabilities

Expand for capabilities property metadata

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. For the Set operation, each entry must specify both identity and state. For the Export operation, the array is optional and each entry can filter results using identity, state, displayName, or description with wildcard support.

Each entry in capabilities has the following properties:

identity - The identity string of the capability.
_exist - Indicates whether the capability is recognized by DISM.
state - The current or desired state of the capability.
displayName - The display name of the capability.
description - The description of the capability.
downloadSize - The download size of the capability in bytes.
installSize - The install size of the capability in bytes.

identity

Expand for capabilities[*].identity property metadata

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

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

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

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

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

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

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.

sourcePaths

Expand for sourcePaths property metadata

Type       : array
IsRequired : false
IsKey      : false
IsReadOnly : false

Supplied at the top level of the Set operation, indicates the location of the source files to use for installation if necessary. The DISM API will search these paths if the feature files are not available in the local feature store. See the feature on demand repository documentation for more information on valid sources.

This property is optional and will be omitted from the response if empty.

_restartRequired

Expand for _restartRequired property metadata

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.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["capabilities"],
  "additionalProperties": false,
  "properties": {
    "_restartRequired": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "sourcePaths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "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 - Success
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.
An invalid path was supplied to sourcePaths in a Set operation.

Navigation Menu

Uh oh!

Microsoft.Windows/FeatureOnDemandList

Synopsis

Metadata

Instance definition syntax

Description

Requirements

Capabilities

Examples

Properties

capabilities

identity

_exist

state

displayName

description

downloadSize

installSize

sourcePaths

_restartRequired

Instance validating schema

Exit codes

Exit code 0

Exit code 1

See also

Uh oh!

FilesExpand file tree

index.md

Latest commit

History

index.md

File metadata and controls

Microsoft.Windows/FeatureOnDemandList

Synopsis

Metadata

Instance definition syntax

Description

Requirements

Capabilities

Examples

Properties

capabilities

identity

_exist

state

displayName

description

downloadSize

installSize

sourcePaths

_restartRequired

Instance validating schema

Exit codes

Exit code 0

Exit code 1

See also