docs: Add reference documentation for Microsoft.Windows/Service#1522
docs: Add reference documentation for Microsoft.Windows/Service#1522Gijsreyn wants to merge 1 commit into
Microsoft.Windows/Service#1522Conversation
There was a problem hiding this comment.
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/Serviceresource 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. |
1be44ec to
f122076
Compare
| - **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. |
There was a problem hiding this comment.
This is a departure from the canonical property contract, which states (emphasis mine):
The
_existcanonical 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:
- When the desired state for
_exististrue, the resource expects the instance to exist. If it doesn't exist, the resource creates or adds the instance during the set operation.- When the desired state for
_existisfalse, the resource expects the instance to not exist. If it does exist, the resource deletes or removes the instance during the set operation.- When the get operation queries for an instance that doesn't exist, the returned JSON always defines the
_existproperty asfalse.
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.
| 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`. |
There was a problem hiding this comment.
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.
f122076 to
6a12ce7
Compare
michaeltlombardi
left a comment
There was a problem hiding this comment.
Completed editorial pass, ready for final technical review and merge.
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.