PowerShell / PowerShell/DSC

Canonical DSCv3 properties for adapted resources

Open
#546 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue-Enhancement Needs Triage
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:

  1. Adapter translates the resource property for v3

    In this case, the adapter would surface any resource with a boolean instance property called Exist that defaults to $true as _exist, using v3 semantics in v3 and idiomatic PowerShell in older versions of PSDSC.

  2. Resource authors define the class with the _Exist property and alias it to Exist

    This would enable v3/higher order tools to rely on the canonical property convention and non-v3 users/tools to use the more idiomatic Exist property name.

  3. 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 _exist and Exist

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.