docs: Add reference documentation for Microsoft.Windows/FirewallRuleList#1523
docs: Add reference documentation for Microsoft.Windows/FirewallRuleList#1523Gijsreyn wants to merge 3 commits into
Microsoft.Windows/FirewallRuleList#1523Conversation
There was a problem hiding this comment.
Pull request overview
Adds reference documentation and examples for the built-in DSC resource Microsoft.Windows/FirewallRuleList, describing its schema, capabilities, and common usage patterns for getting/setting/exporting Windows Firewall rules.
Changes:
- Added a full resource reference page including properties, schema, exit codes, and links to examples.
- Added a “get/toggle/export” CLI example page for
dsc resourceusage. - Added a configuration-document example (YAML) plus a walkthrough for
dsc config test/setand rule removal.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md | New reference page for the resource (syntax, properties, schema, exit codes, links). |
| docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md | New CLI-oriented example for get/set/export behavior. |
| docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml | New sample DSC config document defining two firewall rules. |
| docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md | New walkthrough demonstrating config test/set and rule removal. |
|
@SteveL-MSFT - one of the remarks from Copilot was the min/max on the protocol property. Even though, when running it, for example, with 257, the executable throws a useful error message. However, I have updated the resource manifest to include both minimum and maximum, as I do think it adds value for authoring-time feedback and fails early without spawning a process. If not, let me know, and I'll remove it from the docs. |
| > [!IMPORTANT] | ||
| > The `_exist` property on a rule item behaves differently from most DSC resources. When a rule | ||
| > exists in the Windows Firewall store, `_exist` is **omitted** from the returned state (absent | ||
| > means present). When a rule is not found, `_exist: false` appears in the response. This means | ||
| > that a missing `_exist` field in the actual state always indicates the rule exists. |
There was a problem hiding this comment.
Out of scope for this PR, but we should consider altering this behavior for the next release.
_exist is a canonical property with strong contracts. We shouldn't have any resources that implement a canonical property in a surprising way that requires callouts like this.
It's always an optional field to send to the resource, because the default is true, but we should always return the fully defined actual state of the resource, including _exist as either true or false.
PR Summary
This pull request adds reference documentation for the built-in DSC resource
Microsoft.Windows/FirewallRuleList.