(AB-118300) Draft Anatomy of a command-based DSC Resource#101
(AB-118300) Draft Anatomy of a command-based DSC Resource#101SteveL-MSFT merged 1 commit intoPowerShell:mainfrom michaeltlombardi:ab-118300/main/command-based-resource-anatomy
Conversation
sdwheeler
left a comment
sdwheeler
left a comment
There was a problem hiding this comment.
LGTM pending tech review from the Dev team.
docs/resources/concepts/anatomy.md
Outdated
| Command-based DSC Resources are defined with at least two files: | ||
|
|
||
| 1. A DSC Resource Manifest that tells DSC how to interact with the DSC Resource. | ||
| 1. One or more executable files, run by DSC, to manage instances of the DSC Resource. |
There was a problem hiding this comment.
Maybe reword as an executable and its dependencies? In the case of Python, for example, the resource shouldn't ship python but probably doc that it's a dependency (or whatever package manager they use to distribute has that relationship), so in that case it's probably just the manifest and the python script.
There was a problem hiding this comment.
I see this covered more in detail below, but it may still be worthwhile to say executable and dependencies rather than one or more executable files
docs/resources/concepts/anatomy.md
Outdated
|
|
||
| At a minimum, the DSC Resource Manifest must define: | ||
|
|
||
| - The version of DSC it's compatible with. |
There was a problem hiding this comment.
I think this is referring to the manifestVersion member which is currently 1.0.0. So it's not the version of DSC which is 3.0.0.
There was a problem hiding this comment.
Instead of manifestVersion, should this align with the configuration document and use $schema, limited to the versions of the schema we publish and support? This might also make broader integration easier.
There was a problem hiding this comment.
Filed #127 for the question/thinking around manifestVersion vs $schema.
docs/resources/concepts/anatomy.md
Outdated
| If the DSC Resource Manifest doesn't define how to test an instance of the DSC Resource, DSC | ||
| performs a synthetic test for instances of the DSC Resource. DSC's synthetic test always gets the | ||
| actual state of an instance and does a strict comparison of the DSC Resource's properties to the | ||
| desired state. If any of the properties aren't exactly the same as the defined desired state, DSC |
There was a problem hiding this comment.
It may be worth calling out that the synthetic test is case-sensitive and meta-properties (starting with _ or $) are skipped
There was a problem hiding this comment.
Are we planning for a way to allow DSC Resources to opt-in for case-insensitive comparisons? It might be frustrating to be forced to implement test only to do the equivalent of:
struct Settings {
Foo string
Bar int
Baz string
InDesiredState *bool `json:"_inDesiredState,omitempty"`
}
func Test(actual Settings, desired Settings) Settings (
inDesiredState := true
if (lower(actual.Foo) != lower(desired.Foo)) { indesiredState = false }
if (actual.Bar != desired.Bar) { indesiredState = false }
if (lower(actual.Baz) != lower(desired.Baz)) { indesiredState = false }
actual.InDesiredState = &inDesiredState
return actual
}
SteveL-MSFT
left a comment
SteveL-MSFT
left a comment
There was a problem hiding this comment.
Some suggestions and some general comments
docs/resources/concepts/anatomy.md
Outdated
| When DSC searches the local system for available command-based DSC Resources, it searches every | ||
| folder in the `PATH` for files that use the DSC Resource manifest naming convention. DSC then | ||
| parses each of those discovered files and validates them against the | ||
| [DSC Resource Manifest JSON schema][xx]. |
There was a problem hiding this comment.
Yes - can use the probable link for it on the assumption that #94 will merge.
This change adds a draft of the conceptual article defining the components of a command-based DSC Resource at a high-level, with information about what is required of them and how DSC uses them. This draft links to several articles that have not been written yet. Those drafts will be addressed in future PRs.
3 participants
PR Summary
This change adds a draft of the conceptual article defining the components of a command-based DSC Resource at a high-level, with information about what is required of them and how DSC uses them.
This draft links to several articles that have not been written yet. Those drafts will be addressed in future PRs.
PR Context
Conceptual documentation for command-based DSC Resources at a high level.