PowerShell / PowerShell/DSC

Design Document: Built-in resources

Open
#1,539 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Doc-Impact
Dominant language
Rust
Stars
523
Forks
75
Avg merge
3d 16h
Merged PRs (30d)
24

Description

We need to define some design principles for built-in resources so we can ensure that the resources that ship with DSC follow best practices and provide first-class ergonomics to users. The built-in resources serve both as examples for resource design and will be among the most-used resources.

During the review for the 3.2 GA, I noticed a few specific design principles we should call out. The following list is non-exhaustive:

  1. Only define the _exist canonical property at the top-level for a resource instance JSON Schema and only when the resource can both create and delete instances. The resource must implement the canonical property in adherence to the contract. Don't define _exist for nested instances of a *List resource, since those instances can't participate in the engine semantics for existence.
  2. When a resource has the _exist canonical property it should implement the get, set, export, and delete operations.
  3. Always implement what-if support for set and delete operations.
  4. Always return all non-write-only properties for the actual state of a resource if those property values are knowable. If the values are not knowable for a given operation, omit those properties from the return data. In JSON Schema defining a property as null and omitting the property are semantically distinct representations of data. Only populate a field with null when that actually matches the underlying resource behavior (when the resource has a nullable property, rather than an unset or undiscoverable property value).
  5. Always mark properties that can be passed to but not returned by the resource with the writeOnly keyword.
  6. Always mark properties that can be returned by but not passed to the resource with the readOnly keyword.
  7. Never add null as a valid value for a property in the instance JSON Schema when null indicates that you aren't passing a value for the property. Only allow null for properties where null is a valid value for that property.
  8. When creating a *List resource to manage multiple instances, also be sure to create a companion resource that manages a single instance. We should direct users towards the *List resource options only when the performance impact for single instances is too high. Those resources are much less ergonomic for result output and are somewhat obfuscated in the node graph. Using those resources necessitates tradeoffs in ergonomics for authoring vs reporting and performance vs clarity.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No file, test, or entry point is named in the issue. Define and document the design principles for built-in resources, including the listed schema, operation, what-if, property, nullability, and companion-resource requirements; done means the principles are recorded as an agreed design document.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.