docs: Add reference documentation for Microsoft.Windows/FirewallRuleList

docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md

@@ -0,0 +1,279 @@
+---
+description: >
+  Example showing how to use the Microsoft.Windows/FirewallRuleList resource in a DSC configuration
+  document to create and enforce Windows Firewall rules.
+ms.date:     05/09/2026
+ms.topic:    reference
+title:       Configure firewall rules
+---
+
+# Configure firewall rules
+
+This example shows how you can use the `Microsoft.Windows/FirewallRuleList` resource in a DSC
+configuration document to create and enforce multiple Windows Firewall rules in a single operation.
+
+> [!IMPORTANT]
+> **Set** operations for this resource require an elevated (administrator) process context. Run
+> your terminal or PowerShell session as Administrator before using `dsc config set`.
+
+## Definition
+
+The configuration document for this example defines one instance of the `FirewallRuleList`
+resource that manages two rules:
+
+- **DscDemo - Custom App (TCP-In)** — allows inbound TCP traffic on port 8080 for a custom
+  application, active on the Domain and Private profiles.
+- **DscDemo - Block Telnet (TCP-Out)** — blocks all outbound TCP connections to port 23 (Telnet)
+  on all profiles.
+
+:::code language="yaml" source="firewall.config.dsc.yaml":::
+
+Copy the configuration document and save it as `firewall.config.dsc.yaml`.
+
+## Test the configuration
+
+To see whether the rules already exist, use the [dsc config test][01] command.
+
+```powershell
+dsc config test --file ./firewall.config.dsc.yaml
+```
+
+Because neither rule exists yet, both appear in the actual state with `_exist: false`. DSC
+computes the instance as out of desired state and lists `rules` in `differingProperties`.
+
+```yaml
+executionInformation:
+  duration: <time omitted>
+  endDatetime: <time omitted>
+  executionType: actual
+  operation: test
+  securityContext: elevated
+  startDatetime: <time omitted>
+  version: <redacted>
+metadata:
+  Microsoft.DSC:
+    duration: <time omitted>
+    endDatetime: <time omitted>
+    executionType: actual
+    operation: test
+    securityContext: elevated
+    startDatetime: <time omitted>
+    version: <redacted>
+results:
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Application firewall rules
+  type: Microsoft.Windows/FirewallRuleList
+  result:
+    desiredState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    actualState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        _exist: false
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        _exist: false
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    inDesiredState: false
+    differingProperties:
+    - rules
+messages: []
+hadErrors: false
+```
+
+Neither rule exists in the firewall store, so both entries in `actualState` show `_exist: false`.
+Because the actual state differs from the desired state, `inDesiredState` is `false` and `rules`
+is listed in `differingProperties`.
+
+## Set the configuration
+
+To enforce the desired state and create both rules, use the [dsc config set][02] command.
+
+```powershell
+dsc config set --file ./firewall.config.dsc.yaml
+```
+
+DSC performs a synthetic test, determines that both rules are missing, and calls the resource's
+set operation. The resource creates both rules and returns the new state. The `afterState` shows
+the full configuration of each rule as read back from the Windows Firewall store, including
+properties filled in by Windows defaults such as `interfaceTypes` and `edgeTraversal`.
+
+```yaml
+executionInformation:
+  duration: <time omitted>
+  endDatetime: <time omitted>
+  executionType: actual
+  operation: set
+  securityContext: elevated
+  startDatetime: <time omitted>
+  version: <redacted>
+metadata:
+  Microsoft.DSC:
+    duration: <time omitted>
+    endDatetime: <time omitted>
+    executionType: actual
+    operation: set
+    securityContext: elevated
+    startDatetime: <time omitted>
+    version: <redacted>
+results:
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Application firewall rules
+  type: Microsoft.Windows/FirewallRuleList
+  result:
+    beforeState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        _exist: false
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        _exist: false
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    afterState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        remotePorts: '*'
+        localAddresses: '*'
+        remoteAddresses: '*'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+        interfaceTypes:
+        - All
+        edgeTraversal: false
+      - name: DscDemo - Block Telnet (TCP-Out)
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        localPorts: '*'
+        remotePorts: '23'
+        localAddresses: '*'
+        remoteAddresses: '*'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+        interfaceTypes:
+        - All
+        edgeTraversal: false
+    changedProperties:
+    - rules
+messages: []
+hadErrors: false
+```
+
+Both rules were created. The `beforeState` shows both rules with `_exist: false`, confirming they
+didn't exist before the operation. The `afterState` shows the complete configuration read back
+from the firewall store after creation, including `interfaceTypes: [All]` and
+`edgeTraversal: false` filled in by Windows. `changedProperties` lists `rules` because the rules
+array changed.
+
+## Remove a rule
+
+To remove a rule, set `_exist: false` on the specific entry and run `dsc resource set`.
+The following snippet removes the Telnet block rule while leaving the custom app rule in place.
+
+```powershell
+$desired = @'
+{
+  "rules": [
+    { "name": "DscDemo - Block Telnet (TCP-Out)", "_exist": false }
+  ]
+}
+'@
+
+dsc resource set --resource Microsoft.Windows/FirewallRuleList --input $desired
+```
+
+```yaml
+beforeState:
+  rules:
+  - name: DscDemo - Block Telnet (TCP-Out)
+    description: Block all outbound Telnet connections.
+    protocol: 6
+    remotePorts: "23"
+    direction: Outbound
+    action: Block
+    enabled: true
+    profiles:
+    - All
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+afterState:
+  rules:
+  - name: DscDemo - Block Telnet (TCP-Out)
+    _exist: false
+changedProperties:
+- rules
+```
+
+The rule was removed. The `afterState` for the entry shows `_exist: false`, confirming the rule
+no longer exists in the Windows Firewall store.
+
+<!-- Link definitions -->
+[01]: ../../../../../cli/config/test.md
+[02]: ../../../../../cli/config/set.md

docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml

@@ -0,0 +1,26 @@
+# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Application firewall rules
+    type: Microsoft.Windows/FirewallRuleList
+    properties:
+      rules:
+        - name: DscDemo - Custom App (TCP-In)
+          description: Allow inbound TCP traffic on port 8080 for the custom app.
+          protocol: 6
+          localPorts: '8080'
+          direction: Inbound
+          action: Allow
+          enabled: true
+          profiles:
+            - Domain
+            - Private
+        - name: DscDemo - Block Telnet (TCP-Out)
+          description: Block all outbound Telnet connections.
+          protocol: 6
+          remotePorts: '23'
+          direction: Outbound
+          action: Block
+          enabled: true
+          profiles:
+            - All