dism resource: add sourcePath parameter to allow for offline feature installs

docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md

@@ -115,6 +115,52 @@ changedProperties:
 - capabilities
 ```
 
+## Install a feature on demand using an offline source
+
+To allow DISM to install capabilities that are not present on the machine in a offline environment, 
+add the offline Windows image file (WIM) path to the `sourcePaths` property.
+
+```powershell
+$instance = @{
+    sourcePaths = @('z:\sources\SxS')
+    capabilities = @(
+        @{
+            identity = 'NetFX3~~~~'
+            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:
+  sourcePaths:
+  - z:\sources\SxS
+  capabilities:
+  - identity: NetFX3~~~~
+    state: NotPresent
+    displayName: ''
+    description: ''
+    downloadSize: 0
+    installSize: 487706170
+afterState:
+  sourcePaths:
+  - z:\sources\SxS
+  capabilities:
+  - identity: NetFX3~~~~
+    state: Installed
+    displayName: ''
+    description: ''
+    downloadSize: 0
+    installSize: 487706170
+changedProperties:
+- capabilities
+```
+
 ## Manage multiple capabilities in a single operation
 
 You can install or remove multiple capabilities in a single **Set** call by specifying multiple

docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md

@@ -96,6 +96,12 @@ The following list describes the properties for the resource.
 
   - [capabilities](#capabilities) - An array of capability entries.
 
+- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
+  They define the desired state for an instance of the resource.
+
+  - [sourcePaths](#sourcePaths) - The location of the source files to use for installation if 
+    necessary.
+
 - **Read-only properties:** <a id="read-only-properties"></a> 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].
@@ -277,6 +283,28 @@ IsReadOnly : true
 The size in bytes that the capability occupies on disk after installation. This property is returned
 by **Get** and **Export** operations.
 
+### sourcePaths
+
+<details><summary>Expand for <code>sourcePaths</code> property metadata</summary>
+
+```yaml
+Type       : array
+IsRequired : false
+IsKey      : false
+IsReadOnly : false
+```
+
+</details>
+
+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.
+
+All paths supplied should be to a Windows image file (WIM). See the 
+[feature on demand repository documentation][08] for more information on valid sources.
+
+This property is optional and will be omitted from the response if empty.
+
 ### _restartRequired
 
 <details><summary>Expand for <code>_restartRequired</code> property metadata</summary>
@@ -314,6 +342,12 @@ The following snippet contains the JSON Schema that validates an instance of the
         "additionalProperties": true
       }
     },
+    "sourcePaths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "capabilities": {
       "type": "array",
       "items": {
@@ -364,6 +398,7 @@ Common causes include:
 - 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.
 
 ## See also
 
@@ -378,3 +413,4 @@ Common causes include:
 [05]: ../../../../../concepts/resources/properties.md#read-only-resource-properties
 [06]: ../OptionalFeatureList/index.md
 [07]: /windows-hardware/manufacture/desktop/features-on-demand-v2--capabilities
+[08]: /windows-hardware/manufacture/desktop/features-on-demand-v2--capabilities?view=windows-11#fod-repositories

docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md

@@ -146,6 +146,50 @@ changedProperties:
 - features
 ```
 
+## Enable an optional feature using an offline source
+
+To allow DISM to install features that are not present on the machine in a offline environment, add
+the offline Windows image file (WIM) path to the `sourcePaths` property.
+
+```powershell
+$instance = @{
+    sourcePaths = @('z:\sources\SxS')
+    features = @(
+        @{
+            featureName = 'NetFx3'
+            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:
+  sourcePaths:
+  - z:\sources\SxS
+  features:
+  - featureName: NetFx3
+    state: NotPresent
+    displayName: NET Framework 3.5 (includes .NET 2.0 and 3.0)
+    description: .NET Framework 3.5 (includes .NET 2.0 and 3.0)
+    restartRequired: No
+afterState:
+  sourcePaths:
+  - z:\sources\SxS
+  features:
+  - featureName: NetFx3
+    state: Installed
+    displayName: NET Framework 3.5 (includes .NET 2.0 and 3.0)
+    description: .NET Framework 3.5 (includes .NET 2.0 and 3.0)
+    restartRequired: Possible
+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

docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md

@@ -94,6 +94,12 @@ The following list describes the properties for the resource.
 
   - [features](#features) - An array of optional feature entries.
 
+- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
+  They define the desired state for an instance of the resource.
+
+  - [sourcePaths](#sourcePaths) - The location of the source files to use for installation if 
+    necessary.
+
 - **Read-only properties:** <a id="read-only-properties"></a> 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].
@@ -262,6 +268,28 @@ property is returned by **Get** and **Export** operations and cannot be set.
 | `Possible` | A restart may be required depending on system conditions. |
 | `Required` | A restart is required to complete the state change.       |
 
+### sourcePaths
+
+<details><summary>Expand for <code>sourcePaths</code> property metadata</summary>
+
+```yaml
+Type       : array
+IsRequired : false
+IsKey      : false
+IsReadOnly : false
+```
+
+</details>
+
+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. 
+
+All paths supplied should be to a Windows image file (WIM). See the 
+[DISM enable feature documentation][08] for more information on valid sources.
+
+This property is optional and will be omitted from the response if empty.
+
 ### _restartRequired
 
 <details><summary>Expand for <code>_restartRequired</code> property metadata</summary>
@@ -298,6 +326,12 @@ The following snippet contains the JSON Schema that validates an instance of the
         "type": "object",
         "additionalProperties": true
       }
+    },    
+    "sourcePaths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     },
     "features": {
       "type": "array",
@@ -351,6 +385,7 @@ Common causes include:
   `Removed`).
 - The DISM API returned an error while querying or modifying feature state.
 - The process is not running with elevated privileges.
+- An invalid path was supplied to `sourcePaths` in a **Set** operation.
 
 ## See also
 
@@ -364,4 +399,5 @@ Common causes include:
 [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
+[07]: /windows-hardware/manufacture/desktop/deployment-image-servicing-and-management--dism--command-line-options
+[08]: /windows-hardware/manufacture/desktop/dism-operating-system-package-servicing-command-line-options#enable-feature

resources/dism_dsc/featureondemand.dsc.resource.json

@@ -116,6 +116,14 @@
                             }
                         }
                     }
+                },
+                "sourcePaths": {
+                    "type": "array",
+                    "title": "Source paths",
+                    "description": "An array of paths to feature files if the files are not available in the local feature store. This is an optional property for set operations and is ignored for get operations.",
+                    "items": {
+                        "type": "string"
+                    }
                 }
             }
         }

resources/dism_dsc/locales/en-us.toml

@@ -31,6 +31,7 @@ failedSerializeOutput = "Failed to serialize output: %{err}"
 [fod_set]
 failedParseInput = "Failed to parse input: %{err}"
 capabilitiesArrayEmpty = "Capabilities array cannot be empty for set operation"
+sourcePathInvalid = "Failed to parse value in sourcePaths: '%{path}' is an invalid path"
 identityRequired = "identity is required for set operation"
 stateRequired = "state is required for set operation"
 capabilityNotFound = "Capability '%{identity}' was not found on this system"
@@ -40,6 +41,7 @@ failedSerializeOutput = "Failed to serialize output: %{err}"
 [set]
 failedParseInput = "Failed to parse input: %{err}"
 featuresArrayEmpty = "Features array cannot be empty for set operation"
+sourcePathInvalid = "Failed to parse value in sourcePaths: '%{path}' is an invalid path"
 featureNameRequired = "featureName is required for set operation"
 stateRequired = "state is required for set operation"
 unsupportedDesiredState = "Unsupported desired state '%{state}'. Supported states for set are: Installed, NotPresent, Removed"

resources/dism_dsc/optionalfeature.dsc.resource.json

@@ -91,7 +91,8 @@
                                     "PartiallyInstalled"
                                 ],
                                 "title": "Feature state",
-                                "description": "The current state of the optional feature. For set operations, only Installed, NotPresent, and Removed are accepted; other states are returned by get and export operations and are not valid inputs for set."},
+                                "description": "The current state of the optional feature. For set operations, only Installed, NotPresent, and Removed are accepted; other states are returned by get and export operations and are not valid inputs for set."
+                            },
                             "displayName": {
                                 "type": "string",
                                 "title": "Display name",
@@ -114,6 +115,14 @@
                             }
                         }
                     }
+                },
+                "sourcePaths": {
+                    "type": "array",
+                    "title": "Source paths",
+                    "description": "An array of paths to feature files if the files are not available in the local feature store. This is an optional property for set operations and is ignored for get operations.",
+                    "items": {
+                        "type": "string"
+                    }
                 }
             }
         }

resources/dism_dsc/src/dism.rs

@@ -319,17 +319,25 @@ impl DismSessionHandle {
     }
 
     /// Returns `Ok(true)` if DISM reports a reboot is required (HRESULT 3010).
-    pub fn enable_feature(&self, feature_name: &str) -> Result<bool, String> {
+    pub fn enable_feature(&self, feature_name: &str, source_paths: &Option<Vec<String>>) -> Result<bool, String> {
         let wide_name = to_wide_null(feature_name);
+
+        let source_count: u32 = source_paths.as_ref().map_or(0, |paths| paths.len() as u32);
+        let wide_source_paths: Option<Vec<_>> = source_paths.as_ref().map(|paths| {
+            paths.into_iter().map(|p| to_wide_null(&p)).collect()
+        });
+        let sources = wide_source_paths.as_ref().map(|paths| paths.iter().map(|p| p.as_ptr()).collect::<Vec<_>>());
+        let sources_ptr = sources.as_ref().map_or(std::ptr::null(), |v| v.as_ptr());
+
         let hr = unsafe {
             (self.api.enable_feature)(
                 self.handle,
                 wide_name.as_ptr(),
                 std::ptr::null(),       // Identifier
                 DISM_PACKAGE_NONE,      // PackageIdentifier
                 0,                      // LimitAccess = FALSE
-                std::ptr::null(),       // SourcePaths
-                0,                      // SourcePathCount
+                sources_ptr,            // SourcePaths
+                source_count,           // SourcePathCount
                 0,                      // EnableAll = FALSE
                 std::ptr::null_mut(),   // CancelEvent
                 std::ptr::null_mut(),   // Progress
@@ -457,18 +465,26 @@ impl DismSessionHandle {
     }
 
     /// Returns `Ok(true)` if DISM reports a reboot is required (HRESULT 3010).
-    pub fn add_capability(&self, name: &str) -> Result<bool, String> {
+    pub fn add_capability(&self, name: &str, source_paths: &Option<Vec<String>>) -> Result<bool, String> {
         let add_cap = self.api.add_capability
             .ok_or_else(|| t!("dism.capabilitiesNotSupported").to_string())?;
 
         let wide_name = to_wide_null(name);
+
+        let source_count: u32 = source_paths.as_ref().map_or(0, |paths| paths.len() as u32);
+        let wide_source_paths: Option<Vec<_>> = source_paths.as_ref().map(|paths| {
+            paths.into_iter().map(|p| to_wide_null(&p)).collect()
+        });
+        let sources = wide_source_paths.as_ref().map(|paths| paths.iter().map(|p| p.as_ptr()).collect::<Vec<_>>());
+        let sources_ptr = sources.as_ref().map_or(std::ptr::null(), |v| v.as_ptr());
+
         let hr = unsafe {
             add_cap(
                 self.handle,
                 wide_name.as_ptr(),
                 0,                      // LimitAccess = FALSE
-                std::ptr::null(),       // SourcePaths
-                0,                      // SourcePathCount
+                sources_ptr,            // SourcePaths
+                source_count,           // SourcePathCount
                 std::ptr::null_mut(),   // CancelEvent
                 std::ptr::null_mut(),   // Progress
                 std::ptr::null_mut(),   // UserData

resources/dism_dsc/src/feature_on_demand/export.rs

@@ -91,7 +91,7 @@ pub fn handle_export(input: &str) -> Result<String, String> {
         }
     }
 
-    let output = FeatureOnDemandList { restart_required_meta: None, capabilities: results };
+    let output = FeatureOnDemandList { restart_required_meta: None, source_paths: None, capabilities: results };
     serde_json::to_string(&output)
         .map_err(|e| t!("fod_export.failedSerializeOutput", err = e.to_string()).to_string())
 }

resources/dism_dsc/src/feature_on_demand/get.rs

@@ -44,7 +44,11 @@ pub fn handle_get(input: &str) -> Result<String, String> {
         results.push(info);
     }
 
-    let output = FeatureOnDemandList { restart_required_meta: None, capabilities: results };
+    let output = FeatureOnDemandList { 
+        restart_required_meta: None, 
+        source_paths: capability_list.source_paths, 
+        capabilities: results 
+    };
     serde_json::to_string(&output)
         .map_err(|e| t!("fod_get.failedSerializeOutput", err = e.to_string()).to_string())
 }