From 94286d9a2e8fcb9ec8901e322399cde3747eb51d Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Thu, 13 Jul 2023 17:56:10 -0500 Subject: [PATCH] (AB-118300) Draft Anatomy of a command-based DSC Resource 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. --- docs/resources/concepts/anatomy.md | 137 +++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/resources/concepts/anatomy.md diff --git a/docs/resources/concepts/anatomy.md b/docs/resources/concepts/anatomy.md new file mode 100644 index 00000000..467e3d43 --- /dev/null +++ b/docs/resources/concepts/anatomy.md @@ -0,0 +1,137 @@ +--- +author: michaeltlombardi +title: Anatomy of a command-based DSC Resource +description: >- + Describes the components of a command-based DSC Resource, how DSC uses them, and what's required + of them. +ms.author: mlombardi +ms.topic: concept-article +ms.date: 2023-07-13 +--- + +# Anatomy of a command-based DSC Resource + +DSC Resources provide a standardized interface for managing the settings of a system. A resource +defines properties you can manage and implements the code needed to get an instance of the +resource. + +Command-based DSC Resources are defined with at least two files: + +1. A DSC Resource manifest that tells DSC how to interact with the resource. +1. One or more executable files and their dependencies to manage instances of the resource. + +## DSC Resource manifests + +DSC Resource manifests are defined as JSON files. For DSC to recognize a JSON file as a manifest, +the file must meet the following criteria: + +1. The file must be discoverable in the `PATH` environment variable. +1. The filename must end with `.dsc.resource.json`. + +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][01]. + +If the JSON file validates against the schema, DSC can use the DSC Resource. + +At a minimum, the manifest must define: + +- The version of the DSC Resource Manifest JSON schema it's compatible with. +- The fully qualified name of the resource, like `Microsoft.Windows/Registry`. The fully qualified + name syntax is `[.][.]/`. The group and area components of the fully + qualified name enable organizing resources into namespaces. +- How DSC can call the command to get the current state of a resource instance. +- A way to validate an instance. This can be one of the following: + - A JSON schema that describes an instance + - A command DSC must call to get the schema at runtime + - A command to validate nested DSC Resources. This last option only applies to DSC Group + Resources and DSC Provider Resources. + +The manifest may optionally define: + +- How DSC can call the command to test whether an instance is in the desired + state. +- How DSC can call the command to set an instance to the desired state. +- The meaning of the non-zero exit codes returned by the command. +- How DSC can call the command to manage other DSC Resources, when the resource is a DSC Group + Resource or a DSC Provider Resource. +- Metadata about the resource, like its author and a short description. + +If the manifest doesn't define how to test an instance of the resource, DSC performs a synthetic +test for resource instances. DSC's synthetic test always gets the actual state of an instance and +does a strict case-sensitive comparison of the instance's properties to the desired state. The +synthetic test ignores any properties prefixed with an underscore (`_`) or dollar sign (`$`). If +any of the properties aren't exactly the same as the defined desired state, DSC reports the +instance as being non-compliant. + +If the manifest doesn't define how to set an instance of the DSC Resource, DSC can't use the +resource to enforce desired state. + +The manifest doesn't need to specify the same executable file for every operation. The definition +for each operation is independent. + +For more information on authoring DSC Resource manifests, see +[Authoring a DSC Resource Manifest][02]. + +## DSC Resource executables + +Command-based DSC Resources always require an executable file for DSC to run. The DSC Resource +Manifest doesn't need to be bundled with the executable. The executable can be any executable file, +such as a binary application or a shell script. A resource may use different executables for +different operations. + +For DSC to use an executable, it must be discoverable in the `PATH` environment variable. DSC calls +the executable once per operation, using the exit code returned by the executable to determine if +the command was successful. DSC treats exit code `0` as a success and all other exit codes as an +error. For more information about error handling, see +[Handling errors in a command-based DSC Resource][03]. + +### Inputs + +DSC sends input to command-based DSC Resources as either a JSON data blob over stdin or as a set of +argument flags and values. Input handling is defined per-operation in the DSC Resource Manifest. + +When DSC sends the input as JSON over stdin, the data blob is the JSON representation of an +instance's desired state. This is the most robust option for a resource, as it enables the resource +to support complex properties with nested objects. + +When DSC sends the input as arguments, it generates a pair of arguments for each of the specified +properties. The first argument is the name of the property prefixed with `--`, such as +`--duration`. The second argument is the property's value. The ordering of the argument pairs isn't +guaranteed. This input method doesn't support complex properties. + +### Outputs + +The executable for a command-based DSC Resource must return JSON data to stdout when called by DSC. +The output encoding must be UTF-8. When the resource returns the state of an instance, DSC +validates the JSON data against the resource's instance schema. + +For DSC Provider Resources, DSC expects the executable to pass through the instance states for the +resources it manages as either a single JSON array or as a series of [JSON Lines][04]. + +Command-based DSC Resources can report logging information to DSC by emitting JSON Lines to stderr. +Each log entry must be a JSON object that includes two keys: + +1. The `message` key defines the human-readable string for the log entry. +1. The `level` key defines whether the message represents an `Error`, a `Warning`, or `Information`. + +DSC collects messages from resources and displays them in the results for a configuration +operation. When DSC invokes a resource directly outside of a configuration, it doesn't collect the +messages. Instead, they're just emitted to stderr. + +For more information about logging from command-based DSC Resources, see +[Logging messages from a command-based DSC Resource][05]. + +## Related Content + +- [Authoring a DSC Resource Manifest][02] +- [Write a command-based DSC Resource][06] +- [DSC Resource Manifest schema reference][01] + +[01]: ../../reference/schemas/resource/manifest/root.md +[02]: authoring-a-manifest.md +[03]: handling-errors.md +[04]: https://jsonlines.org/ +[05]: logging-messages.md +[06]: write-a-command-based-resource.md