From 6a12ce7bb99abfb424d6fa10f0e33c7a243e7e42 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Sat, 9 May 2026 11:23:23 +0200 Subject: [PATCH] docs: Add reference documentation for Microsoft.Windows/Service --- .../examples/configure-windows-service.md | 197 ++++++++ .../Service/examples/get-service-status.md | 87 ++++ .../Service/examples/service.config.dsc.yaml | 15 + .../Microsoft/Windows/Service/index.md | 424 ++++++++++++++++++ 4 files changed, 723 insertions(+) create mode 100644 docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md create mode 100644 docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md create mode 100644 docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml create mode 100644 docs/reference/resources/Microsoft/Windows/Service/index.md diff --git a/docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md b/docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md new file mode 100644 index 000000000..d60c65381 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md @@ -0,0 +1,197 @@ +--- +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`. + +## Setup + +The output in this example assumes that the system has the `wuauserv` service stopped with a manual +startup and the `W32Time` service stopped with an automatic startup. You can set the system to +this starting state with the following commands: + +```powershell +Set-Service -Name wuauserv -StartupType Manual -Status Stopped +Set-Service -Name W32Time -StartupType Automatic -Status Stopped +``` + +## 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: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT0.1113118S + metadata: + Microsoft.DSC: + duration: PT0.1113118S + 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: PT0.0353328S + metadata: + Microsoft.DSC: + duration: PT0.0353328S + 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: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT0.0924309S + metadata: + Microsoft.DSC: + duration: PT0.0924309S + 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: PT0.3682548S + metadata: + Microsoft.DSC: + duration: PT0.3682548S + 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. + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md b/docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md new file mode 100644 index 000000000..f88b6f7ba --- /dev/null +++ b/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 -Compress + +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 -Compress + +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. + + +[01]: ../../../../../cli/resource/get.md +[02]: ../../../../../cli/resource/export.md diff --git a/docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml new file mode 100644 index 000000000..3af04533b --- /dev/null +++ b/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 diff --git a/docs/reference/resources/Microsoft/Windows/Service/index.md b/docs/reference/resources/Microsoft/Windows/Service/index.md new file mode 100644 index 000000000..ebcb17811 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Service/index.md @@ -0,0 +1,424 @@ +--- +description: Microsoft.Windows/Service resource reference documentation +ms.date: 05/08/2026 +ms.topic: reference +title: Microsoft.Windows/Service +--- + +# Microsoft.Windows/Service + +## Synopsis + +Manage Windows services. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/Service + properties: + # Key properties + name: string + # Instance properties + description: + dependencies: + displayName: + errorControl: + executablePath: + logonAccount: + startType: + status: +``` + +## Description + +The `Microsoft.Windows/Service` resource enables you to idempotently manage the configuration and +runtime state of Windows services registered with the Service Control Manager (SCM). The resource +can: + +- Retrieve the full configuration and status of a service. +- Change the start type, status, description, display name, logon account, error control, + executable path, and service dependencies. +- Export a list of all services registered on the system. + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- **Set** operations require an elevated (administrator) process context. Running `dsc` without + elevation when using the **Set** operation causes an access-denied error from the SCM. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of a service instance. +- `set` - You can use the resource to enforce the desired configuration and status of a service. +- `export` - You can use the resource to export a list of all services registered on the system. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][01]. + +## Examples + +1. [Get service status][02] - Shows how to retrieve the current state of a Windows service with the + `dsc resource` commands. +1. [Configure a Windows service][03] - Shows how to enforce the desired configuration of a Windows + service using a DSC configuration document. + +## Properties + +The following list describes the properties for the resource. + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][04]. + + - [name](#name) - The name of the service in the Service Control Manager. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [dependencies](#dependencies) - A list of service names that this service depends on. + - [description](#description) - A description of the service. + - [displayName](#displayname) - The display name of the service shown in the Services console. + - [errorControl](#errorcontrol) - The error control level for the service. + - [executablePath](#executablepath) - The fully qualified path to the service binary. + - [logonAccount](#logonaccount) - The account under which the service runs. + - [startType](#starttype) - The start type of the service. + - [status](#status) - The current or desired status of the service. + +- **Read-only properties:** 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]. + + - [_exist](#_exist) - Indicates whether the service exists in the Service Control Manager. + +### name + +
Expand for name property metadata + +```yaml +Type : string +IsRequired : false +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +The service key name as registered in the Service Control Manager. This is the short internal name +used to identify the service. For example, `wuauserv` for Windows Update. This value is +case-insensitive. + +When performing a **Get** operation you may supply either `name` or `displayName` (or both) to +identify the service. For **Set** operations you must supply `name`. + +### displayName + +
Expand for displayName property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +The friendly display name of the service shown in the Windows Services console — for example, +`Windows Update`. You can define `displayName` instead of (or alongside) `name` in a **Get** +operation to locate a service when you don't know its key name. If both are provided, DSC verifies +that they refer to the same service and returns an error if they don't match. + +### description + +
Expand for description property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +A human-readable description of the service. Setting this property updates the description shown +in the Services console and the **Description** field in the SCM database. + +### _exist + +
Expand for _exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +``` + +
+ +Indicates whether the service exists in the Service Control Manager. This property is returned by +the resource and cannot be set. A value of `true` means the service is registered; `false` means +it is not found. + +### status + +
Expand for status property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Running, Stopped, Paused, StartPending, StopPending, PausePending, ContinuePending] +``` + +
+ +The runtime status of the service. When used as desired state in a **Set** operation, only the +following values are valid: + +| Value | Effect | +|:----------|:---------------------------------------------| +| `Running` | DSC starts the service if it is not running. | +| `Stopped` | DSC stops the service if it is not stopped. | +| `Paused` | DSC pauses the service if it is not paused. | + +The following additional values may be returned by a **Get** or **Export** operation to describe a +transient state, but they must not be used as desired-state values: + +- `StartPending` +- `StopPending` +- `PausePending` +- `ContinuePending` + +### startType + +
Expand for startType property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Automatic, AutomaticDelayedStart, Manual, Disabled] +``` + +
+ +Defines how the service is started. The following values are valid: + +| Value | Description | +|:------------------------|:-------------------------------------------------------------------------------------| +| `Automatic` | The service is started automatically by the SCM at system startup. | +| `AutomaticDelayedStart` | The service starts automatically after other auto-start services have initialized. | +| `Manual` | The service is started only when explicitly requested (e.g., via `sc start`). | +| `Disabled` | The service cannot be started. | + +### executablePath + +
Expand for executablePath property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +The fully qualified path to the service binary, including any command-line arguments registered +with the SCM. For example, `C:\Windows\System32\svchost.exe -k netsvcs`. + +### logonAccount + +
Expand for logonAccount property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +The account under which the service process runs. Only the following built-in service accounts are +supported by the **Set** operation: + +- `LocalSystem` +- `NT AUTHORITY\LocalService` +- `NT AUTHORITY\NetworkService` + +Specifying a regular user account causes the **Set** operation to return an error. + +### errorControl + +
Expand for errorControl property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Ignore, Normal, Severe, Critical] +``` + +
+ +Controls the action taken if the service fails to start during system boot. The following values +are valid: + +| Value | Description | +|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Ignore` | The error is logged and startup continues. | +| `Normal` | The error is logged, a message box is displayed, and startup continues. | +| `Severe` | The error is logged. If the last-known-good configuration is in use, startup continues; otherwise the system restarts with the last-known-good configuration. | +| `Critical` | The error is logged. If the last-known-good configuration is in use, startup fails; otherwise the system restarts with the last-known-good configuration. | + +### dependencies + +
Expand for dependencies property metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +A list of service key names that this service depends on. The SCM will not start the service until +all listed dependencies are running. Setting this property _replaces_ the existing dependency list +for the service. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. + +```json +{ + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "description": { + "type": "string" + }, + "_exist": { + "type": "boolean", + "readOnly": true + }, + "status": { + "type": "string", + "enum": [ + "Running", "Stopped", "Paused", + "StartPending", "StopPending", "PausePending", "ContinuePending" + ] + }, + "startType": { + "type": "string", + "enum": ["Automatic", "AutomaticDelayedStart", "Manual", "Disabled"] + }, + "executablePath": { + "type": "string" + }, + "logonAccount": { + "type": "string" + }, + "errorControl": { + "type": "string", + "enum": ["Ignore", "Normal", "Severe", "Critical"] + }, + "dependencies": { + "type": "array", + "items": { + "type": "string" + } + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid arguments +- [2](#exit-code-2) - Invalid input +- [3](#exit-code-3) - Service error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed because required arguments were missing or the operation +name was not recognized. + +### Exit code 2 + +Indicates the resource operation failed because the JSON input could not be deserialized into a +valid `WindowsService` instance. + +### Exit code 3 + +Indicates the resource operation failed due to an error raised by the Windows Service Control +Manager API, or the result could not be serialized. + +## See also + +- [Microsoft.Windows/Registry resource][06] +- [DSC resource capabilities][01] +- [DSC resource properties][07] + + +[01]: ../../../../../concepts/resources/capabilities.md +[02]: ./examples/get-service-status.md +[03]: ./examples/configure-windows-service.md +[04]: ../../../../../concepts/resources/properties.md#key-resource-properties +[05]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[06]: ../Registry/index.md +[07]: ../../../../../concepts/resources/properties.md