Canonical DSCv3 properties for adapted resources
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 523
- Forks
- 75
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 24
Description
Summary of the new feature / enhancement
As a PowerShell developer writing resources for use in v3 and compatible with PSDSC v1/v2, I want to ensure my resources participate as fully in the semantics of v3 as possible while continuing to write idiomatic PowerShell for my resources that works for PSDSC users.
As a configuration document author, I want to be able to define instances of resources that use canonical properties without having to be aware of how a given adapter handles those properties or remember differing conventions.
In PSDSC v1 and v2, resources used the Ensure (Present or Absent) convention generally, but not exclusively, for determining whether a resource should exist. In DSCv3, resources can define the _exist (true or false) canonical property for the same purpose, with the added benefit of DSC and higher order tools being able to add functionality for those resources (like know whether to call the delete operation or report messaging indicated a resource was created/updated/deleted).
In PowerShell, class properties are conventionally PascalCased. Having an _exist property beside Name, Version, etc is non-idiomatic and potentially confusing for users, who might naively think an underscore-prefixed property isn't meant to be used.
If the resource is implemented with the property as _exist, then everything works as-expected in the configuration document today, but creates a mismatch between PSDSC users experience and DSCv3 users. If the resource is implemented as Exist, then DSC and higher order tools need to use special handling for PSDSC resources.
Proposed technical implementation details (optional)
A few options come to mind:
-
Adapter translates the resource property for v3
In this case, the adapter would surface any resource with a boolean instance property called
Existthat defaults to$trueas_exist, using v3 semantics in v3 and idiomatic PowerShell in older versions of PSDSC. -
Resource authors define the class with the
_Existproperty and alias it toExistThis would enable v3/higher order tools to rely on the canonical property convention and non-v3 users/tools to use the more idiomatic
Existproperty name. -
Resource authors using the (not-yet-developed) Microsoft.Dsc PowerShell module could inherit from a class like
[DscResourceExistable]or some other convention that ensures the resource instance can handle defining both_existandExist
In this issue I'm pointing at the specific problem raised for the _exist property, but it isn't unique to that property - it applies equally to _purge and the other canonical properties.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the adapter behavior for canonical properties, especially _exist and _purge, and how adapted PowerShell resources are surfaced in DSCv3 versus PSDSC v1/v2. Compare the proposed translation, aliasing, and shared-base-class approaches; done means a decided, consistent convention that preserves idiomatic PowerShell while exposing canonical semantics.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell
- Domain
- devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100