Skip to content

docs: Add reference documentation for Microsoft.Windows/Service#1522

Open
Gijsreyn wants to merge 1 commit into
PowerShell:mainfrom
Gijsreyn:update-winservice-docs
Open

docs: Add reference documentation for Microsoft.Windows/Service#1522
Gijsreyn wants to merge 1 commit into
PowerShell:mainfrom
Gijsreyn:update-winservice-docs

Conversation

@Gijsreyn
Copy link
Copy Markdown
Collaborator

@Gijsreyn Gijsreyn commented May 9, 2026

PR Summary

This pull request adds reference documentation for the built-in DSC resource Microsoft.Windows/Service. I've tried to do my best to follow proper syntax to easily get it merged on Microsoft Learn + redacted/omitted data to make it life version independently.

Copilot AI review requested due to automatic review settings May 9, 2026 09:26
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds Microsoft Learn–style reference documentation for the built-in DSC resource Microsoft.Windows/Service, including example docs and a sample configuration file.

Changes:

  • Added the main Microsoft.Windows/Service resource reference page (properties, schema, exit codes, links).
  • Added example documentation for dsc resource get / dsc resource export.
  • Added an example DSC configuration document showing how to configure service status/start type.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File Description
docs/reference/resources/Microsoft/Windows/Service/index.md New reference page for the Microsoft.Windows/Service resource (metadata, properties, schema, exit codes).
docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml Sample configuration document defining two Microsoft.Windows/Service instances.
docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md Example page demonstrating dsc resource get and dsc resource export.
docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md Example page demonstrating how to apply a configuration document with dsc config test/set.

Comment thread docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md Outdated
Comment on lines +108 to +112
- **Read-only properties:** <a id="read-only-properties"></a> 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][06].

- [_exist](#_exist) - Indicates whether the service exists in the Service Control Manager.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a departure from the canonical property contract, which states (emphasis mine):

The _exist canonical property indicates that the resource can enforce whether instances exist, handling whether an instance should be added, updated, or removed during a set operation. This property provides shared semantics for DSC Resources and integrating tools. Resources that define this property indicate to DSC that they adhere to the contract for the canonical property.

Resources should only define this property when their implementation adheres to the following behavior contract:

  1. When the desired state for _exist is true, the resource expects the instance to exist. If it doesn't exist, the resource creates or adds the instance during the set operation.
  2. When the desired state for _exist is false, the resource expects the instance to not exist. If it does exist, the resource deletes or removes the instance during the set operation.
  3. When the get operation queries for an instance that doesn't exist, the returned JSON always defines the _exist property as false.

If we're not intending to support creation/deletion, we should rename this property to not include the _ prefix for the canonical property (or to a different name entirely)

Otherwise we should update the resource to support creating and deleting services.

Comment on lines +132 to +133
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`.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This indicates to me that we probably should just mark name as required - when we implement separate schemas for export filters, name would be optional there.

The other way to represent this in the JSON schema would be with the following snippet:

anyOf:
- required: [name]
- required: [displayName]

Which would fail validation for an instance when neither of those properties are defined.

Unfortunately, we don't have a way to make the schemas operation specific at this time.

I think we want to keep export as a special case though and require the same instance schema for all other operations. By that design, the name field should be required and displayName always optional.

@michaeltlombardi michaeltlombardi force-pushed the update-winservice-docs branch from f122076 to 6a12ce7 Compare May 13, 2026 16:29
Copy link
Copy Markdown
Collaborator

@michaeltlombardi michaeltlombardi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completed editorial pass, ready for final technical review and merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants