docs: Add dism_dsc reference documentation#1527
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds new reference documentation pages for the Windows DISM-backed DSC resources provided by dism_dsc, including detailed property descriptions, instance schemas, and example walkthroughs to help users get started.
Changes:
- Added resource reference docs for
Microsoft.Windows/OptionalFeatureListandMicrosoft.Windows/FeatureOnDemandList. - Added three example pages per resource covering
get,set, andexportusage patterns. - Documented resource properties, valid values, exit codes, and provided embedded JSON schema snippets.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/resources/Microsoft/Windows/OptionalFeatureList/index.md | New reference page describing OptionalFeatureList capabilities, properties, schema, exit codes, and links to examples. |
| docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/get-optional-feature.md | New “get” examples for OptionalFeatureList (single/multiple/non-existent feature). |
| docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/export-optional-features.md | New “export” examples for OptionalFeatureList (all/filtered/full details). |
| docs/reference/resources/Microsoft/Windows/OptionalFeatureList/examples/enable-disable-optional-features.md | New “set” examples for OptionalFeatureList (enable/disable/remove + config document usage). |
| docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/index.md | New reference page describing FeatureOnDemandList capabilities, properties, schema, exit codes, and links to examples. |
| docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/get-feature-on-demand.md | New “get” examples for FeatureOnDemandList (single/multiple/non-existent capability). |
| docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/export-features-on-demand.md | New “export” examples for FeatureOnDemandList (all/filtered/full details). |
| docs/reference/resources/Microsoft/Windows/FeatureOnDemandList/examples/install-remove-feature-on-demand.md | New “set” examples for FeatureOnDemandList (install/remove + config document usage). |
michaeltlombardi
force-pushed
the
add-dismdsc-docs
branch
from
ffd7964 to
235f4cd
Compare
|
Starting editorial pass, will be updating the commit directly and force pushing when completed. Please don't make any changes to this PR while I'm actively editing the documentation. Thank you! |
| > [!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. |
There was a problem hiding this comment.
Not to resolve in this PR, but this is also behavior we should reconsider for the next release - the expected behavior for get and export is to return all known data for an instance without requiring resource-specific steps.
If we wanted to support a limited data mode, we should define a write-only property that tells the resource to minimize the return data - this behavior should be opt-in, not opt-out.
Also, these fields (displayName, description, etc) should be marked as read-only in the JSON Schema since they aren't configurable.
There was a problem hiding this comment.
@michaeltlombardi can you open an issue to discuss what pattern we should define for resources? In this specific case, every property is a remote call so it's SUPER slow.
| 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. |
There was a problem hiding this comment.
Design note: This implementation is non-canonical - the _exist canonical property should only be used to indicate/define whether a resource instance actually exists on the system.
We could pretty readily map this to install/uninstall for this resource and make state read-only.
Otherwise we should consider removing this property. If the desired capability doesn't exist we probably want to raise an error.
| 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`. |
There was a problem hiding this comment.
Design note:
For the next release, we may want to consider updating the resource implementation to separate identity into name, languageTag, and version - which we concatenate for the user before handing off to the API.
As-is, this is very difficult to parse and reason about. It also requires the user to know the exact string, which may be different across operating system versions.
This resource serves a similar purpose to PsdscResources\WindowsFeature but with a much less intuitive resource instance API.
Looking through this implementation I think we probably want to review the design for this resource all-up before our next release.
michaeltlombardi
left a comment
michaeltlombardi
left a comment
There was a problem hiding this comment.
Completed editorial review, ready for final technical review and merge.
|
Thanks Mikey! |
PR Summary
This pull request adds reference documentation for the
dism_dscexecutable for Windows. Each resource contains 3 examples for users to get started easily.