docs: Add reference documentation for Microsoft.Windows/Service

docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md

@@ -0,0 +1,212 @@
+---
+description: >
+  Example showing how to use the Microsoft.Windows/Service resource in a DSC configuration
+  document to enforce the desired state of Windows services.
+ms.date:     05/08/2026
+ms.topic:    reference
+title:       Configure a Windows service
+---
+
+# Configure a Windows service
+
+This example shows how you can use the `Microsoft.Windows/Service` resource in a DSC configuration
+document to enforce the desired configuration and runtime status of multiple Windows services.
+
+> [!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 two instances of the `Service` resource.
+
+The first instance ensures that the Windows Update service (`wuauserv`) is stopped and configured
+for manual start. The second instance ensures that the Windows Time service (`W32Time`) is running
+and configured to start automatically.
+
+:::code language="yaml" source="service.config.dsc.yaml":::
+
+Copy the configuration document and save it as `service.config.dsc.yaml`.
+
+## Test the configuration
+
+To see whether the system is already in the desired state, use the [dsc config test][01] command.
+
+```powershell
+dsc config test --file ./service.config.dsc.yaml
+```
+
+```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: Ensure Windows Update is stopped and set to manual start
+  type: Microsoft.Windows/Service
+  result:
+    desiredState:
+      name: wuauserv
+      status: Stopped
+      startType: Manual
+    actualState:
+      name: wuauserv
+      displayName: Windows Update
+      description: Enables the detection, download, and installation of updates for Windows and other programs. If this service is disabled, users of this computer will not be able to use Windows Update or its automatic updating feature, and programs will not be able to use the Windows Update Agent (WUA) API.
+      _exist: true
+      status: Stopped
+      startType: Manual
+      executablePath: C:\Windows\system32\svchost.exe -k netsvcs -p
+      logonAccount: LocalSystem
+      errorControl: Normal
+      dependencies:
+      - rpcss
+    inDesiredState: true
+    differingProperties: []
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Ensure Windows Time service is running
+  type: Microsoft.Windows/Service
+  result:
+    desiredState:
+      name: W32Time
+      status: Running
+      startType: Automatic
+    actualState:
+      name: W32Time
+      displayName: Windows Time
+      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
+      _exist: true
+      status: Stopped
+      startType: Automatic
+      executablePath: C:\Windows\system32\svchost.exe -k LocalService
+      logonAccount: NT AUTHORITY\LocalService
+      errorControl: Normal
+    inDesiredState: false
+    differingProperties:
+    - status
+messages: []
+hadErrors: false
+```
+
+The `inDesiredState` field for the first instance is `true` because the Windows Update service is
+already `Stopped` with `Manual` start, so no change is required. The second instance is `false`:
+the Windows Time service exists and already has `startType: Automatic`, but its `status` is
+`Stopped` while the desired state requires `Running`. Only `status` is listed in
+`differingProperties`.
+
+## Set the configuration
+
+To enforce the desired state, use the [dsc config set][02] command.
+
+```powershell
+dsc config set --file ./service.config.dsc.yaml
+```
+
+```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: Ensure Windows Update is stopped and set to manual start
+  type: Microsoft.Windows/Service
+  result:
+    beforeState:
+      name: wuauserv
+      status: Stopped
+      startType: Manual
+    afterState:
+      name: wuauserv
+      displayName: Windows Update
+      description: Enables the detection, download, and installation of updates for Windows and other programs. If this service is disabled, users of this computer will not be able to use Windows Update or its automatic updating feature, and programs will not be able to use the Windows Update Agent (WUA) API.
+      _exist: true
+      status: Stopped
+      startType: Manual
+      executablePath: C:\Windows\system32\svchost.exe -k netsvcs -p
+      logonAccount: LocalSystem
+      errorControl: Normal
+      dependencies:
+      - rpcss
+    changedProperties: null
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Ensure Windows Time service is running
+  type: Microsoft.Windows/Service
+  result:
+    beforeState:
+      name: W32Time
+      displayName: Windows Time
+      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
+      _exist: true
+      status: Stopped
+      startType: Automatic
+      executablePath: C:\Windows\system32\svchost.exe -k LocalService
+      logonAccount: NT AUTHORITY\LocalService
+      errorControl: Normal
+    afterState:
+      name: W32Time
+      displayName: Windows Time
+      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
+      _exist: true
+      status: Running
+      startType: Automatic
+      executablePath: C:\Windows\system32\svchost.exe -k LocalService
+      logonAccount: NT AUTHORITY\LocalService
+      errorControl: Normal
+    changedProperties:
+    - status
+messages: []
+hadErrors: false
+```
+
+The Windows Update instance shows `changedProperties: null` because it was already in the desired
+state and DSC made no changes to it. The Windows Time instance lists only `status` in
+`changedProperties` because DSC only needed to start the service. The `startType` was already
+`Automatic` and required no update.
+
+<!-- Link definitions -->
+[01]: ../../../../../cli/config/test.md
+[02]: ../../../../../cli/config/set.md

docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md

@@ -0,0 +1,87 @@
+---
+description: >
+  Example showing how to use the Microsoft.Windows/Service resource with DSC to retrieve the
+  current state of a Windows service.
+ms.date:     05/08/2026
+ms.topic:    reference
+title:       Get service status
+---
+
+# Get service status
+
+This example shows how you can use the `Microsoft.Windows/Service` resource to retrieve the
+current configuration and runtime status of a Windows service.
+
+## Get the state of a service by name
+
+The following snippet shows how to use the resource with the [dsc resource get][01] command to
+retrieve the current state of the `wuauserv` (Windows Update) service by its key name.
+
+```powershell
+$instance = @{ name = 'wuauserv' } | ConvertTo-Json
+
+dsc resource get --resource Microsoft.Windows/Service --input $instance
+```
+
+When the service exists, DSC returns its full configuration and status:
+
+```yaml
+actualState:
+  name: wuauserv
+  displayName: Windows Update
+  description: Enables the detection, download, and installation of updates for Windows and other programs. If this service is disabled, users of this computer will not be able to use Windows Update or its automatic updating feature, and programs will not be able to use the Windows Update Agent (WUA) API.
+  _exist: true
+  status: Stopped
+  startType: Manual
+  executablePath: C:\WINDOWS\System32\svchost.exe -k netsvcs -p
+  logonAccount: LocalSystem
+  errorControl: Normal
+  dependencies:
+    - rpcss
+```
+
+## Get the state of a service by display name
+
+You can also identify the service by its display name when you don't know the key name.
+
+```powershell
+$instance = @{ displayName = 'Windows Update' } | ConvertTo-Json
+
+dsc resource get --resource Microsoft.Windows/Service --input $instance
+```
+
+DSC resolves the display name to the corresponding key name and returns the same result.
+
+## Get the state of a non-existent service
+
+When you request a service that isn't registered with the SCM, the resource returns `_exist: false`
+and leaves all other properties unset.
+
+```powershell
+$instance = @{ name = 'MyMissingService' } | ConvertTo-Json
+
+dsc resource get --resource Microsoft.Windows/Service --input $instance
+```
+
+```yaml
+actualState:
+  name: MyMissingService
+  _exist: false
+```
+
+## Export all services
+
+To retrieve the state of every service registered on the system, use the [dsc resource export][02]
+command without an input instance.
+
+```powershell
+dsc resource export --resource Microsoft.Windows/Service
+```
+
+DSC writes a single JSON configuration document to stdout. That document contains a `resources`
+array with one entry per service, which you can pipe to a file or process further with other
+tools.
+
+<!-- Link definitions -->
+[01]: ../../../../../cli/resource/get.md
+[02]: ../../../../../cli/resource/export.md

docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml

@@ -0,0 +1,15 @@
+# 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: Ensure Windows Update is stopped and set to manual start
+    type: Microsoft.Windows/Service
+    properties:
+      name: wuauserv
+      status: Stopped
+      startType: Manual
+  - name: Ensure Windows Time service is running
+    type: Microsoft.Windows/Service
+    properties:
+      name: W32Time
+      status: Running
+      startType: Automatic