diff --git a/docs/concepts/configuration-documents/overview.md b/docs/concepts/configuration-documents/overview.md new file mode 100644 index 00000000..c1a23139 --- /dev/null +++ b/docs/concepts/configuration-documents/overview.md @@ -0,0 +1,255 @@ +--- +description: >- + DSC configuration documents are YAML or JSON data files that define the desired state of a system + declaratively. They're used to retrieve, validate, and enforce the state of multiple resource + instances. +ms.date: 03/25/2025 +title: DSC configuration documents +--- + +# DSC configuration documents + + + +In Microsoft's Desired State Configuration (DSC) platform, DSC configuration documents declare the +desired state of a system as data files. Configuration documents define a collection of +[DSC resource][01] instances to describe what the desired state should be, not how to put the +system into that state. The DSC resources handle the _how_ for each instance. + +DSC can process configuration documents to: + +- Retrieve the current state of the defined resource instances with the `dsc config get` command. +- Validate whether the instances are in the desired state with the `dsc config test` command. +- Enforce the desired state for the instances with the `dsc config set` command. +- Export a new configuration document with every instance of a set of resources with the + `dsc config export` command. + +Configuration documents are YAML or JSON files that contain a single object. The object's +properties define how DSC processes the document. The top-level properties for a document are: + +- `$schema` (required) - Defines the URI for the JSON Schema the document adheres to. DSC + uses this URI to know how to validate and interpret the document. +- `resources` (required) - Defines the collection of resource instances the document manages. +- `metadata` (optional) - Defines an arbitrary set of annotations for the document. Except for + metadata within the `Microsoft.DSC` property, DSC doesn't validate this data or use it directly. + The annotations can include notes like who authored the document, the last time someone updated + it, or any other information. DSC doesn't use the annotations. The metadata is for documentation + or other tools to use. + + DSC applies validation to the `Microsoft.DSC` property. For more information, see the + [DSC Configuration document metadata schema][02] reference. +- `parameters` (optional) - Defines a set of runtime options for the configuration. Resource + instances can reference parameters to reduce duplicate definitions or enable dynamic values. + Parameters can have default values and can be set on any configuration operation. +- `variables` (optional) - Defines a set of reusable values for the configuration. Resource + instances can reference variables to reduce duplicate definitions. + +## Defining a configuration document + +Minimally, a configuration document defines the `$schema` and `resources` properties. The +`$schema` property must be a valid URI for the DSC configuration document schema. The `resources` +property must define at least one DSC Resource instance. + +For example: + +```yaml +# example.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: example key value + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example\key + valueName: Example + valueData: + String: This is an example. +``` + +The example document defines a single resource instance named `example key value`. The instance +uses the `Microsoft.Windows/Registry` resource to declare the following desired state: + +- The `example\key` registry key should exist in the system's current user hive. +- The `example\key` registry key should have a value called `Example`. +- The `Example` value should be the string `This is an example`. + +The example document is _declarative_. It describes the desired state, not how to put the system +into that state. It relies on the `Microsoft.Windows/Registry` resource to handle getting, testing, +and setting the state of the registry key and value. + +For more information about the structure and validation of configuration documents, see +[DSC Configuration document schema reference][03]. + +### Defining resource instances + +As shown in the prior example, configuration documents include a collection of resource instances. +Together, the instances describe the desired state of a system. A configuration document can +include any number of resource instances. + +A resource instance declaration always includes: + +- `name` - A short, human-readable name for the instance that's unique in the document. This name + is used for logging and it helps describe the purpose of the instance. +- `type` - The [fully qualified type name][04] of the resource that DSC should use to manage the + instance. +- `properties` - The desired state for the instance. DSC validates the values against the + resource's instance schema. + +Configuration documents can't include the same instance more than once. Declaring the same instance +with different properties leads to enforcement cycling, where each declaration enforces an +incompatible state for the instance on every run. + +## Getting the current state of a configuration + +The `dsc config get` command retrieves the current state of the resource instances defined in a +configuration document. When you use this command, DSC also: + +- Collects any message emitted by the resources during the operation. +- Indicates whether any of the resources raised an error. +- Provides metadata about the operation as a whole and for each resource instance. + +```sh +dsc config get --file ./example.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-02-24T16:09:40.671454400-06:00 + endDatetime: 2025-02-24T16:09:41.850086300-06:00 + duration: PT1.1786319S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.2751153S + name: example key value + type: Microsoft.Windows/Registry + result: + actualState: + keyPath: HKCU\example\key + _exist: false +messages: [] +hadErrors: false +``` + +## Testing a configuration + +The `dsc config test` command compares the current state of the resource instances to their desired +state. The result for each instance includes: + +- The desired state for the instance. +- The actual state of the instance. +- Whether the instance is in the desired state. +- The list of properties that are out of the desired state, if any. + +When you use this command, DSC also: + +- Collects any message emitted by the resources during the operation. +- Indicates whether any of the resources raised an error. +- Provides metadata about the operation as a whole and for each resource instance. + +```sh +dsc config test --file /example.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: test + executionType: actual + startDatetime: 2025-02-24T16:11:42.798122500-06:00 + endDatetime: 2025-02-24T16:11:43.442216400-06:00 + duration: PT0.6440939S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.2234078S + name: example key value + type: Microsoft.Windows/Registry + result: + desiredState: + keyPath: HKCU\example\key + valueName: Example + valueData: + String: This is an example. + actualState: + keyPath: HKCU\example\key + _exist: false + inDesiredState: false + differingProperties: + - valueName + - valueData + - _exist +messages: [] +hadErrors: false +``` + +## Enforcing a configuration + +The `dsc config set` command enforces the resource instances defined in a configuration document to +their desired state. The result for each instance includes: + +- The state of the instance before the operation. +- The state of the instance after the operation. +- Which properties the operation changed, if any. + +When you use this command, DSC also: + +- Collects any message emitted by the resources during the operation. +- Indicates whether any of the resources raised an error. +- Provides metadata about the operation as a whole and for each resource instance. + +```sh +dsc config set --file ./example.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-02-24T16:13:32.746742600-06:00 + endDatetime: 2025-02-24T16:13:33.606785-06:00 + duration: PT0.8600424S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.4070001S + name: example key value + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\example\key + _exist: false + afterState: + keyPath: HKCU\example\key + valueName: Example + valueData: + String: This is an example. + changedProperties: + - valueName + - valueData + - _exist +messages: [] +hadErrors: false +``` + +## See also + +- [DSC Resources][01] to learn about resources. +- [DSC Configuration document schema reference][05] +- [Command line reference for the 'dsc config' command][06] + +[01]: ../resources/overview.md +[02]: ../../reference/schemas/config/metadata.md#microsoftdsc +[03]: ../../reference/schemas/config/document.md +[04]: ../resources/overview.md#resource-type-names +[05]: ../../reference/schemas/config/document.md +[06]: ../../reference/cli/config/index.md diff --git a/docs/concepts/enhanced-authoring.md b/docs/concepts/enhanced-authoring.md new file mode 100644 index 00000000..91d7edb8 --- /dev/null +++ b/docs/concepts/enhanced-authoring.md @@ -0,0 +1,193 @@ +--- +description: >- + DSC configuration documents and resource manifests are YAML or JSON data files that adhere to a + published JSON schema. You can use enhanced schemas when authoring these files for an improved + experience. +ms.date: 03/25/2025 +title: Authoring with enhanced schemas +--- + +# Authoring with enhanced schemas + + + +Working with Microsoft's Desired State Configuration (DSC) platform involves writing DSC +[configuration documents][01] and [resource manifests][02]. Configuration documents are YAML or +JSON data files that declare the desired state of a system. Resource manifests are JSON or YAML +data files that define a DSC command resource. + +DSC validates these data files with a JSON schema. While the schemas DSC uses for validation are +useful for authoring configuration documents and resource manifests, Microsoft also defines a set +of enhanced schemas for authoring the files in VS Code. These schemas define extra keywords +specific to VS Code that: + +- Improve the contextual help when hovering on or selecting a property in the data file. +- Add contextual help for enum values. +- Improve the error messages for invalid values. +- Provide IntelliSense and default snippets. + +> [!NOTE] +> The enhanced schemas are noncanonical. Only specify them for the `$schema` keyword in a +> configuration document or resource manifest when your tools support it. +> +> These schemas are only for improving the authoring experience. If you try to validate the +> configuration document or resource manifest with a tool that doesn't support the extended +> vocabulary, the tool might raise an error. +> +> The enhanced schemas share the same source definition as the canonical schemas and validate the +> data in the same way. However, they include noncanonical keywords. For maximum compatibility +> with other tools, the canonical schemas only use the core JSON schema vocabularies. + +For the full list of recognized and supported schema URIs, including the enhanced authoring +schemas, see the `$schema` sections in [DSC Configuration document schema reference][03] and +[DSC resource manifest schema reference][04]. + +## Enhanced schema examples + +### Example 1 - Documentation on hover + + +:::image type="complex" source="media/enhanced-authoring/hover-help.png" alt-text="This screenshot shows enhanced hover documentation."::: + This screenshot shows enhanced hover documentation for the 'type' property in a configuration document. The documentation includes a link at the top to the online documentation, followed by prose explaining the syntax for the property. +:::image-end::: + + +With the enhanced schemas, hovering on a property displays contextual help rendered from Markdown. +When possible, the hover help includes a link to the online documentation. + +### Example 2 - IntelliSense quick info + + +:::image type="complex" source="media/enhanced-authoring/peek-help.png" alt-text="This screenshot shows enhanced documentation with autocomplete."::: + This screenshot shows the DSC Resource instance autocomplete option and contextual documentation in a configuration document. The contextual help is shown to the side of the completion option list. The help includes a link to the online documentation, the descriptive prose, and the required properties. +:::image-end::: + + +When you use IntelliSense while authoring with an enhanced schema, the quick info shown for the +completion options displays as rendered Markdown. When possible, the quick info includes a link to +the online documentation. + +### Example 3 - Enum documentation + + +:::image type="complex" source="media/enhanced-authoring/enum-help.png" alt-text="This screenshot shows contextual documentation for an enum."::: + This screenshot shows the contextual documentation for the 'return' property enum values in a resource manifest. The contextual help is shown beneath the enum list, describing the currently selected value. +:::image-end::: + + +The enhanced schemas add documentation for enum values when using IntelliSense to select a valid +value. By default, schemas can't provide per-enum documentation. They can only define documentation +for the property an enum belongs to. + +### Example 4 - Snippets + + +:::image type="complex" source="media/enhanced-authoring/snippet-selection.png" alt-text="This screenshot shows autocomplete snippet options with documentation."::: + This screenshot shows the autocomplete snippets for the metadata section in a configuration document. The currently selected snippet displays contextual help. +:::image-end::: + +:::image type="complex" source="media/enhanced-authoring/snippet-completion.png" alt-text="This screenshot shows the editable output for the chosen snippet."::: + This screenshot shows the editable output for the 'New metadata property (object)' snippet. It defined a new property named 'metadataName' with a nested key-value pair. The property name, key, and value are editable text that a user can tab through, like any other VS Code snippet. +:::image-end::: + + +For common use cases, the enhanced schemas define sets of default snippets. These snippets are +contextual and make it easier and faster to define the file. The snippets work like any other +snippets in VS Code. + +### Example 5 - Error messages + + +:::image type="complex" source="media/enhanced-authoring/error-messages.png" alt-text="This screenshot shows an enhanced error message for failed validation."::: + This screenshot shows a contextual error message when the name property for a resource instance doesn't match the validating regular expression. The value is the string 'invalid?' and the error message says "Invalid value for instance name. An instance name must be a nonempty string containing only letters, numbers, and spaces." +:::image-end::: + + +When you define values, the enhanced schemas provide contextual error messages instead of the +default error messages that JSON schema validation raises. These messages are helpful for +properties that must match a regular expression, where the default message just indicates that the +value is invalid and lists the regular expression pattern. + +## Using the enhanced configuration document schema + +To associate every configuration document with the enhanced schema, add the following snippet to +your `settings.json` file in VS Code. You can define these options in your user settings or for a +specific workspace. + + +```json +"json.schemas": [ + { + "fileMatch": [ + "**/*.dsc.json", + "**/*.dsc.config.json" + ], + "url": "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json" + } +], +"yaml.schemas": { + "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}" +} +``` + + +These settings depend on the configuration documents having a name that ends with one of the +following suffixes: + +- `.dsc.config.json` +- `.dsc.config.yaml` +- `.dsc.config.yml` +- `.dsc.json` +- `.dsc.yaml` +- `.dsc.yml` + +To associate a specific configuration document formatted as YAML with the enhanced schema, add the +following comment to the top of the document: + + +```yml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +``` + + +This option works regardless of the filename, but only for YAML files. To use the enhanced schema +when authoring configuration documents in JSON, you must define the schema association in your +`settings.json`. + +## Using the enhanced resource manifest schema + +To use the enhanced schema when authoring resource manifests, add the following snippet to +your `settings.json` file in VS Code. You can define this option in your user settings or for a +specific workspace. + + +```json +"json.schemas": [ + { + "fileMatch": ["**/*.dsc.resource.json", ], + "url": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json" + } +] +"yaml.schemas": { + "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}" +} +``` + + +To associate a specific resource manifest formatted as YAML with the enhanced schema, add the +following comment to the top of the manifest: + + +```yml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +``` + + +This option works regardless of the filename, but only for YAML files. To use the enhanced schema +when authoring resource manifests in JSON, you must define the schema association in your +`settings.json`. + +[01]: ./configuration-documents/overview.md +[02]: ./resources/anatomy.md#dsc-resource-manifests +[03]: ../reference/schemas/config/document.md#schema +[04]: ../reference/schemas/resource/manifest/root.md#schema diff --git a/docs/concepts/media/enhanced-authoring/enum-help.png b/docs/concepts/media/enhanced-authoring/enum-help.png new file mode 100644 index 00000000..8e533204 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/enum-help.png differ diff --git a/docs/concepts/media/enhanced-authoring/error-messages.png b/docs/concepts/media/enhanced-authoring/error-messages.png new file mode 100644 index 00000000..1d145767 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/error-messages.png differ diff --git a/docs/concepts/media/enhanced-authoring/hover-help.png b/docs/concepts/media/enhanced-authoring/hover-help.png new file mode 100644 index 00000000..fe9e8da4 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/hover-help.png differ diff --git a/docs/concepts/media/enhanced-authoring/peek-help.png b/docs/concepts/media/enhanced-authoring/peek-help.png new file mode 100644 index 00000000..6d960cc1 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/peek-help.png differ diff --git a/docs/concepts/media/enhanced-authoring/snippet-completion.png b/docs/concepts/media/enhanced-authoring/snippet-completion.png new file mode 100644 index 00000000..a07aee49 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/snippet-completion.png differ diff --git a/docs/concepts/media/enhanced-authoring/snippet-selection.png b/docs/concepts/media/enhanced-authoring/snippet-selection.png new file mode 100644 index 00000000..46c63f80 Binary files /dev/null and b/docs/concepts/media/enhanced-authoring/snippet-selection.png differ diff --git a/docs/concepts/output-accessibility.md b/docs/concepts/output-accessibility.md new file mode 100644 index 00000000..4b403b49 --- /dev/null +++ b/docs/concepts/output-accessibility.md @@ -0,0 +1,118 @@ +--- +description: >- + This article aims to guide you through methods to output from PowerShell in formats that are + friendly for screen readers, enhancing the accessibility of your scripts. +ms.custom: experience +ms.date: 03/25/2025 +title: Improve the accessibility of DSC output in PowerShell +--- + +# Improve the accessibility of DSC output in PowerShell + +Most terminal environments only display raw text. Users that rely on screen readers are faced with +tedious narration when consuming large amounts of raw text because the raw output doesn't have the +accessibility metadata to characterize the format of the content. + +There are two ways to improve the accessibility of the output in PowerShell: + +- Output the data in a way that it can be viewed in another tool that supports screen reading + technologies. +- Reduce the amount of output displayed in the terminal by filtering and selecting the data you + want and output the text in a more readable format. + +## Display the data in a tool outside of the terminal + +For large amounts of data, rather than output to the host, consider writing output in a format that +can be viewed in another tool that supports screen reading technologies. You might need to save the +data to a file in a format that can be opened in another application. + +### Out-GridView command on Windows + +For small to moderate size output, use the `Out-GridView` command. The output is rendered using +Windows Presentation Foundation (WPF) in tabular form, much like a spreadsheet. The GridView +control allows you to sort, filter, and search the data, which reduces the amount of data that +needs to be read. The GridView control is also accessible to screen readers. The **Narrator** tool +built into Windows is able to read the GridView details, including column names and row count. + +The following example shows how to display a list of DSC resources in a GridView control. + +```powershell +dsc resource list | ConvertFrom-Json | Out-GridView +``` + +The following example shows how to display a list of DSC adapted resources in a GridView control. + +```powershell +dsc resource list -a Microsoft.Windows/WindowsPowerShell | + ConvertFrom-Json | + Out-GridView +``` + +The `Out-GridView` command is only available in PowerShell on Windows. + +### Character Separated Value (CSV) format + +Spreadsheet applications such as **Microsoft Excel** support CSV files. The following example shows +how to save the output of a command to a CSV file. + +```powershell +dsc resource list | ConvertFrom-Json | Export-Csv -Path .\myFile.csv +Invoke-Item .\myFile.csv +``` + +The `Invoke-Item` command opens the file in the default application for CSV files. + +### HyperText Markup Language (HTML) format + +HTML files can be viewed by web browsers such as **Microsoft Edge**. The following example shows +how to save the output of a command to an HTML file. + +```powershell +dsc resource list | ConvertFrom-Json | ConvertTo-HTML | Out-File .\myFile.html +Invoke-Item .\myFile.html +``` + +The `Invoke-Item` command opens the file in your default web browser. + +## Reduce the amount of output + +One way to improve the accessibility of the output is to reduce the amount of output displayed in +the terminal. PowerShell has several commands that can help you filter and select the data you +want. + +### Select and filter data + +Rather than returning a large mount of data, use commands such as `Select-Object`, `Sort-Object`, +and `Where-Object` to reduce the amount of output. The following example gets the list of Windows +PowerShell DSC resources that manage processes on the computer. + +Each of the following commands improves the output in a different way: + +- The `Where-Object` command reduces the number of items returned by filtering the list to only + show resources that have the word `process` in their type name. +- The `Select-Object` command selects only the resource type name, kind, and version. +- The `Format-List` command displays the output in list format, which provides a better narration + experience for screen readers. + +```powershell +dsc resource list -a Microsoft.Windows/WindowsPowerShell | + ConvertFrom-Json | + Where-Object {$_.type -like "*process*" } | + Select-Object -Property Type, Kind, Version | + Format-List +``` + +## Related content + +- [Improve the accessibility of output in PowerShell][01] +- [Out-GridView][02] +- [Export-Csv][03] +- [ConvertTo-Html][04] +- [about_Calculated_Properties][05] + + +[01]: /powershell/scripting/learn/shell/output-for-screen-reader +[02]: xref:Microsoft.PowerShell.Utility.Out-GridView +[03]: xref:Microsoft.PowerShell.Utility.Export-Csv +[04]: xref:Microsoft.PowerShell.Utility.ConvertTo-Html +[05]: /powershell/module/microsoft.powershell.core/about/about_calculated_properties diff --git a/docs/concepts/resources/anatomy.md b/docs/concepts/resources/anatomy.md new file mode 100644 index 00000000..1955fe11 --- /dev/null +++ b/docs/concepts/resources/anatomy.md @@ -0,0 +1,148 @@ +--- +description: >- + Describes the components of a DSC command resource, how DSC uses them, and what DSC requires of + them. +ms.date: 03/25/2025 +title: Anatomy of a command-based DSC Resource +--- + +# 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. + +DSC command 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 data files. For DSC to recognize a data file as a manifest, +the file must meet the following criteria: + +1. The data in the file must be formatted as YAML or JSON. +1. The file must use UTF-8 encoding. +1. The file must be discoverable in the `PATH` environment variable. +1. The filename must end with one of the following suffixes: + + - `.dsc.resource.json` + - `.dsc.resource.yaml` + - `.dsc.resource.yml` + +When DSC searches the local system for available command 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. Options for validating an instance include: + - 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 adapter resources. + +The manifest can define: + +- The kind of resource the manifest describes: `adapter`, `group`, `importer`, or `resource`. + + If the manifest doesn't define the resource kind, it defaults to `resource` and is interpreted as + a typical resource that directly manages an instance. +- How DSC can call the command to test whether an instance is in the desired state. + + 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. If any + of the properties aren't exactly the same as the defined desired state, DSC reports the instance + as being non-compliant. +- How DSC can call the command to set an instance to the desired state. + + 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 meaning of the nonzero exit codes returned by the command. + + If the manifest doesn't define the meaning for exit codes, all nonzero exit codes are reported + as a generic failure. +- How DSC can call the command to export a list of every instance of that resource on the machine. +- How DSC can call the command to delete a specific instance of the resource. +- Metadata about the resource, like its author and a short description. + +The manifest doesn't need to specify the same executable file for every operation. The definition +for each operation is independent. + +## DSC resource executables + +Command resources always require an executable file for DSC to run. The 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 can 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. + +### Inputs + +DSC sends input to command resources in one of the following ways: + +- A JSON data blob over stdin. + + When DSC sends the input as JSON over stdin, the data blob is the JSON representation of an + instance's desired state. This input option supports complex properties with nested objects. +- A JSON data blob as the value to a specific argument. + + When the resource defines a JSON input argument, DSC invokes the command with the defined + argument and passes the JSON representation of an instance's desired state to that argument. This + input option supports complex properties with nested objects. +- A set of argument flags and values. + + 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. +- Environment variables. + + When DSC sends the input as environment variables, it defines an environment variable for each + property of the resource instance and sets the value to the string representation of that + property. These environment variables are only defined for the execution of the command for that + specific operation. The environment variables don't affect any other processes. + +Input handling is defined per-operation in the resource manifest. A resource can define different +input handling for the operations it supports. + +### Outputs + +The executable for a command 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 adapter 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 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, DSC emits the messages to stderr. + +## Related Content + +- [DSC Resource Manifest schema reference][01] +- [DSC Resources][02] + +[01]: ../../reference/schemas/resource/manifest/root.md +[02]: overview.md +[04]: https://jsonlines.org/ diff --git a/docs/concepts/resources/capabilities.md b/docs/concepts/resources/capabilities.md new file mode 100644 index 00000000..9327015e --- /dev/null +++ b/docs/concepts/resources/capabilities.md @@ -0,0 +1,177 @@ +--- +description: >- + Describes the capabilities of DSC resources, how DSC discovers them, and how + the capabilities affect resource behavior and usage. +ms.date: 03/25/2025 +ms.topic: conceptual +title: DSC resource capabilities +--- + +# DSC resource capabilities + +DSC resources always have at least one capability. Resource capabilities define the operations you +can invoke for a resource and how the resource behaves when invoked. + +The rest of this document describes the available capabilities. + +## get + +A resource with the `get` capability supports retrieving the current state of an instance with the +[Get][01] operation. + +A command resource has this capability when it defines the required [get][02] property in its +resource manifest. + +## set + +A resource with the `set` capability supports enforcing the desired state of an instance with the +[Set][03] operation. Resources without this capability can't be used with the +[dsc resource set][04] or [dsc config set][05] commands unless they're defined in a +`Microsoft.DSC/Assertion` group as a nested instance. + +A command resource has this capability when it defines the [set][06] property in its resource +manifest. + +## setHandlesExist + +A resource with the `setHandlesExist` capability indicates that you can use the [Set][03] operation +to delete an instance. Resources with this capability must have the [_exist][07] canonical resource +property. Resources that don't have the `_exist` property never have this capability. + +When a resource has the `_exist` property but not the `setHandlesExist` capability: + +- If the resource has the `delete` capability, DSC invokes the [Delete][08] operation instead of + **Set** when the desired state for an instance defines `_exist` as false. +- If the resource doesn't have the `delete` capability, DSC raises an error during a **Set** + operation when the desired state for an instance defines _exist` as false. + +A command resource has this capability when it defines the [set.handlesExist][09] property as +`true` in its resource manifest. + +## whatIf + +A resource with the `whatIf` capability indicates that you can use the [Set][03] operation in +what-if mode to have the resource return explicit information about how it would modify state in an +actual **Set** operation. + +When a resource doesn't have this capability, DSC synthesizes how the resource would change an +instance by converting the **Test** result for the instance into a **Set** result. The +synthetic operation can't indicate potential issues or changes that can't be determined by +comparing the result of the **Test** operation against the resource's desired state. For example, +the credentials used to test a resource might be valid for that operation, but not have permissions +to actually modify the system state. Only a resource with this capability can fully report whether +and how the resource would change system state. + +A resource has this capability when it defines the [whatIf][10] property in its resource manifest. + +## test + +A resource with the `test` capability indicates that it implements the **Test** operation directly. +Resources with this capability must have the [_inDesiredState][11] canonical resource property. +Resources that don't have the `_inDesiredState` property never have this capability. + +When a resource doesn't have this capability, DSC uses a synthetic test for instances of the +resource. DSC performs the synthetic test by: + +1. Invoking the **Get** operation on the resource to retrieve the actual state of the instance. +1. Synthetically testing each property for the desired state of an instance against the actual + state returned. The synthetic test uses strict, case-sensitive equivalence. +1. If the desired state for a property and the actual state aren't the same, DSC marks the property + as out of the desired state. +1. If any properties are out of the desired state, DSC reports the entire instance as not being in + the desired state. + +Synthetic testing can't account for all resource behaviors. For example, if a package resource +allows users to define a version range for the package, the **Get** operation returns the +actual version of the package, like `1.2.3`. If the user specified the version range `~1` (NPM +syntax indicating the package should be latest released semantic version with major version `1`), +DSC would compare the desired state `~1` against the actual state `1.2.3` and consider the package +to be in the incorrect state, even if `1.2.3` is actually the latest release matching the version +pin. + +Any resource that has properties which can't use a strict case-sensitive comparison check should +have this capability. + +A command resource has this capability when it defines the [test][12] operation in its resource +manifest. + +## delete + +A resource with the `delete` capability supports removing an instance with the [Delete][08] +operation and the [dsc resource delete][13] command. + +This capability isn't mutually exclusive with the `setHandlesExist` property. A resource can handle +the `_exist` property in **Set** operations and be called directly with `dsc resource delete` to +remove an instance. + +For resources with the `delete` capability and the [_exist][07] canonical resource property: + +- If the resource doesn't have the [setHandlesExist](#sethandlesexist) capability, DSC invokes the + **Delete** operation for the resource instead of **Set** when the desired state defines `_exist` + as `false`. +- If the resource does have the `setHandlesExist` capability, DSC invokes the **Set** operation for + the resource when the desired state defines `_exist` as `false`. + +Resources with the `delete` capability that don't have the `_exist` canonical resource property +must implement their **Set** operation to handle removing instances. DSC can't infer existence +semantics without the `_exist` property. + +A command resource has this capability when it defines the [delete][14] property in its resource +manifest. + +## export + +A resource with the `export` capability supports enumerating every instance of the resource with +the **Export** operation. + +You can use resources with this capability with the following commands: + +- [dsc config export][15] to return a configuration document + representing the actual state for every instance of each resource defined in the input document. +- [dsc resource export][16] to return a configuration document + representing the actual state for every instance of the input resource. +- `dsc resource get` with the [--all][17] option to return + the actual state of every instance of the input resource. + +A command resource has this capability when it defines the [export][18] property in its resource +manifest. + +## resolve + +A resource with the `resolve` capability supports resolving nested resource instances from an +external source. This capability is primarily used by [importer resources][19] to enable users to +compose configuration documents. + +A command resource has this capability when it defines the [resolve][20] property in its resource +manifest. + +## See also + +- [DSC resource operations][21] +- [DSC resource kinds][22] +- [DSC resource properties][23] + + +[01]: operations.md#get-operation +[02]: ../../reference/schemas/resource/manifest/get.md +[03]: operations.md#set-operation +[04]: ../../reference/cli/resource/set.md +[05]: ../../reference/cli/config/set.md +[06]: ../../reference/schemas/resource/manifest/set.md +[07]: ../../reference/schemas/resource/properties/exist.md +[08]: operations.md#delete-operation +[09]: ../../reference/schemas/resource/manifest/set.md#handlesexist +[10]: ../../reference/schemas/resource/manifest/whatif.md +[11]: ../../reference/schemas/resource/properties/inDesiredState.md +[12]: ../../reference/schemas/resource/manifest/test.md +[13]: ../../reference/cli/resource/delete.md +[14]: ../../reference/schemas/resource/manifest/delete.md +[15]: ../../reference/cli/config/export.md +[16]: ../../reference/cli/resource/export.md +[17]: ../../reference/cli/resource/get.md#--all +[18]: ../../reference/schemas/resource/manifest/export.md +[19]: ../resources/kinds.md#importer-resources +[20]: ../../reference/schemas/resource/manifest/resolve.md +[21]: operations.md +[22]: kinds.md +[23]: ../../concepts/resources/properties.md diff --git a/docs/concepts/resources/instances.md b/docs/concepts/resources/instances.md new file mode 100644 index 00000000..e01b331e --- /dev/null +++ b/docs/concepts/resources/instances.md @@ -0,0 +1,351 @@ +--- +description: >- + Describes what a DSC resource instance is and how to use them with DSC. +ms.date: 03/25/2025 +ms.topic: conceptual +title: DSC resource instances +--- + +# DSC resource instances + +DSC resources manage _instances_ of a configurable component. For example, the +`Microsoft.Windows/Registry` resource manages Windows Registry keys and values. Each registry key +and value is a different instance of the resource. + +Every command resource defines a [resource instance schema][01] that describes how to validate and +manage an instance of the resource with a JSON Schema. [Adapter resources][02] implement the +[Validate operation][03] to enable validating adapted resource instances, which might not have JSON +Schemas to describe their properties. + +If you specify an invalid definition for a resource instance, DSC raises an error before invoking +any operations on the instance. + +## Nested resource instances + +The resource instances declared in [adapter resources][04] and [group resources][05] or resolved by +[importer resources][06] are called _nested resource instances_. + +For nested instances, a resource instance is _adjacent_ if: + +- The instance is declared in the same group or adapter instance. +- The instance is resolved from the same importer instance. + +A resource instance is _external_ to a nested instance if: + +- The instance is declared outside of the group or adapter instance +- The instance is resolved from a different importer instance +- The instance is nested inside an adjacent group, adapter, or importer instance. + +For top-level instances, other instances at the top-level are adjacent. All other instances are +external. + +Consider the following configuration snippet. It defines seven resource instances: + +- At the top-level, the configuration defines the `TopLevelEcho`, `TopLevelOSInfo`, and + `TopLevelGroup` instances. +- The `TopLevelGroup` instance defines the nested instances `NestedEcho` and `NestedGroup`. +- The `NestedGroup` instance defines the nested instances `DeeplyNestedEcho` and + `DeeplyNestedOSInfo`. + +```yaml +resources: +- name: TopLevelEcho + type: Microsoft.DSC.Debug/Echo + properties: { output: 'top level instance' } +- name: TopLevelOSInfo + type: Microsoft/OSInfo + properties: { } +- name: TopLevelGroup + type: Microsoft.DSC/Group + properties: + $schema: + resources: + - name: NestedEcho + type: Microsoft.DSC.Debug/Echo + properties: { output: 'nested instance' } + - name: NestedGroup + type: Microsoft.DSC/Group + properties: + $schema: + resources: + - name: DeeplyNestedEcho + type: Microsoft.DSC.Debug/Echo + properties: { output: 'deeply nested instance' } + - name: DeeplyNestedOSInfo + type: Microsoft/OSInfo + properties: { } +``` + +The following matrix defines the relations of each instance in the configuration: + +| | TopLevelEcho | TopLevelOSInfo | TopLevelGroup | NestedEcho | NestedGroup | DeeplyNestedEcho | DeeplyNestedOSInfo | +|------------------------|----------------|----------------|---------------|------------|-------------|------------------|--------------------| +| **TopLevelEcho** | Self | Adjacent | Adjacent | External | External | External | External | +| **TopLevelOSInfo** | Adjacent | Self | Adjacent | External | External | External | External | +| **TopLevelGroup** | Adjacent | Adjacent | Self | External | External | External | External | +| **NestedEcho** | External | External | External | Self | Adjacent | External | External | +| **NestedGroup** | External | External | External | Adjacent | Self | External | External | +| **DeeplyNestedEcho** | External | External | External | External | External | Self | Adjacent | +| **DeeplyNestedOSInfo** | External | External | External | External | External | Adjacent | Self | + +### Referencing nested instances + +Nested resource instances have limitations for the [dependsOn][07] property and the +[reference()][08] configuration function. + +1. You can only reference adjacent instances. You can't reference a nested instance from outside of + the instance that declares or resolves it. You can't use a reference to a resource outside of + the group, adapter, or importer resource for a nested instance. +1. You can only use the `dependsOn` property for adjacent instances. You must add a dependency on + the group, adapter, or importer instance, not a nested instance. Nested instances can't depend + on external instances. + +The following examples show valid and invalid references and dependencies. The examples use the +`Microsoft.DSC/Group` resource, but the functionality is the same for adapter and import resources. + +#### Example 1 - Valid references and dependencies + +This example configuration defines several valid references and dependencies. It also defines two +instances of the `Microsoft.DSC/Group` resource, one nested inside the other. + +The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the +top-level instance of the `Microsoft/OSInfo` resource. The top-level instances of the +`Microsoft.DSC.Debug/Echo` and `Microsoft/OSInfo` resources both depend on the top-level instance +of the `Microsoft.DSC/Group` resource. + +```yaml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +resources: +# The top level echo references and depends on the top-level OSInfo. +# It also depends on the top-level Group. +- name: Top level echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +# The top level OSInfo depends on the top-level Group. +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: # snipped for brevity +``` + +The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances: +`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the +`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested`Microsoft/OSInfo` +instance and that instance depends on the adjacent nested `Microsoft.DSC/Group` instance. + +```yaml +# Other top-level instances snipped for brevity +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + # The nested echo references and depends on the adjacent nested OSInfo. + - name: Nested echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" + # The nested OSInfo depends on the adjacent nested Group. + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} + - name: Nested Group + type: Microsoft.DSC/Group + properties: # snipped for brevity +``` + +Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply +nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance +of `Microsoft/OSInfo`. + +```yaml +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + # Snipped the Microsoft.DSC.Debug/Echo and Microsoft/OSInfo instances for brevity + - name: Nested Group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + # The deeply nested echo references and depends on the adjacent + # deeply nested OSInfo. + - name: Deeply nested echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" + - name: Deeply nested OSInfo + type: Microsoft/OSInfo + properties: {} +``` + +In every case, the references and dependencies are to adjacent instances in the configuration. +Instances at the top level only depend on or reference other instances at the top level. Instances +nested in the top-level group only depend on or reference other nested instances in the same group. +The deeply nested instances defined in the nested group only depend on or reference other deeply +nested instances in the same group. + +Putting the configuration together, you get this full document: + +```yaml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +# The top level echo references and depends on the top-level OSInfo. +- name: Top level echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" +# The top level OSInfo depends on the top-level Group. +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Nested Group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Deeply nested OSInfo + type: Microsoft/OSInfo + properties: {} + # The deeply nested echo references and depends on the adjacent + # deeply nested OSInfo. + - name: Deeply nested echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" + # The nested echo references and depends on the adjacent nested OSInfo. + - name: Nested echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" + # The nested OSInfo depends on the adjacent nested Group. + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Nested Group')]" + +``` + +#### Example 2 - Invalid reference and dependency on a nested instance + +This example configuration is invalid, because the top-level instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the nested `Microsoft/OSInfo` +instance. The nested instance is external to the top-level instance, not adjacent. + +```yaml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Top level echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} +``` + +#### Example 3 - Invalid reference and dependency on an external instance + +This example configuration is invalid, because the nested instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the top-level `Microsoft/OSInfo` +instance. The top-level instance is external to the nested instance, not adjacent. + +```yaml +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Nested echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + )] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" +``` + +## See also + +- [DSC resource kinds][09] +- [DSC resource operations][10] +- [DSC configuration documents][11] + + +[01]: ../../reference/schemas/resource/manifest/root.md#schema +[02]: ./kinds.md#adapter-resources +[03]: ./operations.md#validate-operation +[04]: ./kinds.md#adapter-resources +[05]: ./kinds.md#group-resources +[06]: ./kinds.md#importer-resources +[07]: ../../reference/schemas/config/resource.md#dependson +[08]: ../../reference/schemas/config/functions/reference.md +[09]: ./kinds.md +[10]: ./operations.md +[11]: ../configuration-documents/overview.md diff --git a/docs/concepts/resources/kinds.md b/docs/concepts/resources/kinds.md new file mode 100644 index 00000000..55c41265 --- /dev/null +++ b/docs/concepts/resources/kinds.md @@ -0,0 +1,61 @@ +--- +description: >- + Describes the different kinds of resources that DSC supports. +ms.date: 03/25/2025 +ms.topic: conceptual +title: DSC resource kinds +--- + +# DSC resource kinds + +DSC supports different behaviors and expectations for different kinds of resources. + +For command resources, DSC determines what kind a resource is by analyzing the resource manifest. +For more information about how DSC determines resource kinds, see +[DSC resource kind schema reference][01]. + +## Typical resources + +Typical resources manage the state of a configurable component. The properties of these resources +define the configurable settings of the component they represent. Each instance of a typical +resource represents a distinct item, like an installable software package, a service, or a file. + +You can always invoke the **Get** operation for typical resources to return the actual state of +a specific instance. If the resource has the `set` capability, you can use the **Set** operation +to enforce the desired state for a specific instance. + +## Adapter resources + +An adapter resource makes noncommand resources available to DSC. They always have a `resources` +property that takes an array of nested resource instances. Adapters can provide extra control over +how the adapted resources are processed. + +For example, the `Microsoft.DSC/PowerShell` adapter enables you to use PowerShell Desired State +Configuration (PSDSC) resources in DSC. PSDSC resources are published as components of PowerShell +modules. They don't define resource manifests. + +## Group resources + +Group resources always operate on nested DSC Resource instances. Group resources can change how the +nested instances are processed, like the `Microsoft.DSC/Assertion` group resource. + +Group resources can also be used to bundle sets of resources together for processing, like the +`Microsoft.DSC/Group` resource. You can use the [dependsOn][02] property for a resource instance in +a configuration to point to a group resource instead of enumerating each resource in the list. + +## Importer resources + +Importer resources resolve an external source to a set of nested DSC Resource instances. The +properties of an importer resource define how to find and resolve the external source. + +An importer resource must always define the [kind][03] and [resolve][04] properties in the resource +manifest. + +For example, the `Microsoft.DSC/Import` importer resource resolves instances from an external +configuration document, enabling you to compose configurations from multiple files. + + +[01]: ../../reference/schemas/definitions/resourceKind.md +[02]: ../../reference/schemas/config/resource.md#dependson +[03]: ../../reference/schemas/resource/manifest/root.md#kind +[04]: ../../reference/schemas/resource/manifest/resolve.md diff --git a/docs/concepts/resources/operations.md b/docs/concepts/resources/operations.md new file mode 100644 index 00000000..22d9c428 --- /dev/null +++ b/docs/concepts/resources/operations.md @@ -0,0 +1,126 @@ +--- +description: >- + Describes the operations available for DSC resources and how they're used. +ms.date: 03/25/2025 +ms.topic: conceptual +title: DSC resource operations +--- + +# DSC resource operations + +DSC defines a set of operations that resources can implement. DSC invokes the operations to use +resources for different tasks. Not every resource implements every operation. + +The general operations for managing system state are [Get](#get-operation), +[Test](#test-operation), and [Set](#set-operation). + +The rest of this document describes the available resource operations. + +## Get operation + +The **Get** operation returns the actual state of a specific resource instance on the system. + +This operation is only available for resources that have the [get capability][01]. + +DSC invokes the **Test** operation when you use the following commands: + +- `dsc resource get` to return the actual state for a resource instance. +- `dsc config get` to return the actual state for every instance in a configuration document. + +## Test operation + +The **Test** operation compares the actual state of a specific resource instance on the system to a +specified desired state. The result indicates not only whether the instance is in the desired state +but also _how_ the actual state differs from the desired state. + +If a resource doesn't have the [test capability][02], DSC synthetically tests the resource. + +DSC invokes the **Test** operation when you use the following commands: + +- `dsc resource test` to test the desired state of a specific resource instance. +- `dsc config test` to test the desired state of every instance in a configuration document. + +## Set operation + +The **Set** operation enforces the desired state of a resource instance on a system. The result +indicates how the resource modified the system. + +This operation is only available for resources with the [set capability][03]. + +DSC invokes the **Set** operation when you use the following commands: + +- `dsc resource set` to enforce the desired state of a specific resource instance. +- `dsc config get` to enforce the desired state defined by a configuration document. + +## Delete operation + +The **Delete** operation removes a resource instance from a system. The operation returns no output. + +This operation is only available for resources with the [delete capability][04]. + +DSC invokes the **Delete** operation when you use the following commands: + +- `dsc resource delete` to remove a specific resource instance. + +## Export operation + +The **Export** operation retrieves the actual state for every instance of the resource on a system. +The result is a configuration document that includes the exported instances. + +This operation is only available for resources with the [export capability][05]. + +DSC invokes the **Export** operation when you use the following commands: + +- `dsc resource export` to return a configuration document that enumerates the actual state for + every instance of a specific resource. +- `dsc config export` to return a configuration document that enumerates the actual state for every + instance in a configuration document. +- `dsc resource get` with the `--all` option to return the actual state for every instance of a + specific resource as an array of **Get** operation results. + +## List operation + +The **List** operation retrieves the available adapted resources for a specific DSC adapter +resource. + +This operation is only available for [adapter resources][06]. + +## Validate operation + +The **Validate** operation indicates whether an instance of the resource is validly defined. +Command resources use their resource instance schema for validation. Adapter resources implement +the **Validate** operation to enable DSC to validate adapted resources, which might not have a +defined JSON Schema. + +DSC invokes the **Validate** operation on adapter resources when validating adapted resource +instances in a configuration document or when you use the `dsc resource` commands to directly +invoke an adapted resource. + +## Resolve operation + +The **Resolve** operation processes an importer resource instance to return a configuration +document. + +This operation is only available for resources with the [resolve capability][07]. This operation +is primarily useful for [importer resources][08]. + +## See also + +- [DSC resource capabilities][09] +- [DSC resource kinds][10] +- [DSC resource properties][11] +- [DSC command reference][12] + + +[01]: ./capabilities.md#get +[02]: ./capabilities.md#test +[03]: ./capabilities.md#set +[04]: ./capabilities.md#delete +[05]: ./capabilities.md#export +[06]: ./kinds.md#adapter-resources +[07]: ./capabilities.md#resolve +[08]: ./kinds.md#importer-resources +[09]: ./capabilities.md +[10]: ./kinds.md +[11]: ./properties.md +[12]: ../../reference/cli/index.md diff --git a/docs/concepts/resources/overview.md b/docs/concepts/resources/overview.md new file mode 100644 index 00000000..64d70a2a --- /dev/null +++ b/docs/concepts/resources/overview.md @@ -0,0 +1,311 @@ +--- +description: >- + DSC Resources provide a standardized interface for idempotently managing the settings of a + system. They use a declarative syntax to define what the desired state should be. +ms.date: 03/25/2025 +title: DSC Resources +--- + +# DSC Resources + + + +In Microsoft's Desired State Configuration (DSC) platform, DSC Resources represent a standardized +interface for managing the settings of a system. Resources can model components as generic as a +file or as specific as an IIS server setting. Resources use a declarative syntax rather than +imperative. Instead of specifying _how_ to set a system to the desired state, with DSC you specify +_what_ the desired state is. Resources handle the "how" for you. + +Resources manage _instances_ of a configurable component. For example, the +`PSDscResources/Environment` resource manages environment variables. Each environment variable is a +different instance of the resource. Every resource defines a schema that describes how to validate +and manage an instance of the resource. + +DSC supports several kinds of resources: + +- A resource defined with a resource manifest is a _command_ resource. DSC uses the manifest + to determine how to invoke the resource and how to validate the resource instance properties. +- A _group resource_ is a command resource with a `resources` property that takes an array of + resource instances and processes them. Group resources can apply special handling to their nested + resource instances, like changing the user the resources run as. +- An _adapter resource_ is a group resource that enables the use of noncommand resources with DSC. + For example, the `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` adapter + resources enable the use of PowerShell DSC (PSDSC) resources in DSC, invoking the resources in + PowerShell and Windows PowerShell respectively. + +## Resource type names + +Every resource has a fully qualified type name, which identifies the resource. You use the type +name to specify a resource in configuration documents and as the value of the `--resource` flag +when using the `dsc resource *` commands. + +The fully qualified type name of a resource uses the following syntax: + +```Syntax +[.][.]/ +``` + +Every resource must define an `owner` and a `name`. The `group` and `area` components enable +organizing resources into related namespaces, like `Microsoft.SqlServer/Database` and +`Microsoft.SqlServer.Database/Role`. + +For more information about type names and how DSC validates them, see +[DSC Resource fully qualified type name schema reference][01]. + +## Resource properties + +The properties of a resource are the settings and options a user can declare for managing an +instance. Resources always have at least one property. Resources define their properties in their +instance schema. + +Properties are optional by default. Resources can be invoked directly or declared in a +configuration with only the properties that are relevant to the current task or purpose. You don't +need to declare every property for an instance. Properties can have default values for their +desired state. + +Most properties are one of the basic types: + +- String properties require the property value to be a set of characters, like `machine`. +- Integer properties require the property value to be a number without a fractional part, like `5`. +- Boolean properties require the property value to be either `true` or `false`. +- Array properties require the property value to be a list of items. Usually, array properties + specify that the values must be of a particular type, like a list of exit code integers or a list + of file paths. + +Complex properties require the property value to be an object with defined subproperties. The +subproperties can be basic or complex, but they're usually a basic type. + +Resources can define their properties as read-only or write-only: + +- A _read-only resource property_ defines metadata about an instance that the resource can retrieve + but that a user can't directly set. You can't specify read-only properties in the desired state + for an instance. Examples of read-only properties include the last time a file was modified or + the author of an installed software package. +- A _write-only resource property_ defines a value that the resource uses during a resource + operation but which can't be returned for the current state of an instance. Examples of + write-only properties include credentials used to authenticate during a resource operation and + the temporary directory to use when retrieving and unpacking a remote archive. + +DSC defines a set of _canonical resource properties_ which indicate that a resource participates in +shared semantics the DSC engine provides. For example, any resource that includes the `_exist` +canonical property in its instance schema indicates that the resource manages instances that can be +created and deleted. If a resource has the `_exist` canonical property and the `delete` capability, +DSC can handle invoking the **Delete** operation instead of **Set** when the desired state +indicates the instance shouldn't exist. For more information about the available canonical +properties, see [DSC canonical properties][02]. + +## Listing resources + +You can use DSC to list the available resources with the `dsc resource list` command. DSC searches +the `PATH` for command-based resources and invokes available resource providers to list their +resources. + +By default, the command returns every discovered DSC Resource. + +```sh +dsc resource list +``` + +```Output +Type Kind Version Capabilities RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +Microsoft.DSC.Debug/Echo Resource 1.0.0 gs--t--- +Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter file. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. +Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. +Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values +Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. +Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell. +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. +Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes. +``` + +You can filter the results by a resource's type name, description, and tags. For more information, +see [dsc resource list][03] + +## Invoking resources + +You can invoke resources directly with the `dsc resource *` commands to manage a single instance +through the three primary DSC operations: **Get**, **Test**, **Set**. If the resource has the +capability, you can also invoke the **Export** or **Delete** operations. + +### Get operations + +Every resource implements the **Get** operation, which retrieves the actual state of a resource +instance. Use the `dsc resource get` command to invoke the operation. + +For example, you can use the `Microsoft.Windows/Registry` resource to get the actual state for a +registry key value: + +```powershell +dsc resource get --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion", + "valueName": "SystemRoot" +}' +``` + +```yaml +actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS +``` + +### Test operations + +Some resources implement the **Test** operation. For resources that don't implement the **Test** +operation, DSC can validate an instance's state with a synthetic test. The synthetic test is a +strict case-insensitive comparison of the desired and actual values for the instance's properties. +Only resources that have advanced or complex validation requirements need to implement the **Test** +operation themselves. + +Use the `dsc resource test` command to invoke the operation. DSC returns data that includes: + +- The desired state for the instance. +- The actual state of the instance. +- Whether the instance is in the desired state. +- The list of properties that aren't in the desired state. + +For example, you can test whether a specific registry key exists: + +```powershell +dsc resource test --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\key\\that\\does\\not\\exist", + "exist": true +}' +``` + +```yaml +desiredState: + keyPath: HKCU\key\that\does\not\exist + _exist: true +actualState: + keyPath: HKCU\key\that\does\not\exist + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +### Set operations + + + +Most resources implement the **Set** operation, which enforces the desired state for an +instance. When used with DSC, the **Set** operation is _idempotent_, which means that the +resource only invokes the operation when an instance isn't in the desired state. Because the +operation is idempotent, invoking it repeatedly is the same as invoking it once. The idempotent +model prevents side effects from unnecessarily executing code. + + + +Resources that don't implement the **Set** operation are _assertion_ resources. You can use +assertion resources to retrieve and validate the state of an instance, but you can't use them to +enforce a desired state. + +Use the `dsc resource set` command to invoke the operation. DSC returns data that includes: + +- The state of the instance before the operation. +- The state of the instance after the operation. +- The list of properties the operation changed. + +For example, you can create a registry key by setting the desired state for a key that doesn't +exist. + +```powershell +dsc resource set --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\example\\key", + "valueName": "Example", + "valueData": { "String": "This is an example." } +}' +``` + +```yaml +beforeState: + keyPath: HKCU\example\key + _exist: false +afterState: + keyPath: HKCU\example\key + valueName: Example + valueData: + String: This is an example. +changedProperties: +- valueName +- valueData +- _exist +``` + +### Delete operations + +Some resources implement the **Delete** operation for convenience. This operation enables you to +invoke the resource to remove an instance from the system. + +Use the `dsc resource delete` command to invoke the operation. When you invoke the **Delete** +operation, DSC returns no output unless there's an error. + +For example, you can delete the registry created in the **Set** operation example: + +```powershell +dsc resource delete --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\example\\key" +}' +``` + +### Export operations + +Some resources implement the **Export** operation, which returns every instance of the resource on +the system. This operation can help you discover how a machine is currently configured. + +Use the `dsc resource export` command to invoke the operation. When you invoke the **Export** +operation, DSC returns an array of resources instance definitions you can copy into a configuration +document. + +## Declaring resource instances + +DSC configuration documents enable managing more than one resource or resource instance at a time. +Configuration documents declare a collection of resource instances and their desired state. +Configuration documents make it possible to model complex desired states by composing different +resources and instances together, like defining a security baseline for compliance or the settings +for a web farm. + +A resource instance declaration always includes: + +- `name` - A short, human-readable name for the instance that's unique in the document. This name + is used for logging and it helps to document an instance's purpose in the document. +- `type` - The fully qualified type name for the resource to identify the resource DSC should use + to manage the instance. +- `properties` - The desired state for the instance. DSC validates the values against the + resource's instance schema. + +This example configuration document snippet declares an instance of the +`Microsoft.Windows/Registry` resource. + +```yaml +$schema: https://schemas.microsoft.com/dsc/2023/08/configuration.schema.json +resources: + - name: example key value + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example\key + valueName: Example + valueData: + String: This is an example. +``` + +## See also + +- [Anatomy of a DSC command resource][04] to learn about authoring resources in your language + of choice. +- [DSC configuration documents][05] to learn about using resources in a configuration document. +- [Command line reference for the 'dsc resource' command][06] + +[01]: ../../reference/schemas/definitions/resourceType.md +[02]: ../../reference/schemas/resource/properties/overview.md +[03]: ../../reference/cli/resource/list.md +[04]: ./anatomy.md +[05]: ../configuration-documents/overview.md +[06]: ../../reference/cli/resource/index.md diff --git a/docs/concepts/resources/properties.md b/docs/concepts/resources/properties.md new file mode 100644 index 00000000..449f8f9d --- /dev/null +++ b/docs/concepts/resources/properties.md @@ -0,0 +1,142 @@ +--- +description: >- + Describes what DSC resource properties are, how they behave, and how to use + them. +ms.date: 03/25/2025 +ms.topic: conceptual +title: DSC resource properties +--- + +# DSC resource properties + +Every DSC resource defines how you can manage an instance of the resource as a set of properties. +Resources define each property as part of their instance JSON schema. + +When you define an instance of a resource to use for invoking an operation directly or in a +configuration document, DSC uses the instance schema to validate that data before invoking the +resource. + +If you specify an invalid property name or an invalid value for a property, DSC raises an error +describing how the data is invalid. + +Unless otherwise noted, for any given property: + +- You can define the property for the desired state of a resource instance. +- The resource can retrieve the actual state of the property from the system. +- The resource can enforce the desired state of the property on the system. +- You can omit the property from the desired state if you don't want to manage it. + +The preceding list describes a typical resource property. However, DSC recognizes different +attributes for a property that can change how you use the property: + +- If the instance schema defines the `x-dsc-key` keyword for the property subschema as `true`, the + property is a _key resource property_. Key properties uniquely identify a resource instance on + the system to prevent conflicts in configuration documents. + + For more information, see the [Key properties](#key-resource-properties) section. +- If the instance schema defines the property name in the `required` keyword, the property is a + _required resource property_. You _must_ define the property in the desired state for the + instance. If you omit the property, DSC raises an error because the instance is invalid. + + For more information, see the [Required properties](#required-resource-properties) section. +- If the instance schema defines the `readOnly` keyword for the property subschema as `true`, the + property is a _read-only resource property_. You can't define the property in the desired state + for an instance. The resource can't set a read-only property. It can only return the actual state + for that property on an instance. + + For more information, see the [Read-only properties](#read-only-resource-properties) section. +- If the instance schema defines the `writeOnly` keyword for the property subschema as `true`, + property is a _write-only resource property_. The resource never returns a value for that + property. You can use the property to control how the resource behaves, rather than directly map + the value for the property to the instance state. + + For more information, see the [Write-only properties](#write-only-resource-properties) section. + +Additionally, DSC defines a set of canonical properties that enable resources to participate in the +semantics of the DSC engine. Canonical resource properties are reusable subschemas that indicate +the resource adheres to certain contracts that you can rely on when using the resource. + +## Key resource properties + +DSC uses key resource properties to uniquely identify instances of the resource on a system. If you +specify two or more instances of the resource with the same key properties, you're attempting to +manage the same instance more than once. + +Instances in a configuration document with the same values for their key properties are +_conflicting instances_. Never define conflicting instances in a configuration document. In a +future release, DSC will raise an error for a configuration document containing any conflicting +instances. + +If you define different settings for conflicting instances, DSC invokes the resource for each +conflicting instance during every **Set** operation. In this case, later instances override any +settings defined by an earlier conflicting instance in the configuration document. + +If the settings for conflicting instances are the same, the resource is still invoked for each +instance, which expends time and resources without benefit. + +DSC determines whether a resource property is a key property by examining the property subschema +in the instance schema. If the subschema defines the `x-dsc-key` keyword with the value `true`, +the property is a key property. + +## Required resource properties + +When you're defining a resource instance, some properties might be required. An instance that +doesn't define every required property is invalid. DSC validates instance definitions before +invoking resource operations. When an instance is missing any required properties, DSC raises a +validation error and doesn't invoke the resource. + +Properties can be _always_ required. DSC determines whether a resource property is a required +property by examining the `required` keyword in the instance schema. If the instance schema defines +the `required` keyword and the property name is included in the array of values for the keyword, +the property is always required. + +Properties can be _conditionally_ required. Resources can conditionally require a property with the +`dependentRequires` keyword or other conditional keywords. For more information about conditionally +applied subschemas, see +[Conditional schema validation][01]. + +## Read-only resource properties + +Resources can define read-only properties to describe information about an instance that the +resource can retrieve but not directly set. For example, file APIs don't generally allow a user to +set the property describing the last time the file was modified. + +Generally, you shouldn't include read-only properties when defining the desired state for an +instance. Assertion resources that don't support the **Set** operation can include read-only +properties you can use for validating system state for conditional behavior. + +DSC determines whether a resource property is a read-only property by examining the property +subschema in the instance schema. If the subschema defines the `readOnly` keyword with the value +`true`, the property is read-only. + +## Write-only resource properties + +Resources can define write-only properties that affect how the resource behaves but that the +resource can't retrieve for the actual state of an instance. For example, a resource might support +credentials for downloading a file, but won't return those credentials in the output. + +DSC determines whether a resource property is a write-only property by examining the property +subschema in the instance schema. If the subschema defines the `writeOnly` keyword with the value +`true`, the property is write-only. + +## Canonical resource properties + +DSC defines a set of subschemas representing reusable properties with defined behaviors and +expectations. These reusable properties are called canonical resource properties. + +Any resource that defines a canonical resource property in the instance schema must adhere to the +requirements and behaviors defined for the canonical property. + +For more information about the available canonical properties, see +[DSC canonical resource properties][02]. + +## Related + +- [DSC Resource Manifest schema reference][03] +- [JSON Schema reference][04] + + +[01]: https://json-schema.org/understanding-json-schema/reference/conditionals +[02]: ../../reference/schemas/resource/properties/overview.md +[03]: ../../reference/schemas/resource/manifest/root.md +[04]: https://json-schema.org/understanding-json-schema/reference diff --git a/docs/get-started/index.md b/docs/get-started/index.md new file mode 100644 index 00000000..c8f963c3 --- /dev/null +++ b/docs/get-started/index.md @@ -0,0 +1,539 @@ +--- +description: >- + Learn how to use Microsoft's Desired State Configuration platform to manage the state of a + machine as code. +ms.date: 03/25/2025 +title: Get started with DSC +--- + +# Get started with DSC + +Microsoft's Desired State Configuration (DSC) is a declarative configuration platform. You can use +DSC resources to query, audit, and set the state of a specific component on a system. You can use +DSC configuration documents to describe how a system should be configured using one or more +resources. This document describes how you can discover the resources available on a machine, +invoke those resources directly, and manage a configuration. + +## Prerequisites + +- [Install DSC][01] version `3.0.0` on a Windows machine. +- A terminal emulator, like [Windows Terminal][02]. + +## Discover resources + +You can use the `dsc resource list` command to enumerate the available DSC resources on a machine. +DSC discovers resources by searching the folders in your `PATH` environment variable for files that +have any of the following suffixes: + +- `.dsc.resource.json` +- `.dsc.resource.yaml` +- `.dsc.resource.yml` + +Files with the `.dsc.resource.` suffix are DSC resource manifests. They describe both +the settings they enable you to manage and how DSC can invoke them as a command. + +Open a terminal and run the following command: + +```powershell +dsc resource list +``` + +DSC outputs a table showing the available resources and summary information about each resource. + +```Output +Type Kind Version Capabilities RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +Microsoft.DSC.Debug/Echo Resource 1.0.0 gs--t--- +Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter file. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. +Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. +Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values +Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. +Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell. +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. +Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes. +``` + +Together, the columns describe each resource: + +- The **Type** column defines the fully qualified type name for a resource. This name identifies the + resource on a system and in a configuration document. +- The **Kind** column indicates how you can use the resource. + - `Adapter` indicates that the resource is an adapter resource and enables you to configure + components that don't define a DSC resource manifest, like PowerShell DSC (PSDSC) resources. + - `Group` indicates that the resource is a group resource and changes how DSC processes a list of + resource instances. Group resources don't directly manage state on a system. + - `Importer` indicates that the resource is an importer resource that retrieves a configuration + document from an external source to insert into the current configuration document. + - `Resource` indicates that the resource is typical - not an adapter, group, or importer resource. +- The **Version** column indicates the latest discovered version of the resource on the system. +- The **Capabilities** column indicates how the resource is implemented and what you can expect + when using it. The table displays the capabilities as flags in the following order, using a `-` + instead of the appropriate letter if the resource doesn't have a specific capability: + + - `g` indicates that the resource has the `get` capability. + - `s` indicates that the resource has the `set` capability. + - `x` indicates that the resource has the `setHandlesExist` capability. + - `w` indicates that the resource has the `whatIf` capability. + - `t` indicates that the resource has the `test` capability. + - `d` indicates that the resource has the `delete` capability. + - `e` indicates that the resource has the `export` capability. + - `r` indicates that the resource has the `resolve` capability. + +- The **RequireAdapter** column indicates which adapter resource, if any, the resource requires. +- The **Description** column defines a synopsis for the resource. + +By default, the `dsc resource list` command only returns command resources, which always have a +resource manifest. You can use the `--adapter` option to return the resources for one or more +adapted resources. + +Run the following command to return the available adapted resources instead of command resources: + +```powershell +$adaptedResources = dsc resource list --adapter * | ConvertFrom-Json + +$adaptedResources | + Group-Object -NoElement -Property requireAdapter | + Format-Table -AutoSize +``` + +```Output +Count Name +----- ---- + 27 Microsoft.Windows/WindowsPowerShell + 961 Microsoft.Windows/WMI +``` + +The output of `dsc resource list` is saved to the `$resources` variable as an array of PowerShell +objects. When you first ran the `dsc resource list` command, the output in the terminal was a table +view. By default, when DSC detects output redirection, it formats the output as JSON. Converting the +JSON into a PowerShell object with the `ConvertFrom-Json` cmdlet enables you to treat the output +like any other PowerShell object. + +The `Group-Object` cmdlet summarizes the available adapted resources, grouped by the adapter that +they require. The specific count for adapted resources depends on the machine you're using and the +installed PowerShell modules that export any PSDSC resources. + +Run the following command to display only the resources available with the +`Microsoft.Windows/WindowsPowerShell` adapter. + +```powershell +$adaptedResources | + Where-Object -requireAdapter -EQ Microsoft.Windows/WindowsPowerShell | + Format-Table -Property type, kind, version, capabilities, description +``` + +```Output +type kind version capabilities description +---- ---- ------- ------------ ----------- +PSDesiredStateConfiguration/Archive resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Environment resource 1.1 {get, set, test} +PSDesiredStateConfiguration/File resource 1.0.0 {get, set, test} +PSDesiredStateConfiguration/Group resource 1.1 {get, set, test} +PSDesiredStateConfiguration/GroupSet resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Log resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Package resource 1.1 {get, set, test} +PSDesiredStateConfiguration/ProcessSet resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Registry resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Script resource 1.1 {get, set, test} +PSDesiredStateConfiguration/Service resource 1.1 {get, set, test} +PSDesiredStateConfiguration/ServiceSet resource 1.1 {get, set, test} +PSDesiredStateConfiguration/SignatureValidation resource 1.0.0 {get, set, test} +PSDesiredStateConfiguration/User resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WaitForAll resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WaitForAny resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WaitForSome resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsFeature resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsFeatureSet resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsOptionalFeature resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsOptionalFeatureSet resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsPackageCab resource 1.1 {get, set, test} +PSDesiredStateConfiguration/WindowsProcess resource 1.1 {get, set, test} +PackageManagement/PackageManagement resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa… +PackageManagement/PackageManagementSource resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa… +PowerShellGet/PSModule resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing … +PowerShellGet/PSRepository resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing … +``` + +For more information about the command, see [dsc resource list][03]. + +## Invoke a resource + +You can use DSC to directly invoke a resource. When you invoke a resource, you're performing a +specific operation on an _instance_ of the resource. A resource instance is a specific item the +resource represents. The following examples use the `Microsoft.Windows/Registry` resource to invoke +DSC operations. + +First, use the `dsc resource list` command to see what capabilities the `Registry` resource has. + +```powershell +$resource = dsc resource list Microsoft.Windows/Registry | ConvertFrom-Json +$resource.capabilities +``` + +```Output +get +set +whatIf +delete +``` + +Together, these capabilities tell us that you can use the `Registry` command resource to: + +- The `get` capability indicates that you can invoke the **Get** operation to retrieve the current + state of an instance. +- The `set` capability indicates that you can invoke the **Set** operation to modify the state of + an instance. +- The `whatIf` capability indicates that you can invoke the **Set** operation in what-if mode to + see how the resource would change the instance without actually modifying the system. +- The `delete` capability indicates that you can invoke the **Delete** operation to remove an + instance from the system. + +### Get the current state of a resource + +You can use the `dsc resource get` command to retrieve the current state of an instance. Run the +following command to define the data that represents a registry value: + +```powershell +$instance = @{ + keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion' + valueName = 'SystemRoot' +} | ConvertTo-Json +``` + +For this example: + +- The `keyPath` property to indicate the path to the registry key that should contain the value you + want to manage. `keyPath` is a _required_ property for the `Registry` resource - you always need + to specify it. +- The `valueName` property identifies which registry value to manage for the registry key. +- The `_exist` canonical property indicates whether the registry value should exist. In this + example, the value is `true`, which indicates that the instance should exist. + +Run the following command to get the current state of the registry key: + +```powershell +dsc resource get --resource $resource.type --input $instance +``` + +```yaml +actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS +``` + +The output shows that the value is set to the string `C:\WINDOWS`. + +### Test whether a resource is in the desired state + +Retrieving the current state of a resource is useful, but in practice you more often want to know +whether an instance is in the desired state. The `dsc resource test` command not only tells you +whether an instance is out of state, but how it's out state. + +> {!NOTE} +> Remember that the `Registry` resource doesn't have the `test` capability. Fortunately, that +> doesn't mean that you can't use the **Test** operation for a resource. When a resource doesn't +> have the `test` capability, it is indicating that the resource depends on DSC's synthetic test +> capabilities. DSC itself calls the **Get** operation for the resource and compares it to the +> desired state. + +Run the following commands to define the desired state of a registry key that doesn't exist and test +it. + +```powershell +$desired = @{ + keyPath = 'HKCU\dsc\example\key' + _exist = $true +} | ConvertTo-Json +dsc resource test --resource $resource.type --input $desired +``` + +```yaml +desiredState: + keyPath: HKCU\dsc\example\key + _exist: true +actualState: + keyPath: HKCU\dsc\example\key + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +The output for the command shows you the desired state, actual state, and how they differ. In this +case, the registry key doesn't exist - the `_exist` property is `false` when the desired state is +`true`. + +### Set the desired state of a resource + +You can also directly invoke a resource to set the state for an instance if the resource has the +`set` capability. + +Run the following command to create the registry key: + +```powershell + +dsc resource set --resource $resource.type --input $desired +``` + +```yaml +beforeState: + keyPath: HKCU\dsc\example\key + _exist: false +afterState: + keyPath: HKCU\dsc\example\key +changedProperties: +- _exist +``` + +The output indicates that the resource created the missing instance. + +## Manage a configuration + +Invoking resources directly is useful, but tedious for defining the desired state of a system. You +can define a DSC configuration document to describe a set of resource instances together. + +Copy the following code block and save it in a file named `example.dsc.config.yaml`. + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Example registry key + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\dsc\example\key + _exist: true +- name: PSDSC resources + type: Microsoft.Windows/WindowsPowerShell + properties: + resources: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + Name: DSC_EXAMPLE + Ensure: Present + Value: Set by DSC +``` + +The configuration document specifies two resource instances at the top level: + +- The `Microsoft.Windows/Registry` resource to ensure that a registry key exists. +- The `Microsoft.Windows/WindowsPowerShell` adapter resource to define PowerShell DSC (PSDSC) + resources. + +The `WindowsPowerShell` adapter instance defines a single property, `resources`, as an array of +resource instances. In this configuration, it defines two instances: + +- The first instance uses the `PSRepository` PSDSC resource from the **PowerShellGet** module to + make sure the PowerShell Gallery is available for use as a repository. +- The second instance uses the `PSModule` PSDSC resource from the same module to make sure that the + **Microsoft.WinGet.Client** module is installed. + +Open a terminal with elevated permissions. PSDSC resources in Windows PowerShell need to run as +administrator. In the elevated terminal, change directory to the folder where you saved the +configuration document as `example.dsc.config.yaml`. Then run the following command. + +```powershell +dsc config test --file ./example.dsc.config.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: test + executionType: actual + startDatetime: 2025-03-03T17:11:25.726475600-06:00 + endDatetime: 2025-03-03T17:11:32.567311800-06:00 + duration: PT6.8408362S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT0.1818183S + name: Example registry key + type: Microsoft.Windows/Registry + result: + desiredState: + keyPath: HKCU\dsc\example\key + _exist: true + actualState: + keyPath: HKCU\dsc\example\key + inDesiredState: true + differingProperties: [] +- metadata: + Microsoft.DSC: + duration: PT3.0461988S + name: PSDSC resources + type: Microsoft.Windows/WindowsPowerShell + result: + desiredState: + resources: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + Name: DSC_EXAMPLE + Ensure: Present + Value: Set by DSC + metadata: + Microsoft.DSC: + context: configuration + actualState: + result: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + InDesiredState: false + inDesiredState: false + differingProperties: + - resources + - metadata +messages: [] +hadErrors: false +``` + +The output shows that: + +- The `Registry` instance is in the desired state. Earlier in this article, you created the key by + invoking the **Set** operation directly. + +- The adapted `Environment` PSDSC resource reports that the `DSC_EXAMPLE` environment variable is + _not_ in the desired state. + +Run the following command to enforce the desired state on the system. + +```powershell +dsc config set --file ./example.dsc.config.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-03T17:14:15.841393700-06:00 + endDatetime: 2025-03-03T17:14:29.136469500-06:00 + duration: PT13.2950758S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT0.2633556S + name: Example registry key + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\dsc\example\key + _exist: true + afterState: + keyPath: HKCU\dsc\example\key + changedProperties: null +- metadata: + Microsoft.DSC: + duration: PT8.6601181S + name: PSDSC resources + type: Microsoft.Windows/WindowsPowerShell + result: + beforeState: + result: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + ResourceId: null + PsDscRunAsCredential: null + PSComputerName: localhost + ModuleVersion: '1.1' + Value: null + Path: null + ConfigurationName: null + Name: DSC_EXAMPLE + ModuleName: PSDesiredStateConfiguration + SourceInfo: null + DependsOn: null + Ensure: Absent + afterState: + result: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + RebootRequired: false + changedProperties: + - result +messages: [] +hadErrors: false +``` + +To review the actual state of the system, run the `dsc config get` command: + +```powershell +dsc config get --file ./example.dsc.config.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-03T17:16:39.507848200-06:00 + endDatetime: 2025-03-03T17:16:47.734256600-06:00 + duration: PT8.2264084S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT0.1739569S + name: Example registry key + type: Microsoft.Windows/Registry + result: + actualState: + keyPath: HKCU\dsc\example\key +- metadata: + Microsoft.DSC: + duration: PT3.9958946S + name: PSDSC resources + type: Microsoft.Windows/WindowsPowerShell + result: + actualState: + result: + - name: DSC_EXAMPLE env variable + type: PSDesiredStateConfiguration/Environment + properties: + ResourceId: null + PsDscRunAsCredential: null + PSComputerName: localhost + ModuleVersion: '1.1' + Value: Set by DSC + Path: null + ConfigurationName: null + Name: DSC_EXAMPLE + ModuleName: PSDesiredStateConfiguration + SourceInfo: null + DependsOn: null + Ensure: Present +messages: [] +hadErrors: false +``` + +## Related content + +- [Glossary: Desired State Configuration][04] +- [DSC configuration documents][05] +- [DSC Resources][06] +- [DSC command reference][07] + + + +[01]: ../overview.md#installation +[02]: /windows/terminal/ +[03]: ../reference/cli/resource/list.md +[04]: ../glossary.md +[05]: ../concepts/configuration-documents/overview.md +[06]: ../concepts/resources/overview.md +[07]: ../reference/cli/index.md diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..3607b254 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,475 @@ +--- +title: "Glossary: Desired State Configuration" +description: >- + A glossary of terms for Microsoft Desired State Configuration (DSC) +ms.topic: glossary +ms.date: 03/25/2025 +--- + +# Glossary: Desired State Configuration + +Microsoft Desired State Configuration (DSC) uses several terms that might have different +definitions elsewhere. This document lists the terms, their meanings, and shows how they're +formatted in the documentation. + + + +## Configuration terms + +### DSC Configuration document + +The JSON or YAML data that defines a list of resource instances and their desired state. + +#### Guidelines + +- **First mention:** DSC Configuration Document +- **Subsequent mentions:** configuration document or document + +#### Examples + +> A DSC Configuration Document can be formatted as JSON or YAML. + +> Define the `scope` variable in the document as `machine`. + +## Resource terms + +### DSC Resource + +The DSC interface for managing the settings of a component. DSC supports several kinds of +resources. + +#### Guidelines + +- **First mention:** DSC Resource +- **Subsequent mentions:** resource +- Format the names of specific resources as code. + +#### Examples + +> They both use the `Microsoft/OSInfo` DSC Resource. + +> You can inspect a resource's definition with the `dsc resource list ` command. + +### DSC resource instance + +A single item configured by a DSC resource. A resource can manage any number of instances. Each +instance uniquely represents an item, like a specific file or a software package. + +A DSC configuration document defines the desired state for one or more instances. + +#### Guidelines + +- **First mention:** DSC resource instance +- **Subsequent mentions:** resource instance or instance + +#### Examples + +> Next, define the first DSC resource instance for your configuration document. Each resource +> instance configures a unique component on the machine. + +### DSC command resource + +A resource defined with a resource manifest is a _command_ resource. DSC uses the manifest to +determine how to invoke the resource and how to validate the resource instance properties. + +#### Guidelines + +- Use this term when distinguishing between command resources and adapted resources. + +#### Examples + +> `Microsoft.Windows/Registry` is a command resource. DSC uses the resource's resource manifest +> to determine how to invoke the `registry` executable for a DSC operation. Adapted resources, +> like those implemented in PowerShell, don't define a resource manifest. Instead, the adapter +> is responsible for discovering adapted resources, advertising their properties to DSC, and +> invoking the adapted resources for DSC. + +### DSC group resource + +A _group resource_ is a resource with a `resources` property that takes an array of resource +instances and processes them. Group resources can apply special handling to their nested resource +instances, like changing the user the resources run as. + +#### Guidelines + +- Always specify the term as group resource. Don't omit "group" from the term. + +#### Examples + +> To invoke resources in parallel, use the `Microsoft.DSC/ParallelGroup` group resource. + +### Nested resource instance + +A resource instance defined in the `resources` property of a group or adapter +resource instance. + +#### Guidelines + +- **First mention:** nested resource instance +- **Subsequent mentions:** nested instance +- If it's clear from context that the instance is a nested instance, you can omit the "nested" + prefix. + +#### Examples + +> Add a nested resource instance to the `DSC/ParallelGroup` instance. Define the `type` of the +> nested instance as `Microsoft.Windows/Registry`. + +### DSC adapter resource + +An _adapter resource_ is a group resource that enables the use of noncommand resources with +DSC. Every nested resource instance must be a resource type the adapter supports. + +#### Guidelines + +- **First mention:** DSC adapter resource +- **Subsequent mentions:** adapter + +#### Examples + +> To use PowerShell DSC (PSDSC) Resources in your configuration document, add an instance of the +> `Microsoft.Dsc/PowerShell` adapter resource and define the PowerShell resource instances as +> nested instances. + +### DSC PowerShell resources + +A resource implemented in PowerShell is a PowerShell resource. + +Any PowerShell resource that is compatible with PowerShell DSC is a PowerShell DSC resource (PSDSC +resource). The implementation of a PSDSC resource further distinguishes those resources: + +- Class-Based - A PSDSC resource defined as a PowerShell class in a PowerShell module is a + _class-based_ PSDSC resource. + + The class's members define a class-based resource's schema. A class-based PSDSC resource must: + + 1. Have the `[DscResource()]` attribute. + 1. Define at least one property with the `[DscProperty()]` attribute. + 1. Define the `Get()`, `Set()`, and `Test()` methods. + +- MOF-based - A PSDSC resource defined with a MOF file (`.mof`), a script module file (`.psm1`), + and optional module manifest file (`.psd1`) is a _MOF-based_ PSDSC resource. MOF-based resources + are only supported through Windows PowerShell and the `Microsoft.Windows/WindowsPowerShell` + adapter. + + The MOF file is the schema for the resource and defines the resource's properties. The script + module file defines the resource's functions: `Get-TargetResource`, `Set-TargetResource`, and + `Test-TargetResource`. These functions map to the **Get**, **Set**, and **Test** operations. + +#### Guidelines + + + +- **First mention:** PowerShell DSC resources +- **Subsequent mentions:** PSDSC resources. +- When discussing a specific type of PowerShell resource, always specify the type prefix, like + _class-based PSDSC resources_. +- The PSDSC prefix can be omitted when the context is clearly or only about PowerShell DSC + resources, like a tutorial for authoring a class-based resource. + + + +#### Examples + +> To use PowerShell DSC Resources in your configuration document, add an instance of the +> `Microsoft.DSC/PowerShell` adapter resource and define the PSDSC resource instances as nested +> instances. + +> When developing PowerShell resources for cross-platform software, create class-based resources. +> MOF-based resources are only supported through Windows PowerShell. + +### DSC Resource manifest + +The data file that defines the metadata and implementation of a command-based resource. A resource +manifest can be authored in either JSON or YAML. + +#### Guidelines + +- **First mention:** DSC resource manifest +- **Subsequent mentions:** manifest + +#### Examples + +> Every command resource must define a DSC resource manifest. The manifest's filename must end with +> `.dsc.resource.json`. + +### DSC Resource type name + +The identifying name of a resource. The fully qualified resource type name uses the following +syntax: + +```text +`[.][.]/` +``` + +#### Guidelines + +- **First mention:** When discussing type names conceptually, use the phrase _DSC resource type + name_. When referencing a specific resource by name, always use the fully qualified resource type + name formatted as code. +- **Subsequent mentions:** When discussing type names conceptually, use the phrase _resource type_ + or _type name_. When referencing a specific resource by name, you can specify it as `` for + brevity. +- When discussing the syntax of a resource type name, always specify the term as + _fully qualified resource type name_. + +#### Examples + +> DSC Resources are uniquely identified by their fully qualified resource type name. + +> The `Microsoft.DSC/PowerShell` adapter resource enables you to use PowerShell DSC (PSDSC) +> resources with DSC. The `PowerShell` adapter handles discovering and invoking PSDSC resources. + +### Operations + +The actions a resource can take for the component it manages. + +- **Get** - Retrieves the current state of an instance of the resource. +- **Set** - Enforces the desired state of an instance of the resource. +- **Test** - Compares the desired state of an instance of the resource against its current state. +- **Export** - Retrieves the current state of every instance of the resource. +- **Delete** - Removes a specific instance of the resource. + +#### Guidelines + +- Capitalize the operations. +- When referring to the operation specifically, format it as **bold**. +- When referring to the operation's method as implemented in a PowerShell class, format the method + as `code` with an empty set of parentheses (`()`) after the name. +- When referring to the operation as the DSC command, format the method as `code` for the + appropriate command. + +#### Examples + +> The implementation of the `Set()` method in a class-based PowerShell resource can't use any +> `return` statements. + +> DSC is constructed around the primary operations **Get**, **Test**, and **Set**. When you use the +> `get` subcommand for `dsc resource`, it returns the current state of the resource instance. + +### Resource properties + +A setting that a resource can manage for a component. Resources always have at least one property. +Resources describe their properties with their [instance schema](#resource-instance-schema) in the +`properties` keyword. + +Some properties are [canonical](#canonical-resource-properties), [key](#key-resource-properties), +[read-only](#read-only-resource-properties), or [write-only](#write-only-resource-properties) +properties. + +#### Guidelines + +- Format property names as bold. +- Format property values as code. +- Use the correct casing for the property based on the resource instance schema. + +#### Examples + +> The value of the **format** property in this example is `JSON`. + +### Key resource properties + +The key properties of a resource uniquely identify an instance of the resource. No two instances of +a resource in a configuration can have identical key properties. + +If two instances have the same key properties but different values for the other properties, the +configuration will never be in the desired state and DSC will reconfigure the instance during every +**Set** operation. In a future release, specifying two or more instances of a resource with the +same key properties will raise a validation error. + +#### Guidelines + +- **First mention:** When discussing a specific property, specify the suffix _key property_ after + the formatted property name. When discussing key resource properties conceptually, specify the + phrase as _key resource properties_. +- **Subsequent mentions:** When discussing a specific property, you can omit the word _key_. When + discussing key properties conceptually, you can omit the word _resource_ and use the phrase _key + properties_ instead. If it's clear from context, you can omit the word _key_. +- Follow the same formatting for general resource properties. + +#### Examples + +> The `Microsoft.Windows/Registry` resource has two key properties: +> +> - `keyPath` uniquely identifies the registry key to manage. This key property is required. +> - `valueName` uniquely identifies the registry value to manage. This key property is optional +> unless you specify a value for the `valueData` property. + +> Specify the `settingsScope` key property defines whether the settings file should be updated for +> the machine or current user. + +### Canonical resource properties + +DSC defines a set of common purpose properties for use in resource instance schemas. These +properties indicate that the resource is participating in specific semantics that enables DSC to +handle certain behaviors on behalf of the resource. For more information about canonical +properties, see [DSC canonical properties][01] + +#### Guidelines + +- **First mention:** When discussing a specific property, specify the suffix _canonical property_ + after the formatted property name. When discussing canonical resource properties conceptually, + specify the phrase as _canonical resource properties_. +- **Subsequent mentions:** When discussing a specific property, you can omit the word _canonical_. + When discussing canonical properties conceptually, you can omit the word _resource_ and use the + phrase _canonical properties_ instead. If it's clear from context, you can omit the word + _canonical_. +- Follow the same formatting for general resource properties. Canonical property names always have + an underscore (`_`) prefix. + +#### Examples + +> The `_exist` canonical property defines whether an instance should exist. + +> When defining your resource, consider whether you can use any of the semantics DSC defines for +> canonical resource properties. If your resource manages instances that can be created, updated, +> and deleted, consider using the `_exist_ canonical property. Implementing your resource to adhere +> to canonical properties makes it easier for your users to understand how your resource behaves +> and reduces the code you need to write by letting DSC handle some behaviors for your resource. + +### Read-only resource properties + +Read-only resource properties of a resource describe nonconfigurable information about an instance +that the resource returns. Examples include metadata, such as the last time a file was modified, or +the latest available version of a package. + +Resources indicate which properties are read-only in their instance schema by defining the +`readOnly` keyword as `true`. + +#### Guidelines + +- **First mention"** When discussing a specific property, specify the suffix "read-only property" + after the formatted property name. When discussing read-only resource properties conceptually, + specify the phrase as "read-only resource properties. +- **Subsequent mentions:** When discussing a specific property, you can omit the phrase + "read-only." When discussing read-only properties conceptually, you can omit the word "resource" + and use the phrase "read-only properties" instead. +- Follow the same formatting for general resource properties. + +#### Examples + +> The `lastWriteTime` read-only resource property indicates when the file was last updated. The +> `creationTime` read-only property indicates when the file was created. + +> When defining a resource, consider whether your resource should return any non-configurable +> metadata for users as read-only resource properties. Defining read-only properties can enable +> your users to more effectively and quickly investigate and audit their systems by providing +> information they need about an instance but can't directly configure. + +### Write-only resource properties + +Write-only properties of a resource instance describe options that influence how the resource +behaves, but can't be returned from the machine. Examples of write-only properties include +credentials required for configuring the resource and the +[_purge][02] canonical property. + +Resources indicate which properties are write-only in their instance schema by defining the +`writeOnly` keyword as `true`. + +#### Guidelines + +- **First mention"** When discussing a specific property, specify the suffix "write-only property" + after the formatted property name. When discussing write-only resource properties conceptually, + specify the phrase as "write-only resource properties. +- **Subsequent mentions:** When discussing a specific property, you can omit the phrase + "write-only." When discussing write-only properties conceptually, you can omit the word "resource" + and use the phrase "write-only properties" instead. +- Follow the same formatting for general resource properties. + +#### Examples + +> The `token` write-only resource property defines the access token the resource must use to access +> the remote datastore. The `connectionTimeout` write-only property defines how many seconds the +> resource should allow for retrieving the data. The `connectionTimeout` property defaults to sixty +> seconds. + +> When defining a resource, consider whether your resource needs any options that change how the +> resource behaves but can't be retrieved from the system as write-only resource properties. If +> your resource requires or can use credentials, credential properties should always be write-only +> properties. + +### Resource instance schema + +The JSON schema that describes and validates the properties of a resource instance. All command +resources define a resource instance schema. Adapter resources provide the instance schema for +their adapted resources. + +#### Guidelines + +- **First mention:** resource instance schema +- **Subsequent mentions:** resource schema or schema. +- Specify the full term when discussing multiple kinds of schema. + +## General terms + +### Desired State Configuration + +Microsoft's Desired State Configuration (DSC) is a declarative configuration platform. With DSC, +you describe the state of a machine in a format that anyone can read and understand, not just +subject matter experts. + +#### Guidelines + +- **First mention:** Microsoft's Desired State Configuration (DSC) platform +- **Subsequent mentions:** DSC or DSC platform +- Specify the platform suffix when referencing the platform specifically in contexts where the + term could be confused with PowerShell DSC or the `dsc` command. + +#### Examples + +> In Microsoft's Desired State Configuration (DSC) platform, DSC resources represent a standardized +> interface for managing the settings of a system. + +> You can use DSC to list the available resources with the `dsc resource list` command. + +> For resources that don't implement the **Test** operation, DSC can validate an instance's state +> with a synthetic test. + +### `dsc` + +The DSC command line tool that invokes resources and manages configuration documents. + +#### Guidelines + +- Specify the term as DSC when discussing the command line tool in general. +- Use code formatting when discussing running the command, a specific subcommand, or to distinguish + the command line tool from the conceptual platform. + +#### Examples + +> Use the `dsc resource test` command to invoke the operation. DSC returns data that includes: +> +> - The desired state for the instance. +> - The actual state of the instance. +> - Whether the instance is in the desired state. +> - The list of properties that aren't in the desired state. + +### PowerShell Desired State Configuration (PSDSC) + +The Desired State Configuration feature of PowerShell. Previously, this term included the +PowerShell DSC platform, the Local Configuration Manager, and the **PSDesiredStateConfiguration** +PowerShell module. + +For DSC, this term applies to defining and using resources that are implemented in PowerShell and +compatible with PSDSC. DSC users manage PSDSC resource instances with the +`Microsoft.DSC/PowerShell` or `Microsoft.Windows/WindowsPowerSHell` adapter resources. + +#### Guidelines + +- **First mention:** PowerShell Desired State Configuration (PSDSC) +- **Subsequent mentions:** PowerShell DSC or PSDSC +- Always distinguish PowerShell DSC from the DSC platform and the `dsc` command. +- Always specify the **PSDesiredStateConfiguration** module by name and strongly emphasized when + discussing the PowerShell module itself. + +#### Examples + +> You can use PowerShell DSC (PSDSC) resources with DSC as adapted resources. + +> Get started authoring a class-based PowerShell DSC resource to manage a configuration file. +> Completing this tutorial gives you a functional class-based PSDSC Resource in a module you can +> use for further learning and customization. + + +[01]: ./reference/schemas/resource/properties/overview.md +[02]: ./reference/schemas/resource/properties/ensure.md diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..5f43cbec --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,147 @@ +--- +description: >- + Learn about Microsoft's Desired State Configuration platform, including what it does and when + it should be used. +ms.date: 03/25/2025 +ms.topic: overview +title: Microsoft Desired State Configuration overview +--- + +# Microsoft Desired State Configuration overview + +Microsoft's Desired State Configuration (DSC) is a declarative configuration platform. With DSC, +the state of a machine is described using a format that should be clear to understand even if the +reader isn't a subject matter expert. Unlike imperative tools, with DSC the definition of an +application environment is separate from programming logic that enforces that definition. + +The DSC command line application (`dsc`) abstracts the management of software components +declaratively and idempotently. DSC runs on Linux, macOS, and Windows without any external +dependencies. + +With DSC, you can: + +- Author DSC Resources to manage your systems in any language. +- Invoke individual resources directly. +- Create configuration documents that define the desired state of a system. + +## Configuration Documents + +DSC Configuration Documents are declarative data files that define instances of resources. +Typically, configuration documents define what state to enforce. DSC supports writing configuration +documents in both JSON and YAML. + +Example scenarios include requirements for an application environment or operational/security +standards. + +## DSC Resources + +DSC Resources define how to manage state for a particular system or application component. +Resources describe a schema for the manageable settings of the component. Every resource can be +used with the **Get** and **Test** operations to retrieve the current state of a resource instance +and validate whether it's in the desired state. Most resources also support enforcing the desired +state with the **Set** operation. + +Example scenarios include: + +- How to update the contents of a file. +- How to run a utility that changes the state of a machine. +- How to configure settings of an application. + +### Differences from PowerShell DSC + +DSC differs from PowerShell Desired State Configuration (PSDSC) in a few important ways: + +- DSC doesn't _depend_ on PowerShell, Windows PowerShell, or the [PSDesiredStateConfiguration][01] + PowerShell module. DSC provides full compatibility with PSDSC resources through the + `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` _adapter resources_. + + With the `Microsoft.DSC/PowerShell` adapter resource, you can use any PSDSC resource implemented + as a PowerShell class. The resource handles discovering, validating, and invoking PSDSC + resources in PowerShell. The resource is included in the DSC install package for every platform. + + With the `Microsoft.Windows/WindowsPowerShell` adapter resource, you can use any PSDSC resource + compatible with Windows PowerShell. The resource handles discovering, validating, and invoking + PSDSC resources in Windows PowerShell. The resource is included in the DSC install packages for + Windows only. +- Because DSC doesn't depend on PowerShell, you can use DSC without PowerShell installed and manage + resources written in bash, Python, C#, Rust, or any other language. +- DSC doesn't include a local configuration manager. DSC is invoked as a command. It doesn't + run as a service. +- New DSC resources define their schemas with JSON or YAML files, not MOF files. Self-contained + resources define a _resource manifest_ that indicates how DSC should invoke the resource and what + properties the resource can manage. For adapted resources, like those implemented in PowerShell, + the adapter resource tells DSC what the available properties are for the resource and handles + invoking the adapted resources. +- Configuration documents are defined in JSON or YAML files, not PowerShell script files. + Configuration documents support a subset of functionality in ARM templates, including parameters, + variables, metadata, and expression functions to dynamically resolve data in the configuration. + +## Installation + +### Install DSC manually + +To install DSC on any platform: + +1. Download the [latest release from the PowerShell/DSC repository][02]. +1. Expand the release archive. +1. Add the folder containing the expanded archive contents to the `PATH`. + +### Install DSC on Windows with WinGet + +The following commands can be used to install DSC using the published `winget` packages: + +Search for the latest version of DSC + +```powershell +winget search DesiredStateConfiguration +``` + +```Output +Name Id Version Source +--------------------------------------------------------------- +DesiredStateConfiguration 9NVTPZWRC6KQ Unknown msstore +DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z Unknown msstore +``` + +Install DSC using the `id` parameter: + +```powershell +# Install latest stable +winget install --id 9NVTPZWRC6KQ --source msstore +``` + +```powershell +# Install latest preview +winget install --id 9PCX3HX4HZ0Z --source msstore +``` + +## Integrating with DSC + +DSC is a platform tool that abstracts the concerns for defining and invoking resources. Higher +order tools, like [WinGet][03], [Microsoft Dev Box][04], and [Azure Machine Configuration][05] are +early partners for DSC as orchestration agents. + +DSC uses JSON schemas to define the structure of resources, configuration documents, and the +outputs that DSC returns. These schemas make it easier to integrate DSC with other tools, because +they standardize and document how to interface with DSC. + +For more information, see [DSC JSON Schema reference overview][06]. + +## See Also + +- [Anatomy of a command-based DSC Resource][07] to learn about authoring a resource in your + language of choice. +- [Command line reference for the 'dsc' command][08] +- [DSC JSON Schema reference overview][06] +- [WinGet Configuration][09] + + +[01]: https://github.com/powershell/psdesiredstateconfiguration +[02]: https://github.com/PowerShell/DSC/releases/latest +[03]: /windows/package-manager/winget +[04]: /azure/dev-box/overview-what-is-microsoft-dev-box +[05]: /azure/governance/machine-configuration/overview +[06]: ./reference/schemas/overview.md +[07]: ./concepts/resources/anatomy.md +[08]: ./reference/cli/index.md +[09]: /windows/package-manager/configuration/ diff --git a/docs/reference/cli/completer/command.md b/docs/reference/cli/completer/index.md similarity index 84% rename from docs/reference/cli/completer/command.md rename to docs/reference/cli/completer/index.md index 84d2ce44..b86ae1e5 100644 --- a/docs/reference/cli/completer/command.md +++ b/docs/reference/cli/completer/index.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc completer' command -ms.date: 01/17/2024 +ms.date: 03/25/2025 ms.topic: reference title: dsc completer --- @@ -78,31 +78,36 @@ shell the application returns a completion script for: - `zsh` - [Z SHell (ZSH)][05] ```yaml -Type: String -Mandatory: true -ValidValues: [ - bash, - elvish, - fish, - powershell, - zsh, - ] +Type : string +Mandatory : true +ValidValues : [ + bash, + elvish, + fish, + powershell, + zsh, + ] ``` ## Options ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` [01]: https://www.gnu.org/software/bash/ [02]: https://elv.sh/ [03]: https://fishshell.com/ -[04]: https://learn.microsoft.com/powershell/scripting/overview +[04]: /powershell/scripting/overview [05]: https://zsh.sourceforge.io/ diff --git a/docs/reference/cli/config/export.md b/docs/reference/cli/config/export.md index 1097cda0..57546c0c 100644 --- a/docs/reference/cli/config/export.md +++ b/docs/reference/cli/config/export.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config export' command -ms.date: 09/06/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc config export --- @@ -13,22 +13,22 @@ Generates a configuration document that defines the existing instances of a set ## Syntax -### Configuration document from stdin +### Configuration document from file ```sh - | dsc config export [Options] +dsc config export [Options] --file ``` ### Configuration document from option string ```sh -dsc config export [Options] --document +dsc config export [Options] --input ``` -### Configuration document from file +### Configuration document from stdin ```sh -dsc config export [Options] --path +cat | dsc config export [Options] --file - ``` ## Description @@ -36,10 +36,10 @@ dsc config export [Options] --path The `export` subcommand generates a configuration document that includes every instance of a set of resources. -The configuration document must be passed to this command as JSON or YAML over stdin, as a string -with the **document** option, or from a file with the **path** option. +The configuration document must be passed to this command as JSON or YAML with the `--input` or +`--file` option. -The input configuration defines the resources to export. DSC ignores any properties specified for +The input document defines the resources to export. DSC ignores any properties specified for the resources in the input configuration for the operation, but the input document and any properties for resource instances must still validate against the configuration document and resource instance schemas. @@ -49,65 +49,158 @@ configuration. Only define each resource type once. If the configuration documen resource instance where the resource type isn't exportable or has already been declared in the configuration, DSC raises an error. +## Examples + +### Example 1 - Test whether a configuration's resource instances are in the desired state + + + +The command inspects the system to return a configuration document containing every discovered +instance of the resources defined in the configuration document saved as `example.dsc.config.yaml`. +It passes the configuration document to the command from stdin using the `--file` option. + +```yaml +# example.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Operating system information + type: Microsoft/OSInfo + properties: {} +- name: Processes + type: Microsoft/Process + properties: {} +``` + +```sh +cat ./example.dsc.config.yaml | dsc config export --file - +``` + +### Example 2 - Passing a file to read as the configuration document + + + +The command uses the `--file` option to export resources from the configuration defined in the +`example.dsc.config.yaml` file. + +```sh +dsc config export --file ./example.dsc.config.yaml +``` + +### Example 3 - Passing a configuration document as a variable + + + +The command uses the `--input` option to exoirt resources from the configuration stored in the +`$desired` variable. + +```sh +dsc config export --input $desired +``` + ## Options -### -d, --document +### -i, --input + + + + +Specifies the configuration document to validate state for. -Specifies the configuration document to export from as a JSON or YAML object. DSC validates the -document against the configuration document schema. If the validation fails, DSC raises an error. +The document must be a string containing a JSON or YAML object. DSC validates the document against +the configuration document schema. If the validation fails, DSC raises an error. -This option can't be used with configuration document over stdin or the `--path` option. Choose -whether to pass the configuration document to the command over stdin, from a file with the `--path` -option, or with the `--document` option. +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + + +Defines the path to a configuration document to validate state for. -Defines the path to a configuration document to export instead of piping the document from stdin or -passing it as a string with the `--document` option. The specified file must contain a -configuration document as a JSON or YAML object. DSC validates the document against the -configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC -raises an error. +The specified file must contain a configuration document as a JSON or YAML object. DSC validates +the document against the configuration document schema. If the validation fails, or if the +specified file doesn't exist, DSC raises an error. -This option is mutually exclusive with the `--document` option. When you use this option, DSC -ignores any input from stdin. +You can also use this option to pass a configuration document from stdin, as shown in +[Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][02]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that defines a configuration document including every instance of -the resources declared in the input configuration. For more information, see -[DSC Configuration document schema reference][02]. +This command returns formatted data that defines a configuration document including every instance +of the resources declared in the input configuration. For more information, see +[DSC Configuration document schema reference][03]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + [01]: ../../schemas/resource/manifest/export.md -[02]: ../../schemas/config/document.md +[02]: https://jsonlines.org/ +[03]: ../../schemas/config/document.md diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md index 34a2bc5d..3694d36d 100644 --- a/docs/reference/cli/config/get.md +++ b/docs/reference/cli/config/get.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config get' command -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: dsc config get --- @@ -13,39 +13,42 @@ Retrieves the current state of resource instances in a configuration document. ## Syntax -### Configuration document from stdin +### Configuration document from file ```sh - | dsc config get [Options] +dsc config get [Options] --file ``` ### Configuration document from option string ```sh -dsc config get [Options] --document +dsc config get [Options] --input ``` -### Configuration document from file +### Configuration document from stdin ```sh -dsc config get [Options] --path +cat | dsc config get [Options] --file - ``` ## Description -The `get` subcommand returns the current state of the resource instances in a configuration +The `get` subcommand returns the actual state of the resource instances in a configuration document. When this command runs, DSC validates the configuration document before invoking the get operation for each resource instance defined in the document. -The configuration document must be passed to this command as JSON or YAML over stdin, as a string -with the **document** option, or from a file with the **path** option. +The configuration document must be passed to this command as JSON or YAML with the `--input` or +`--file` option. ## Examples ### Example 1 - Get the current state of a configuration's resource instances + + The command returns the actual state for the resource instances defined in the configuration -document saved as `example.dsc.config.yaml`. +document saved as `example.dsc.config.yaml`. It passes the configuration document to the command +from stdin using the `--file` option. ```yaml # example.dsc.config.yaml @@ -70,12 +73,14 @@ resources: ``` ```sh -cat ./example.dsc.config.yaml | dsc config get +cat ./example.dsc.config.yaml | dsc config get --file - ``` ### Example 2 - Passing a file to read as the configuration document -The command uses the **path** option to retrieve the resource instances defined in the + + +The command uses the `--file` option to retrieve the resource instances defined in the `example.dsc.config.yaml` file. ```sh @@ -84,72 +89,118 @@ dsc config get --path ./example.dsc.config.yaml ### Example 3 - Passing a configuration document as a variable -The command uses the **document** option to retrieve the resource instances defined in a + + +The command uses the `--input` option to retrieve the resource instances defined in a configuration document stored in the `$desired` variable. ```sh -dsc config get --document $desired +dsc config get --input $desired ``` ## Options -### -d, --document +### -i, --input + + + -Specifies the configuration document to retrieve actual state for. The document must be a string -containing a JSON or YAML object. DSC validates the document against the configuration document -schema. If the validation fails, DSC raises an error. +Specifies the configuration document to retrieve actual state for. -This option can't be used with configuration document over stdin or the `--path` option. Choose -whether to pass the configuration document to the command over stdin, from a file with the `--path` -option, or with the `--document` option. +The document must be a string containing a JSON or YAML object. DSC validates the document against +the configuration document schema. If the validation fails, DSC raises an error. + +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + -Defines the path to a configuration document to retrieve actual state for instead of piping the -document from stdin or passing it as a string with the `--document` option. The specified file must -contain a configuration document as a JSON or YAML object. DSC validates the document against the -configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC -raises an error. +Defines the path to a configuration document to retrieve actual state for. -This option is mutually exclusive with the `--document` option. When you use this option, DSC -ignores any input from stdin. +The specified file must contain a configuration document as a JSON or YAML object. DSC validates +the document against the configuration document schema. If the validation fails, or if the +specified file doesn't exist, DSC raises an error. + +You can also use this option to pass a configuration document from stdin, as shown in +[Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][01]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that includes whether the operation or any resources raised any +This command returns formatted data that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the get operation results for -every instance. For more information, see [dsc config get result schema][01]. +every instance. For more information, see [dsc config get result schema][02]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). -[01]: ../../schemas/outputs/config/get.md + +[01]: https://jsonlines.org/ +[02]: ../../schemas/outputs/config/get.md diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/index.md similarity index 70% rename from docs/reference/cli/config/command.md rename to docs/reference/cli/config/index.md index 3b51dd14..ceb9475e 100644 --- a/docs/reference/cli/config/command.md +++ b/docs/reference/cli/config/index.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config' command -ms.date: 02/05/2024 +ms.date: 03/25/2025 ms.topic: reference title: dsc config --- @@ -57,12 +57,15 @@ dsc config help [] For example, `dsc config help` gets the help for this command. `dsc config help set` gets the help for the `set` subcommand. -You can also use the [--help](#-h---help) option on the command or subcommand to display the help +You can also use the [--help](#--help) option on the command or subcommand to display the help information. For example, `dsc config --help` or `dsc config set --help`. ## Options -### -f, --parameters_file +### -f, --parameters-file + + + Specifies the path to a data file containing the parameters to pass to the configuration as JSON or YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses @@ -73,39 +76,74 @@ The data file must contain an object with the `parameters` key. The value of the must be an object where each key is the name of a defined parameter and each value is a valid value for that parameter. -This option can't be used with the `--parameters` option. Choose whether to pass the parameters as -a data string with the `--parameters` option or in a data file with the `--parameters_file` option. +This option is mutually exclusive with the `--parameters` option. For more information about defining parameters in a configuration document, see [DSC Configuration document parameter schema][06]. For more information about using parameters in configuration document, see the [parameters function reference][07]. +```yaml +Type : string +Mandatory : false +LongSyntax : --parameters-file +ShortSyntax : -f +``` + ### -p, --parameters -Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify -this option, DSC interprets the keys in the data string as parameters and uses the specified -values. The values in the data string override any defaults defined in the configuration itself. + + + +Specifies the parameters to pass to the configuration document as a string of data formatted as +JSON or YAML. When you specify this option, DSC interprets the keys in the data string as +parameters and uses the specified values. The values in the data string override any defaults +defined in the configuration document itself. The data string must contain an object with the `parameters` key. The value of the `parameters` key must be an object where each key is the name of a defined parameter and each value is a valid value for that parameter. -This option can't be used with the `--parameters_file` option. Choose whether to pass the -parameters as a data string with the `--parameters` option or in a data file with the -`--parameters_file` option. +This option is mutually exclusive with the `--parameters_file` option. For more information about defining parameters in a configuration document, see [DSC Configuration document parameter schema][06]. For more information about using parameters in configuration document, see the [parameters function reference][07]. +```yaml +Type : string +Mandatory : false +LongSyntax : --parameters +ShortSyntax : -p +``` + +### -r, --system-root + + + + +Use this option to specify the path to the operating system root when you aren't targeting the +current running OS. + +```yaml +Type : string +Mandatory : false +LongSyntax : --system-root +ShortSyntax : -r +``` + ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Environment variables @@ -122,11 +160,11 @@ containing the specified configuration document. You can use the [envvar][08] configuration function to reference that folder path for resource instances in the configuration. -[01]: ../resource/command.md -[02]: export.md -[03]: get.md -[04]: set.md -[05]: test.md +[01]: ../resource/index.md +[02]: ./export.md +[03]: ./get.md +[04]: ./set.md +[05]: ./test.md [06]: ../../schemas/config/parameter.md [07]: ../../schemas/config/functions/parameters.md [08]: ../../schemas/config/functions/envvar.md diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md index 19549bc2..196597c6 100644 --- a/docs/reference/cli/config/set.md +++ b/docs/reference/cli/config/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config set' command -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: dsc config set --- @@ -13,22 +13,22 @@ Enforces the desired state of resource instances in a configuration document. ## Syntax -### Configuration document from stdin +### Configuration document from file ```sh - | dsc config set [Options] +dsc config set [Options] --file ``` ### Configuration document from option string ```sh -dsc config set [Options] --document +dsc config set [Options] --input ``` -### Configuration document from file +### Configuration document from stdin ```sh -dsc config set [Options] --path +cat | dsc config set [Options] --file - ``` ## Description @@ -38,13 +38,15 @@ document. When this command runs, DSC validates the configuration document befor operation for each resource instance defined in the document. DSC then invokes the set operation for each resource instance that isn't in the desired state. -The configuration document must be passed to this command as JSON or YAML over stdin, as a string -with the **document** option, or from a file with the **path** option. +The configuration document must be passed to this command as JSON or YAML with the `--input` or +`--file` option. ## Examples ### Example 1 - Set a configuration's resource instances to the desired state + + The command inspects the resource instances defined in the configuration document saved as `example.dsc.config.yaml` and sets them to the desired state as needed. @@ -71,11 +73,13 @@ resources: ``` ```sh -cat ./example.dsc.config.yaml | dsc config set +cat ./example.dsc.config.yaml | dsc config set --file - ``` ### Example 2 - Passing a file to read as the configuration document + + The command uses the **path** option to enforce the configuration defined in the `example.dsc.config.yaml` file. @@ -85,6 +89,8 @@ dsc config set --path ./example.dsc.config.yaml ### Example 3 - Passing a configuration document as a variable + + The command uses the **document** option to enforce the configuration stored in the `$desired` variable. @@ -94,39 +100,53 @@ dsc config set --document $desired ## Options -### -d, --document +### -i, --input + + + + +Specifies the configuration document to enforce state for. -Specifies the configuration document to enforce state for. The document must be a string -containing a JSON or YAML object. DSC validates the document against the configuration document -schema. If the validation fails, DSC raises an error. +The document must be a string containing a JSON or YAML object. DSC validates the document against +the configuration document schema. If the validation fails, DSC raises an error. -This option can't be used with configuration document over stdin or the `--path` option. Choose -whether to pass the configuration document to the command over stdin, from a file with the `--path` -option, or with the `--document` option. +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + + +Defines the path to a configuration document to enforce state for. -Defines the path to a configuration document to enforce state for instead of piping the document -from stdin or passing it as a string with the `--document` option. The specified file must contain -a configuration document as a JSON or YAML object. DSC validates the document against the -configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC -raises an error. +The specified file must contain a configuration document as a JSON or YAML object. DSC validates +the document against the configuration document schema. If the validation fails, or if the +specified file doesn't exist, DSC raises an error. -This option is mutually exclusive with the `--document` option. When you use this option, DSC -ignores any input from stdin. +You can also use this option to pass a configuration document from stdin, as shown in +[Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` ### -w, --what-if + + + When you specify this flag option, DSC doesn't actually change the system state with the `set` operation. Instead, it returns output indicating _how_ the operation will change system state when called without this option. Use this option to preview the changes DSC will make to a system. @@ -135,36 +155,71 @@ The output for the command when you use this option is the same as without, exce `ExecutionType` metadata field is set to `WhatIf` instead of `Actual`. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --what-if +ShortSyntax : -w ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][01]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that includes whether the operation or any resources raised any +This command returns formatted data that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the set operation results for -every instance. For more information, see [dsc config get result schema][01]. +every instance. For more information, see [dsc config get result schema][02]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). -[01]: ../../schemas/outputs/config/set.md + +[01]: https://jsonlines.org/ +[02]: ../../schemas/outputs/config/set.md diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md index 26cbabb2..ca84dc42 100644 --- a/docs/reference/cli/config/test.md +++ b/docs/reference/cli/config/test.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config test' command -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: dsc config test --- @@ -13,22 +13,22 @@ Verifies whether the resource instances in a configuration document are in the d ## Syntax -### Configuration document from stdin +### Configuration document from file ```sh - | dsc config test [Options] +dsc config test [Options] --file ``` ### Configuration document from option string ```sh -dsc config test [Options] --document +dsc config test [Options] --document ``` -### Configuration document from file +### Configuration document from stdin ```sh -dsc config test [Options] --path +cat | dsc config test [Options] --file - ``` ## Description @@ -37,15 +37,18 @@ The `test` subcommand verifies whether the resource instances in a configuration the desired state. When this command runs, DSC validates the configuration document before invoking the test operation for each resource instance defined in the document. -The configuration document must be passed to this command as JSON or YAML over stdin, as a string -with the **document** option, or from a file with the **path** option. +The configuration document must be passed to this command as JSON or YAML with the `--input` or +`--file` option. ## Examples ### Example 1 - Test whether a configuration's resource instances are in the desired state + + The command returns the status, desired state, actual state, and differing properties for the -resource instances defined in the configuration document saved as `example.dsc.config.yaml`. +resource instances defined in the configuration document saved as `example.dsc.config.yaml`. It +passes the configuration document to the command from stdin using the `--file` option. ```yaml # example.dsc.config.yaml @@ -70,86 +73,134 @@ resources: ``` ```sh -cat ./example.dsc.config.yaml | dsc config test +cat ./example.dsc.config.yaml | dsc config test --file - ``` ### Example 2 - Passing a file to read as the configuration document -The command uses the **path** option to validate the configuration defined in the + + +The command uses the `--file` option to validate the configuration defined in the `example.dsc.config.yaml` file. ```sh -dsc config test --path ./example.dsc.config.yaml +dsc config test --file ./example.dsc.config.yaml ``` ### Example 3 - Passing a configuration document as a variable -The command uses the **document** option to validate the configuration stored in the `$desired` + + +The command uses the `--input` option to validate the configuration stored in the `$desired` variable. ```sh -dsc config test --document $desired +dsc config test --input $desired ``` ## Options -### -d, --document +### -i, --input + + + -Specifies the configuration document to validate state for. The document must be a string -containing a JSON or YAML object. DSC validates the document against the configuration document -schema. If the validation fails, DSC raises an error. +Specifies the configuration document to validate state for. -This option can't be used with configuration document over stdin or the `--path` option. Choose -whether to pass the configuration document to the command over stdin, from a file with the `--path` -option, or with the `--document` option. +The document must be a string containing a JSON or YAML object. DSC validates the document against +the configuration document schema. If the validation fails, DSC raises an error. + +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + -Defines the path to a configuration document to validate state for instead of piping the document -from stdin or passing it as a string with the `--document` option. The specified file must contain -a configuration document as a JSON or YAML object. DSC validates the document against the -configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC -raises an error. +Defines the path to a configuration document to validate state for. -This option is mutually exclusive with the `--document` option. When you use this option, DSC -ignores any input from stdin. +The specified file must contain a configuration document as a JSON or YAML object. DSC validates +the document against the configuration document schema. If the validation fails, or if the +specified file doesn't exist, DSC raises an error. + +You can also use this option to pass a configuration document from stdin, as shown in +[Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][01]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that includes whether the operation or any resources raised any +This command returns formatted data that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the test operation results for -every instance. For more information, see [dsc config test result schema][01]. +every instance. For more information, see [dsc config test result schema][02]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). -[01]: ../../schemas/outputs/config/test.md + +[01]: https://jsonlines.org/ +[02]: ../../schemas/outputs/config/test.md diff --git a/docs/reference/cli/dsc.md b/docs/reference/cli/index.md similarity index 67% rename from docs/reference/cli/dsc.md rename to docs/reference/cli/index.md index b7d311db..061bab89 100644 --- a/docs/reference/cli/dsc.md +++ b/docs/reference/cli/index.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc' command -ms.date: 02/05/2024 +ms.date: 03/25/2025 ms.topic: reference title: dsc --- @@ -22,7 +22,7 @@ dsc [Options] ### completer The `completer` command returns a shell script that, when executed, registers completions for the -given shell. For more information, see [completer][01]. +given shell. For more information, see [dsc completer][01]. ### config @@ -32,7 +32,7 @@ The `config` command manages a DSC Configuration document. You can use it to: - Test whether a configuration is in the desired state. - Set a configuration to the desired state. -For more information, see [config][02]. +For more information, see [dsc config][02]. ### resource @@ -44,12 +44,12 @@ The `resource` command manages a DSC Resource. You can use it to: - Test whether a resource instance is in the desired state. - Set a resource instance to the desired state. -For more information, see [resource][03] +For more information, see [dsc resource][03] ### schema The `schema` command returns the JSON schema for a specific DSC type. For more information, see -[schema][04]. +[dsc schema][04]. ### help @@ -64,23 +64,16 @@ dsc help [] For example, `dsc help config` gets the help for the `config` subcommand. `dsc help config set` gets the help for the `config set` subcommand. -You can also use the [--help](#-h---help) option on a command to display the help information. For +You can also use the [--help](#--help) option on a command to display the help information. For example, `dsc config --help` or `dsc config set --help`. ## Options -### -h, --help - -Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. - -```yaml -Type: Boolean -Mandatory: false -``` - ### -l, --trace-level + + + Defines the minimum message level DSC should emit during an operation. Messages in DSC are categorized by their level. @@ -96,21 +89,26 @@ set to any value in the list, DSC emits messages at that level and above. > [!WARNING] > The `trace` level output emits all JSON input/output that DSC processes during execution. DSC > doesn't sanitize the JSON before emitting it. This trace level is only intended for developer -> use. Never redirect `trace` level output to storage as it may contain sensitive information. +> use. Never redirect `trace` level output to storage as it might contain sensitive information. For example, when the log level is `debug`, DSC emits messages for every log level except `trace`. When the log level is `error`, DSC only emits error messages. DSC ignores every message with a lower log level. ```yaml -Type: String -Mandatory: false -DefaultValue: warning -ValidValues: [error, warning, info, debug, trace] +Type : string +Mandatory : false +DefaultValue : warning +ValidValues : [error, warning, info, debug, trace] +LongSyntax : --trace-level +ShortSyntax : -l ``` ### -f, --trace-format + + + Defines the output format to use when emitting trace messages on stderr. DSC supports the following formats: @@ -121,27 +119,72 @@ formats: line number as properties. ```yaml -Type: String -Mandatory: false -DefaultValue: default -ValidValues: [default, plaintext, json] +Type : string +Mandatory : false +DefaultValue : default +ValidValues : [default, plaintext, json] +LongSyntax : --trace-format +ShortSyntax : -f +``` + +### -p, --progress-format + + + + +Defines the progress format to use when emitting progress messages on stderr. DSC supports the +following formats: + +- `default` - Shows a progress bar if DSC detects that it's being called interactively. Otherwise, + DSC doesn't show any progress. +- `none` - Doesn't show any progress. +- `json` - Emits progress as compressed JSON objects with the timestamp, level, message, and line + number as properties. + +```yaml +Type : string +Mandatory : false +DefaultValue : default +ValidValues : [default, none, json] +LongSyntax : --progress-format +ShortSyntax : -p ``` ### -V, --version + + + Displays the version of the application. When you specify this option, the application ignores all -options and arguments after this one. +options and arguments except for [--help](#--help), which overrides this option. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --version +ShortSyntax : -V +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Environment Variables -By default, the `dsc` command searches for command-based DSC Resource manifests in the folders -defined by the `PATH` environment variable. If the `DSC_RESOURCE_PATH` environment variable is -defined, `dsc` searches the folders in `DSC_RESOURCE_PATH` instead of `PATH`. +By default, the `dsc` command searches for DSC resource manifests in the folders defined by the +`PATH` environment variable. If the `DSC_RESOURCE_PATH` environment variable is defined, `dsc` +searches the folders in `DSC_RESOURCE_PATH` instead of `PATH`. The `DSC_RESOURCE_PATH` environment must be an environment variable that follows the same conventions as the `PATH` environment variable for the operating system. Separate folder paths with @@ -167,7 +210,7 @@ execution of the command. DSC expects input strings to use UTF-8 encoding. When you pass input from stdin or the path to a file, ensure that the input is encoded as UTF-8. -[01]: completer/command.md -[02]: config/command.md -[03]: resource/command.md -[04]: schema/command.md +[01]: completer/index.md +[02]: config/index.md +[03]: resource/index.md +[04]: schema/index.md diff --git a/docs/reference/cli/resource/delete.md b/docs/reference/cli/resource/delete.md index 7636366a..ab6da0d1 100644 --- a/docs/reference/cli/resource/delete.md +++ b/docs/reference/cli/resource/delete.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource delete' command -ms.date: 05/08/2024 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource delete --- @@ -9,7 +9,7 @@ title: dsc resource delete ## Synopsis -Invokes the delete operation of a resource. +Removes a resource instance from the system. ## Syntax @@ -19,22 +19,22 @@ Invokes the delete operation of a resource. dsc resource delete [Options] --resource ``` -### Instance properties from stdin +### Instance properties from input option ```sh - | dsc resource delete [Options] --resource +dsc resource delete --input --resource ``` -### Instance properties from input option +### Instance properties from file ```sh -dsc resource delete --input '' --resource +dsc resource delete --file --resource ``` -### Instance properties from file +### Instance properties from stdin ```sh -dsc resource delete --path --resource +cat | dsc resource delete [Options] --resource --file - ``` ## Description @@ -42,8 +42,7 @@ dsc resource delete --path --resource The `delete` subcommand removes a resource instance. Any properties the resource requires for discerning which instance to delete must be passed to this -command as a JSON or YAML object. The object can be passed to this command from stdin or with the -`--input` option. You can also use the `--path` option to read the object from a JSON or YAML file. +command as a JSON or YAML object with the `--input` or `--file` opion. This command returns no output when successful. If it encounters an error, it surfaces the error to the caller on stderr and exits with a non-zero exit code. @@ -52,8 +51,10 @@ the caller on stderr and exits with a non-zero exit code. ### Example 1 - delete resource instance with input option -If a resource requires one or more property values to return the actual state of the instance, the -instance properties can be passed with the **input** option as either JSON or YAML. + + +If a resource requires one or more property values to identify the instance, the instance +properties can be passed with the `--input` option as either JSON or YAML. ```sh dsc resource delete --resource Microsoft.Windows/Registry --input '{ @@ -63,36 +64,40 @@ dsc resource delete --resource Microsoft.Windows/Registry --input '{ ### Example 2 - delete resource instance with input from stdin -If a resource requires one or more property values to return the actual state of the instance, the -instance properties can be passed over stdin as either JSON or YAML. + + +If a resource requires one or more property values to identify the instance, the instance +properties can be passed over stdin as either JSON or YAML with the `--file` option. ```sh '{ "keyPath": "HKCU\\DSC\\Example" -}' | dsc resource delete --resource Microsoft.Windows/Registry +}' | dsc resource delete --resource Microsoft.Windows/Registry --file - ``` ### Example 3 - delete resource instance with input from a YAML file -If a resource requires one or more property values to return the actual state of the instance, the -instance properties can be retrieved from a saved JSON or YAML file. + -```sh -cat ./example.delete.yaml -``` +If a resource requires one or more property values to identify the instance, the instance +properties can be retrieved from a saved JSON or YAML file with the `--file` option. ```yaml +# ./example.delete.yaml keyPath: HKCU\\DSC\\Example ``` ```sh -dsc resource delete --resource Microsoft.Windows/Registry --path ./example.delete.yaml +dsc resource delete --resource Microsoft.Windows/Registry --file ./example.delete.yaml ``` ## Options ### -r, --resource + + + Specifies the fully qualified type name of the DSC Resource to use, like `Microsoft.Windows/Registry`. @@ -103,53 +108,66 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` ### -i, --input -Specifies a JSON or YAML object with the properties needed for retrieving an instance of the DSC -Resource. DSC validates the object against the resource's instance schema. If the validation fails, -DSC raises an error. + + + +Specifies the resource instance to delete. -This option can't be used with instance properties over stdin or the `--path` option. Choose -whether to pass the instance properties to the command over stdin, from a file with the `--path` -option, or with the `--input` option. +The instance must be a string containing a JSON or YAML object. DSC validates the object against +the resource's instance schema. If the validation fails, DSC raises an error. -DSC ignores this option when the `--all` option is specified. +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file -Defines the path to a text file to read as input for the command instead of piping input from stdin -or passing it as a string with the `--input` option. The specified file must contain JSON or YAML -that represents valid properties for the resource. DSC validates the object against the resource's -instance schema. If the validation fails, or if the specified file doesn't exist, DSC raises an -error. + + -This option is mutually exclusive with the `--input` option. When you use this option, DSC -ignores any input from stdin. +Defines the path to a file defining the resource instance to delete. -DSC ignores this option when the `--all` option is specified. +The specified file must contain a JSON or YAML object that represents valid properties for the +resource. DSC validates the object against the resource's instance schema. If the validation fails, +or if the specified file doesn't exist, DSC raises an error. + +You can also use this option to pass an instance from stdin, as shown in [Example 2](#example-2). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output diff --git a/docs/reference/cli/resource/export.md b/docs/reference/cli/resource/export.md index 78c660bd..97797794 100644 --- a/docs/reference/cli/resource/export.md +++ b/docs/reference/cli/resource/export.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource export' command -ms.date: 09/06/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource export --- @@ -9,7 +9,7 @@ title: dsc resource export ## Synopsis -Generates a configuration document that defines the existing instances of a resource. +Generates a configuration document that defines the existing instances of a specific resource. ## Syntax @@ -29,6 +29,9 @@ the input configuration. If the specified resource type isn't exportable, DSC ra ### -r, --resource + + + Specifies the fully qualified type name of the DSC Resource to export, like `Microsoft.Windows/Registry`. @@ -39,37 +42,72 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][02]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that defines a configuration document including every instance of +This command returns formatted data that defines a configuration document including every instance of the resources declared in the input configuration. For more information, see -[DSC Configuration document schema reference][02]. +[DSC Configuration document schema reference][03]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + [01]: ../../schemas/resource/manifest/export.md -[02]: ../../schemas/config/document.md +[02]: https://jsonlines.org/ +[03]: ../../schemas/config/document.md diff --git a/docs/reference/cli/resource/get.md b/docs/reference/cli/resource/get.md index b3fbae47..17e6ea7b 100644 --- a/docs/reference/cli/resource/get.md +++ b/docs/reference/cli/resource/get.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource get' command -ms.date: 09/06/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource get --- @@ -9,7 +9,7 @@ title: dsc resource get ## Synopsis -Invokes the get operation of a resource. +Retrieves the actual state of a resource instance. ## Syntax @@ -19,22 +19,22 @@ Invokes the get operation of a resource. dsc resource get [Options] --resource ``` -### Instance properties from stdin +### Instance properties from input option ```sh - | dsc resource get [Options] --resource +dsc resource get --input --resource ``` -### Instance properties from input option +### Instance properties from file ```sh -dsc resource get --input '' --resource +dsc resource get --file --resource ``` -### Instance properties from file +### Instance properties from stdin ```sh -dsc resource get --path --resource +cat | dsc resource get [Options] --resource --file - ``` ## Description @@ -45,15 +45,16 @@ By default, this subcommand returns one instance from a specific DSC Resource. T resources, use the `--all` parameter, a resource group, or the [dsc config get][01] command. Any properties the resource requires for retrieving the state of an instance must be passed to this -command as a JSON or YAML object. The object can be passed to this command from stdin or with the -`--input` option. You can also use the `--path` option to read the object from a JSON or YAML file. +command as a JSON or YAML object with the `--input` or `--file` option. ## Examples ### Example 1 - Get resource instance without any input -For single-instance resources that don't require any property values to return the actual -state of the resource instance, the instance properties aren't required. + + +For single-instance resources that don't require any property values to return the actual state of +the resource instance, the instance properties aren't required. ```sh dsc resource get --resource Microsoft/OSInfo @@ -70,8 +71,10 @@ actualState: ### Example 2 - Get resource instance with input option + + If a resource requires one or more property values to return the actual state of the instance, the -instance properties can be passed with the **input** option as either JSON or YAML. +instance properties can be passed with the `--input` option as either JSON or YAML. ```sh dsc resource get --resource Microsoft.Windows/Registry --input '{ @@ -91,14 +94,16 @@ actualState: ### Example 3 - Get resource instance with input from stdin + + If a resource requires one or more property values to return the actual state of the instance, the -instance properties can be passed over stdin as either JSON or YAML. +instance properties can be passed over stdin as either JSON or YAML with the `--file` option. ```sh '{ "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion", "valueName": "SystemRoot" -}' | dsc resource get --resource Microsoft.Windows/Registry +}' | dsc resource get --resource Microsoft.Windows/Registry --file - ``` ```yaml @@ -112,14 +117,13 @@ actualState: ### Example 4 - Get resource instance with input from a YAML file + + If a resource requires one or more property values to return the actual state of the instance, the instance properties can be retrieved from a saved JSON or YAML file. -```sh -cat ./example.yaml -``` - ```yaml +# ./example.yaml keyPath: HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion valueName: SystemRoot ``` @@ -141,6 +145,9 @@ actualState: ### -a, --all + + + Specifies that the command should return every instance of the specified DSC Resource instead of a specific instance. @@ -148,8 +155,7 @@ This option is only valid when the Resource is an exportable resource that defin [export][02] section in the input configuration. If the resource type isn't exportable, DSC raises an error. -When this option is specified, DSC ignores the `--input` and `--path` options and any JSON or YAML -sent to the command from stdin. +When this option is specified, DSC ignores the `--input` and `--path` options. ```yaml Type: Boolean @@ -158,6 +164,9 @@ Mandatory: false ### -r, --resource + + + Specifies the fully qualified type name of the DSC Resource to use, like `Microsoft.Windows/Registry`. @@ -168,76 +177,118 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` ### -i, --input -Specifies a JSON or YAML object with the properties needed for retrieving an instance of the DSC -Resource. DSC validates the object against the resource's instance schema. If the validation fails, -DSC raises an error. + + -This option can't be used with instance properties over stdin or the `--path` option. Choose -whether to pass the instance properties to the command over stdin, from a file with the `--path` -option, or with the `--input` option. +Specifies the resource instance to retrieve. -DSC ignores this option when the `--all` option is specified. +The instance must be a string containing a JSON or YAML object. DSC validates the object against +the resource's instance schema. If the validation fails, DSC raises an error. + +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + + +Defines the path to a file defining the resource instance to retrieve. -Defines the path to a text file to read as input for the command instead of piping input from stdin -or passing it as a string with the `--input` option. The specified file must contain JSON or YAML -that represents valid properties for the resource. DSC validates the object against the resource's -instance schema. If the validation fails, or if the specified file doesn't exist, DSC raises an -error. +The specified file must contain a JSON or YAML object that represents valid properties for the +resource. DSC validates the object against the resource's instance schema. If the validation fails, +or if the specified file doesn't exist, DSC raises an error. -This option is mutually exclusive with the `--input` option. When you use this option, DSC -ignores any input from stdin. +You can also use this option to pass an instance from stdin, as shown in [Example 3](#example-3). -DSC ignores this option when the `--all` option is specified. +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][03]. When you use the [--all option](#--all), each + instance is returned as a JSON Line. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. When you use the `--all` option, each instance is returned as a + YAML document with the `---` document separator between each returned instance. -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -By default, this command returns JSON output that includes the actual state of the instance. When -the `--all` option is specified, the command returns the JSON output for each instance as -[JSON Lines][03]. +By default, this command returns a formatted data object that includes the actual state of the +instance. When the `--all` option is specified, the command returns the formatted data for each +instance. For more information about the structure of the output JSON, see [dsc resource get result schema][04]. +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + + [01]: ../config/get.md [02]: ../../schemas/resource/manifest/export.md [03]: https://jsonlines.org/ diff --git a/docs/reference/cli/resource/command.md b/docs/reference/cli/resource/index.md similarity index 84% rename from docs/reference/cli/resource/command.md rename to docs/reference/cli/resource/index.md index 2a871d82..eb660d48 100644 --- a/docs/reference/cli/resource/command.md +++ b/docs/reference/cli/resource/index.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource' command -ms.date: 09/06/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource --- @@ -69,25 +69,30 @@ dsc resource help [] For example, `dsc resource help` gets the help for this command. `dsc resource help list` gets the help for the `list` subcommand. -You can also use the [--help](#-h---help) option on the command or subcommand to display the help +You can also use the [--help](#--help) option on the command or subcommand to display the help information. For example, `dsc resource --help` or `dsc resource set --help`. ## Options ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` -[01]: ../config/command.md -[02]: list.md -[03]: export.md -[04]: get.md -[05]: set.md -[06]: test.md -[07]: schema.md +[01]: ../config/index.md +[02]: ./list.md +[03]: ./export.md +[04]: ./get.md +[05]: ./set.md +[06]: ./test.md +[07]: ./schema.md diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index bef65e46..8fd6244f 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource list' command -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource list --- @@ -9,7 +9,7 @@ title: dsc resource list ## Synopsis -Returns the list of available DSC Resources with an optional filter. +Retrieves the list of available DSC Resources with an optional filter. ## Syntax @@ -25,13 +25,14 @@ discovers resources by first searching the `PATH` or `DSC_RESOURCE_PATH` environ about the environment variables DSC uses, see [Environment variables][01] If any of the discovered resources are resource adapters, DSC calls the `list` operation for those -adapters if the [--adapter](#-a---adapter) option specifies a matching filter. By default, DSC -doesn't return any adapted resources. +adapters if the [--adapter](#--adapter) option specifies a matching filter. By default, DSC doesn't +return any adapted resources. When you use the `--adapter` option, the command doesn't return any +non-adapted resources. DSC returns the list of discovered resources with their implementation information and metadata. If the command includes the `RESOURCE_NAME` argument, DSC filters the list of discovered resources -before returning them. The **description** and **tags** options filter the results by the -resource descriptions and tags. Filters are always applied after resource discovery. +before returning them. The `--description` and `--tags` options filter the results by the resource +descriptions and tags. Filters are always applied after resource discovery. ### Adapted resource cache @@ -40,9 +41,9 @@ the cache depends on the operating system, as shown in the following table. | Operating system | Cache path | |:----------------:|:------------------------------------------------------| -| Linux | `%LOCALAPPDATA%\dsc\AdaptedResourcesLookupTable.json` | -| macOS | `~/.dsc/AdaptedResourcesLookupTable.json` | -| Windows | `~/.dsc/AdaptedResourcesLookupTable.json` | +| Linux | `~/.dsc/AdaptedResourcesLookupTable.json` | +| macOS | `~/.dsc/AdaptedResourcesLookupTable.json` | +| Windows | `%LOCALAPPDATA%\dsc\AdaptedResourcesLookupTable.json` | ## Examples @@ -56,20 +57,19 @@ dsc resource list ``` ```Output -Type Kind Version Caps RequireAdapter Description --------------------------------------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation -Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Include Import 0.1.0 -------r Allows including a configuration file contents into current configuration. -Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. -Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. -Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. -Microsoft.Windows/Registry Resource 0.1.0 gs---d-- Manage Windows Registry keys and values -Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. -Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell. -Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. -Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes. +Type Kind Version Capabilities RequireAdapter Description +-------------------------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC.Debug/Echo Resource 1.0.0 gs--t--- +Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configu… +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a grou… +Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter fi… +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. +Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. +Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values +Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. +Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows … +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. ``` ### Example 2 - List a specific resource @@ -82,9 +82,9 @@ dsc resource list Microsoft.DSC/Group ``` ```Output -Type Kind Version Caps RequireAdapter Description ---------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Type Kind Version Capabilities RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. ``` ### Example 3 - List resources with a matching type name @@ -97,18 +97,17 @@ dsc resource list Microsoft.DSC/* ``` ```Output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Include Import 0.1.0 -------r Allows including a configuration file contents into current configuration. -Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. -Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. +Type Kind Version Capabilities RequireAdapter Description +-------------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter file. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. ``` ### Example 4 - List resources with a matching description -When the command includes the **description** option, the results include resources that have a +When the command includes the *`--description` option, the results include resources that have a description containing the specified value. ```sh @@ -116,16 +115,15 @@ dsc resource list --description 'supplied configuration' ``` ```Output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. +Type Kind Version Capabilities RequireAdapter Description +---------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. ``` ### Example 5 - List resources with matching tags -When the command includes multiple instances of the **tags** option, the results include resources +When the command includes multiple instances of the `--tags` option, the results include resources that have any of the specified tags. ```sh @@ -133,15 +131,15 @@ dsc resource list --tags Windows --tags Linux ``` ```output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------- -Microsoft.Windows/Registry Resource 0.1.0 gs---d-- Manage Windows Registry keys and values -Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. +Type Kind Version Capabilities RequireAdapter Description +---------------------------------------------------------------------------------------------------------------------------- +Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. ``` ### Example 6 - List resources for a specific adapter -When the command includes the **adapter** option, DSC checks for any discovered resource adapters +When the command includes the `--adapter` option, DSC checks for any discovered resource adapters with a matching name. If it discovers any, it then calls the `list` operation for the adapter and adds the returned list of adapted resources to the discovered resource list. DSC applies any further filters specified with the command after this enumeration. @@ -150,46 +148,6 @@ further filters specified with the command after this enumeration. dsc resource list --adapter Microsoft.Windows/WindowsPowerShell ``` -```Output -Type Kind Version Caps RequireAdapter Description ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -PSDesiredStateConfiguration/Archive Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Environment Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/File Resource 1.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Group Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/GroupSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Log Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Package Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/ProcessSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Registry Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Script Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/Service Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/ServiceSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/SignatureValidation Resource 1.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/User Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WaitForAll Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WaitForAny Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WaitForSome Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsOptionalFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsOptionalFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsPackageCab Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsProcess Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDscResources/Archive Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/Environment Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/Group Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/MsiPackage Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/Registry Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/Script Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/Service Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/User Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsProcess Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -``` - This next command specifies the resource name filter `*Windows*`, limiting the list of returned resources: @@ -197,27 +155,12 @@ resources: dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows* ``` -```Output -Type Kind Version Caps RequireAdapter Description ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -PSDesiredStateConfiguration/WindowsFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsOptionalFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsOptionalFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsPackageCab Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDesiredStateConfiguration/WindowsProcess Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell -PSDscResources/WindowsFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -PSDscResources/WindowsProcess Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. -``` - ## Arguments ### RESOURCE_NAME Specifies an optional filter to apply for the type names of discovered DSC Resources. The filter -may include wildcards (`*`). The filter isn't case-sensitive. +can include wildcards (`*`). The filter isn't case-sensitive. When this argument is specified, DSC filters the results to include only resources where the resource type name matches the filter. @@ -227,14 +170,17 @@ Specifying the filter `*Sql*` returns any resource with the string `Sql` in its the casing. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false ``` ## Options ### -a, --adapter + + + Specifies a filter to define which adapter resources to enumerate adapted resources for. By default, the command doesn't call the `list` command for adapter resources. When you specify this option, DSC looks for adapter resources with type names that match the filter. If it discovers any @@ -242,27 +188,39 @@ adapters matching the filter, it calls the `list` command for those adapters and adapted resources. DSC retrieves adapted resources before applying any other filters for the command. +When you use this option, the command doesn't return any non-adapted resources. + If you specify this option with the filter `*`, DSC calls `list` for every adapter resource it finds before applying the other filters. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --adapter +ShortSyntax : -a ``` ### -d, --description + + + Specifies a string to match in a resource's description. When this option is specified, DSC filters the resources by their description strings. The filter is case-insensitive and matches the value anywhere in the description string. Wildcards aren't permitted. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --description +ShortSyntax : -d ``` ### -t, --tags + + + Specifies a resource tag to filter on. When this option is specified, DSC filters the resources and only includes those with a matching tag. The filter is case-insensitive. Wildcards aren't permitted. @@ -270,39 +228,67 @@ You can specify this option more than once to filter on a set of tags. The resul resources that have at least one of the tags specified with this option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --tags +ShortSyntax : -t ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][02]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always a series of JSON Lines representing each -returned resource. When this option isn't specified, the output for the command shows a table -representing a summary of the returned resources. For more information, see [Output](#output). +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as a summary table + described in the [Output](#output) section of this document. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns a JSON object for each resource that includes the resource's type, version, -manifest settings, and other metadata. For more information, see -[dsc resource list result schema][02]. +This command returns a formatted array containing an object for each resource that includes the +resource's type, version, manifest settings, and other metadata. For more information, see +[dsc resource list result schema][03]. If the output of the command isn't captured or redirected, it displays in the console by default as a summary table for the returned resources. The summary table includes the following columns, @@ -310,20 +296,20 @@ displayed in the listed order: - **Type** - The fully qualified type name of the resource. - **Kind** - Whether the resource is an `adapter`, `group`, `importer`, or typical `Resource`. For - more information, see [DSC Resource kind schema reference][03]. + more information, see [DSC Resource kind schema reference][04]. - **Version** - The semantic version of the resource. -- **Caps** - A display of the resource's [capabilities][04] as flags. The capabilities are +- **Capabilities** - A display of the resource's [capabilities][05] as flags. The capabilities are displayed in the following order, using a `-` instead of the appropriate letter if the resource doesn't have a specific capability: - - `g` indicates that the resource has the [get capability][05]. - - `s` indicates that the resource has the [set capability][06] - - `x` indicates that the resource has the [setHandlesExist capability][07] - - `w` indicates that the resource has the [whatIf capability][08] - - `t` indicates that the resource has the [test capability][09] - - `d` indicates that the resource has the [delete capability][10] - - `e` indicates that the resource has the [export capability][11] - - `r` indicates that the resource has the [resolve capability][12] + - `g` indicates that the resource has the [get capability][06]. + - `s` indicates that the resource has the [set capability][07] + - `x` indicates that the resource has the [setHandlesExist capability][08] + - `w` indicates that the resource has the [whatIf capability][09] + - `t` indicates that the resource has the [test capability][10] + - `d` indicates that the resource has the [delete capability][11] + - `e` indicates that the resource has the [export capability][12] + - `r` indicates that the resource has the [resolve capability][13] For example, the `Microsoft.Windows/Registry` resource has the following capabilities: `gs--d-`, indicating it has the `get`, `set`, and `delete` capabilities. @@ -331,19 +317,20 @@ displayed in the listed order: invoke the returned resource. - **Description** - The short description of the resource's purpose and usage. -To display the output objects as either JSON or YAML objects in the console, use the -[--format](#-f---format) option. +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). -[01]: ../dsc.md#environment-variables -[02]: ../../schemas/outputs/resource/list.md -[03]: ../../schemas/definitions/resourceKind.md -[04]: ../../schemas/outputs/resource/list.md#capabilities -[05]: ../../schemas/outputs/resource/list.md#capability-get -[06]: ../../schemas/outputs/resource/list.md#capability-set -[07]: ../../schemas/outputs/resource/list.md#capability-sethandlesexist -[08]: ../../schemas/outputs/resource/list.md#capability-whatif -[09]: ../../schemas/outputs/resource/list.md#capability-test -[10]: ../../schemas/outputs/resource/list.md#capability-delete -[11]: ../../schemas/outputs/resource/list.md#capability-export -[12]: ../../schemas/outputs/resource/list.md#capability-resolve +[01]: ../index.md#environment-variables +[02]: https://jsonlines.org/ +[03]: ../../schemas/outputs/resource/list.md +[04]: ../../schemas/definitions/resourceKind.md +[05]: ../../schemas/outputs/resource/list.md#capabilities +[06]: ../../schemas/outputs/resource/list.md#capability-get +[07]: ../../schemas/outputs/resource/list.md#capability-set +[08]: ../../schemas/outputs/resource/list.md#capability-sethandlesexist +[09]: ../../schemas/outputs/resource/list.md#capability-whatif +[10]: ../../schemas/outputs/resource/list.md#capability-test +[11]: ../../schemas/outputs/resource/list.md#capability-delete +[12]: ../../schemas/outputs/resource/list.md#capability-export +[13]: ../../schemas/outputs/resource/list.md#capability-resolve diff --git a/docs/reference/cli/resource/schema.md b/docs/reference/cli/resource/schema.md index 1073b1c8..261d209d 100644 --- a/docs/reference/cli/resource/schema.md +++ b/docs/reference/cli/resource/schema.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource schema' command -ms.date: 06/24/2024 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource schema --- @@ -9,7 +9,7 @@ title: dsc resource schema ## Synopsis -Returns the JSON Schema for instances of a resource. +Restrieves the JSON Schema for validating instances of a resource. ## Syntax @@ -23,16 +23,18 @@ The `schema` subcommand returns the JSON schema for a instances of a specific DS uses these schemas to validate the input for the `get`, `set`, and `test` subcommands and when validating the instances in a DSC Configuration document. -Integrating tools may use these schemas for validation or to enhance the configuration authoring +Integrating tools can use these schemas for validation or to enhance the configuration authoring experience. A resource's instance schema defines the valid structure for an instance, including -which properties are mandatory and what their values should be. The instance schemas may also +which properties are mandatory and what their values should be. The instance schemas can also include lightweight documentation for the properties with the `title` and `description` keywords. ## Examples ### Example 1 - Get the schema for a resource -This example returns the schema for the `OSInfo` command-based DSC Resource. + + +This example returns the schema for the `OSInfo` command resource. ```sh dsc resource schema --resource Microsoft/OSInfo @@ -164,7 +166,10 @@ properties: ### -r, --resource -Specifies the fully qualified type name of the DSC Resource to retrieve the instance schema from, + + + +Specifies the fully qualified type name of the DSC Resource to retrieve the instance schema for, like `Microsoft.Windows/Registry`. The fully qualified type name syntax is: `[.][.]/`, where: @@ -174,33 +179,69 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][01]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns a JSON object representing the JSON schema for an instance of the specified +This command returns formatted data representing the JSON schema for an instance of the specified DSC Resource. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + + +[01]: https://jsonlines.org/ diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md index 14559d84..17f2fb98 100644 --- a/docs/reference/cli/resource/set.md +++ b/docs/reference/cli/resource/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource set' command -ms.date: 09/27/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource set --- @@ -9,26 +9,26 @@ title: dsc resource set ## Synopsis -Invokes the set operation of a resource. +Enforces the desired state for a resource instance. ## Syntax -### Instance properties from stdin +### Instance properties from input option ```sh - | dsc resource set [Options] --resource +dsc resource set --input --resource ``` -### Instance properties from input option +### Instance properties from file ```sh -dsc resource set --input '' --resource +dsc resource set --file --resource ``` -### Instance properties from file +### Instance properties from stdin ```sh -dsc resource set --path --resource +cat | dsc resource set [Options] --resource --file - ``` ## Description @@ -38,18 +38,16 @@ The `set` subcommand enforces the desired state of a resource instance and retur This subcommand sets one instance of a specific DSC Resource. To set multiple resources, use a resource group or the [dsc config set][01] command. -The desired state of the instance to set must be passed to this command as a JSON or YAML object. -The object properties must be valid properties for the resource. The instance properties can be -passed to this command from stdin, as a string with the `--input` option, or from a saved file with -the `--path` option. +The desired state of the instance to set must be passed to this command as a JSON or YAML object +with the `--input` or `--file` option. -This subcommand can only be invoked for command-based DSC Resources that define the `set` section -of their resource manifest. If this subcommand is called for a resource that doesn't define a set -operation, DSC raises an error. +This subcommand can only be invoked for command resources that define the `set` section of their +resource manifest. If this subcommand is called for a resource that doesn't define a set operation, +DSC raises an error. > [!IMPORTANT] > The `dsc resource set` command always invokes the `set` operation for the resource. Resources -> may, but aren't required to, implement logic that pretests an instance for the `set` operation. +> might, but aren't required to, implement logic that pretests an instance for the `set` operation. > > This is different from how [dsc config set][02] works, where DSC always tests an instance, either > synthetically or by invoking the `test` operation for the resource, and only invokes `set` for an @@ -77,20 +75,24 @@ operation, DSC raises an error. ### Example 1 - Setting a resource with properties from stdin + + The command ensures that the `Example` key exists in the current user hive. It specifies the -resource instance properties as JSON and passes them from stdin. +desired state for the resource instance as JSON and passes it from stdin. ```sh '{ "keyPath": "HKCU\\Example", "_exist": true -}' | dsc resource set --resource Microsoft.Windows/Registry +}' | dsc resource set --resource Microsoft.Windows/Registry --file - ``` ### Example 2 - Setting a resource with the input option + + The command ensures that the `Example` key exists in the current user hive. It specifies the -resource instance properties as JSON and passes them with the **input** option. +desired state for the resource instance as JSON and passes it with the `--input` option. ```sh dsc resource set --resource Microsoft.Windows/Registry --input '{ @@ -101,14 +103,13 @@ dsc resource set --resource Microsoft.Windows/Registry --input '{ ### Example 3 - Setting a resource with properties from a YAML file -The command ensures that the `Example` key exists in the current user hive. It specifies the -path to a yaml file defining the resource instance properties with the **path** option. + -```sh -cat ./example.yaml -``` +The command ensures that the `Example` key exists in the current user hive. It specifies the path +to a YAML file defining the desired state for the resource instance with the `--file` option. ```yaml +# ./example.yaml keyPath: HKCU\\Example _exist: true ``` @@ -121,6 +122,9 @@ dsc resource set --resource Microsoft.Windows/Registry --path ./example.yaml ### -r, --resource + + + Specifies the fully qualified type name of the DSC Resource to use, like `Microsoft.Windows/Registry`. @@ -131,70 +135,114 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` ### -i, --input -Specifies a JSON or YAML object with the properties defining the desired state of a DSC Resource -instance. DSC validates the object against the resource's instance schema. If the validation fails, -DSC raises an error. +Specifies the desired state of the resource instance to enforce on the system. + +The instance must be a string containing a JSON or YAML object. DSC validates the object against +the resource's instance schema. If the validation fails, DSC raises an error. -This option can't be used with instance properties over stdin or the `--path` option. Choose -whether to pass the instance properties to the command over stdin, from a file with the `--path` -option, or with the `--input` option. +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file + + + + +Defines the path to a file defining the desired state of the resource instance to enforce on the +system. -Defines the path to a text file to read as input for the command instead of piping input from stdin -or passing it as a string with the `--input` option. The specified file must contain JSON or YAML -that represents valid properties for the resource. DSC validates the object against the resource's -instance schema. If the validation fails, or if the specified file doesn't exist, DSC raises an -error. +The specified file must contain a JSON or YAML object that represents valid properties for the +resource. DSC validates the object against the resource's instance schema. If the validation fails, +or if the specified file doesn't exist, DSC raises an error. -This option is mutually exclusive with the `--input` option. When you use this option, DSC -ignores any input from stdin. +You can also use this option to pass an instance from stdin, as shown in [Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +- `json` to emit the data as a [JSON Line][04]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that includes the actual state of the instance before and after +This command returns a formatted data object that includes the actual state of the instance before and after the set operation, and the list of properties that the set operation modified. For more -information, see [dsc resource set result schema][04]. +information, see [dsc resource set result schema][05]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + +[zz]: https://jsonlines.org/ [01]: ../config/set.md [02]: ../config/set.md [03]: ../../schemas/resource/manifest/set.md#implementspretest -[04]: ../../schemas/outputs/resource/set.md +[04]: https://jsonlines.org/ +[05]: ../../schemas/outputs/resource/set.md diff --git a/docs/reference/cli/resource/test.md b/docs/reference/cli/resource/test.md index f659ff59..0ebdab60 100644 --- a/docs/reference/cli/resource/test.md +++ b/docs/reference/cli/resource/test.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource test' command -ms.date: 08/04/2023 +ms.date: 03/25/2025 ms.topic: reference title: dsc resource test --- @@ -9,26 +9,26 @@ title: dsc resource test ## Synopsis -Invokes the test operation of a resource. +Validates the actual state of a resource instance against a desired state. ## Syntax -### Instance properties from stdin +### Instance properties from input option ```sh - | dsc resource set [Options] --resource +dsc resource set --input --resource ``` -### Instance properties from input option +### Instance properties from file ```sh -dsc resource set --input '' --resource +dsc resource set --file --resource ``` -### Instance properties from file +### Instance properties from stdin ```sh -dsc resource set --path --resource +cat | dsc resource set [Options] --resource --file - ``` ## Description @@ -36,18 +36,16 @@ dsc resource set --path --resource The `test` subcommand validates the actual state of a resource instance against a desired state. This subcommand tests one instance of a specific DSC Resource. To test multiple resources, use a -resource group or the [dsc config test][01] command. +group resource, adapter resource, or the [dsc config test][01] command. -The desired state of the instance to test must be passed to this command as a JSON or YAML object. -The object properties must be valid properties for the resource. The instance properties can be -passed to this command from stdin, as a string with the `--input` option, or from a saved file with -the `--path` option. +The desired state of the instance to test must be passed to this command as a JSON or YAML object +with the `--input` or `--file` option. -If this command is invoked for a command-based DSC Resource that doesn't define its own test -operation, DSC performs a synthetic test. The synthetic test compares each property for the desired -state of an instance against the actual state. The synthetic test uses strict, case-sensitive -equivalence. If the desired state for a property and the actual state aren't the same, DSC marks -the property as out of the desired state. +If this command is invoked for a command resource that doesn't define its own test operation, DSC +performs a synthetic test. The synthetic test compares each property for the desired state of an +instance against the actual state. The synthetic test uses strict, case-sensitive equivalence. If +the desired state for a property and the actual state aren't the same, DSC marks the property as +out of the desired state. This command only validates instance properties under two conditions: @@ -58,20 +56,24 @@ This command only validates instance properties under two conditions: ### Example 1 - Testing a resource with properties from stdin + + The command tests whether the `Example` key exists in the current user hive. It specifies the -resource instance properties as JSON and passes them from stdin. +desired state for the resource instance as JSON and passes it from stdin. ```sh '{ "keyPath": "HKCU\\Example", "_exist": true -}' | dsc resource test --resource Microsoft.Windows/Registry +}' | dsc resource test --resource Microsoft.Windows/Registry --file - ``` ### Example 2 - Testing a resource with the input option + + The command tests whether the `Example` key exists in the current user hive. It specifies the -resource instance properties as JSON and passes them with the **input** option. +desired state for the resource instance as JSON and passes it with the `--input` option. ```sh dsc resource test --resource Microsoft.Windows/Registry --input '{ @@ -82,13 +84,13 @@ dsc resource test --resource Microsoft.Windows/Registry --input '{ ### Example 3 - Testing a resource with properties from a YAML file -The command tests whether the `Example` key exists in the current user hive. It specifies the -path to a YAML file defining the resource instance properties with the **path** option. + -```sh -``` +The command tests whether the `Example` key exists in the current user hive. It specifies the path +to a YAML file defining the desired state for the resource instance with the `--file` option. ```yaml +# example.yaml keyPath: HKCU\\Example _exist: true ``` @@ -101,6 +103,9 @@ dsc resource test --resource Microsoft.Windows/Registry --path ./example.yaml ### -r, --resource + + + Specifies the fully qualified type name of the DSC Resource to use, like `Microsoft.Windows/Registry`. @@ -111,69 +116,117 @@ The fully qualified type name syntax is: `[.][.]/`, wh - The `name` identifies the component the resource manages. ```yaml -Type: String -Mandatory: true +Type : string +Mandatory : true +LongSyntax : --resource +ShortSyntax : -r ``` ### -i, --input -Specifies a JSON or YAML object with the properties defining the desired state of a DSC Resource -instance. DSC validates the object against the resource's instance schema. If the validation fails, -DSC raises an error. + + + +Specifies the desired state of the resource instance to validate against the actual state. + +The instance must be a string containing a JSON or YAML object. DSC validates the object against +the resource's instance schema. If the validation fails, DSC raises an error. -This option can't be used with instance properties over stdin or the `--path` option. Choose -whether to pass the instance properties to the command over stdin, from a file with the `--path` -option, or with the `--input` option. +This option is mutually exclusive with the `--file` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --input +ShortSyntax : -i ``` -### -p, --path +### -f, --file -Defines the path to a text file to read as input for the command instead of piping input from stdin -or passing it as a string with the `--input` option. The specified file must contain JSON or YAML -that represents valid properties for the resource. DSC validates the object against the resource's -instance schema. If the validation fails, or if the specified file doesn't exist, DSC raises an -error. + + -This option is mutually exclusive with the `--input` option. When you use this option, DSC -ignores any input from stdin. +Defines the path to a file defining the desired state of the resource instance to validate against +the actual state. + +The specified file must contain a JSON or YAML object that represents valid properties for the +resource. DSC validates the object against the resource's instance schema. If the validation fails, +or if the specified file doesn't exist, DSC raises an error. + +You can also use this option to pass an instance from stdin, as shown in [Example 1](#example-1). + +This option is mutually exclusive with the `--input` option. ```yaml -Type: String -Mandatory: false +Type : string +Mandatory : false +LongSyntax : --file +ShortSyntax : -f ``` -### -f, --format +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][02]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` + + ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` ## Output -This command returns JSON output that includes the desired state of the instance, the actual state, -the list of properties that are out of the desired state, and a boolean value indicating whether -the instance is in the desired state. For more information, see -[dsc resource test result schema][02]. +This command returns a formatted data object that includes the desired state of the instance, the +actual state, the list of properties that are out of the desired state, and a boolean value +indicating whether the instance is in the desired state. For more information, see +[dsc resource test result schema][03]. + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + [01]: ../config/test.md -[02]: ../../schemas/outputs/resource/test.md +[02]: https://jsonlines.org/ +[03]: ../../schemas/outputs/resource/test.md diff --git a/docs/reference/cli/schema/command.md b/docs/reference/cli/schema/index.md similarity index 55% rename from docs/reference/cli/schema/command.md rename to docs/reference/cli/schema/index.md index d744dbb9..ed79f8c0 100644 --- a/docs/reference/cli/schema/command.md +++ b/docs/reference/cli/schema/index.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc schema' command -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: dsc schema --- @@ -34,10 +34,10 @@ output for one of the application's commands. > > Both the published schemas and those returned from this command correctly validate the data. The > schemas returned from this command are less strict than the published schemas. Even though data -> validates against the schemas returned by this command, DSC may raise errors when processing the -> data. For example, the returned schema for versions indicates that the valid value is a string - -> but if you specify a string that isn't a semantic version, DSC raises an error. In that case, the -> data passed the schema validation but was incorrect. +> validates against the schemas returned by this command, DSC might raise errors when processing +> the data. For example, the returned schema for versions indicates that the valid value is a +> string - but if you specify a string that isn't a semantic version, DSC raises an error. In that +> case, the data passed the schema validation but was incorrect. > > Until the schemas are canonicalized, consider using the published schemas when indpendently > testing your configuration documents and resource manifests with a JSON Schema validation tool. @@ -46,6 +46,8 @@ output for one of the application's commands. ### Example 1 - Retrieve the schema for the dsc resource get command result + + ```sh dsc schema --type get-result ``` @@ -170,72 +172,122 @@ definitions: ### -t, --type + + + This option is mandatory for the `schema` command. The value for this option determines which schema the application returns: -- `dsc-resource` ([reference documentation][01]) - Represents a DSC Resource as returned from the - `dsc resource list` command. -- `resource-manifest` ([reference documentation][02]) - Validates a command-based DSC Resource's - manifest. If the manifest is invalid, DSC raises an error. -- `get-result` ([reference documentation][03]) - Represents the output from the `dsc resource get` - command. -- `set-result` ([reference documentation][04]) - Represents the output from the `dsc resource set` - command. -- `test-result` ([reference documentation][05]) - Represents the output from the - `dsc resource test` command. -- `configuration` ([reference documentation][06]) - Validates a DSC Configuration document. If the +- `configuration` ([reference documentation][01]) - Validates a DSC Configuration document. If the document is invalid, DSC raises an error. -- `configuration-get-result` ([reference documentation][07]) - Represents the output from the +- `dsc-resource` ([reference documentation][02]) - Represents a DSC Resource as returned from the + `dsc resource list` command. +- `resource-manifest` ([reference documentation][03]) - Validates a command resource's manifest. If + the manifest is invalid, DSC raises an error. +- `include` - represents the instance schema for the + built-in `Microsoft.DSC/Include` importer resource. +- `configuration-get-result` ([reference documentation][05]) - Represents the output from the `dsc config get` command. -- `configuration-set-result` ([reference documentation][08]) - Represents the output from the +- `configuration-set-result` ([reference documentation][06]) - Represents the output from the `dsc config set` command. -- `configuration-test-result` ([reference documentation][09]) - Represents the output from the +- `configuration-test-result` ([reference documentation][07]) - Represents the output from the `dsc config test` command. +- `get-result` ([reference documentation][08]) - Represents the output from the `dsc resource get` + command. +- `resolve-result` - Represents the resolved form of the + configuration document an `importer` resource emits. +- `set-result` ([reference documentation][10]) - Represents the output from the `dsc resource set` + command. +- `test-result` ([reference documentation][11]) - Represents the output from the + `dsc resource test` command. ```yaml -Type: String +Type: string Mandatory: true ValidValues: [ - dsc-resource, - resource-manifest, - get-result, - set-result, - test-result, - configuration, - configuration-get-result, - configuration-set-result, + configuration + dsc-resource + resource-manifest + include + configuration-get-result + configuration-set-result configuration-test-result + get-result + resolve-result + set-result + test-result ] +LongSyntax : --type +ShortSyntax : -t ``` -### -f, --format +### -o, --output-format -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][12]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format + in the console. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output include terminal sequences +for formatting. ```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] +Type : string +Mandatory : false +ValidValues : [json, pretty-json, yaml] +LongSyntax : --output-format +ShortSyntax : -o ``` ### -h, --help + + + Displays the help for the current command or subcommand. When you specify this option, the -application ignores all options and arguments after this one. +application ignores all other options and arguments. ```yaml -Type: Boolean -Mandatory: false +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h ``` -[01]: ../../schemas/outputs/resource/list.md -[02]: ../../schemas/resource/manifest/root.md -[03]: ../../schemas/outputs/resource/get.md -[04]: ../../schemas/outputs/resource/set.md -[05]: ../../schemas/outputs/resource/test.md -[06]: ../../schemas/config/document.md -[07]: ../../schemas/outputs/config/get.md -[08]: ../../schemas/outputs/config/set.md -[09]: ../../schemas/outputs/config/test.md +## Output + +This command returns formatted data representing a JSON Schema specified by the +[--type option](#--type). + +For more information about the formatting of the output data, see the +[--output-format option](#--output-format). + +[01]: ../../schemas/config/document.md +[02]: ../../schemas/outputs/resource/list.md +[03]: ../../schemas/resource/manifest/root.md +[04]: ../../../reference/resources/microsoft/dsc/include/index.md +[05]: ../../schemas/outputs/config/get.md +[06]: ../../schemas/outputs/config/set.md +[07]: ../../schemas/outputs/config/test.md +[08]: ../../schemas/outputs/resource/get.md +[09]: ../../schemas/resource/stdout/resolve +[10]: ../../schemas/outputs/resource/set.md +[11]: ../../schemas/outputs/resource/test.md +[12]: https://jsonlines.org/ diff --git a/docs/reference/resources/Microsoft/DSC/Assertion/index.md b/docs/reference/resources/Microsoft/DSC/Assertion/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/Group/index.md b/docs/reference/resources/Microsoft/DSC/Group/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/Include/index.md b/docs/reference/resources/Microsoft/DSC/Include/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/examples/configure-a-machine.md b/docs/reference/resources/Microsoft/DSC/PowerShell/examples/configure-a-machine.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/examples/discovering-powershell-resources.md b/docs/reference/resources/Microsoft/DSC/PowerShell/examples/discovering-powershell-resources.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/examples/invoke-a-resource.md b/docs/reference/resources/Microsoft/DSC/PowerShell/examples/invoke-a-resource.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/index.md b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md new file mode 100644 index 00000000..db56a0d2 --- /dev/null +++ b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md @@ -0,0 +1,205 @@ +--- +description: Microsoft.DSC/PowerShell resource reference documentation +ms.date: 03/18/2025 +ms.topic: reference +title: Microsoft/OSInfo +--- + +# Microsoft.DSC/PowerShell + +## Synopsis + +Adapter for resources implemented as PowerShell classes + +## Metadata + +```yaml +Version: 0.1.0 +Kind: adapter +Tags: [linux, windows, macos, pwsh, powershell] +Executable: powershell.resource.ps1 +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.DSC/PowerShell + properties: + # Required Properties + resources: + - name: + type: / + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.DSC/PowerShell` adapter resource enables you to use PowerShell Desired State +Configuration (PSDSC) resources in DSC. The adapter is able to discover and invoke PSDSC resources +implemented as PowerShell classes. + +The adapter manages the PSDSC resources in PowerShell, not Windows PowerShell. To use MOF-based +PSDSC resources or PSDSC resources that require Windows PowerShell, use the +[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/resource.md) adapter. + +This adapter doesn't use the **PSDesiredStateConfiguration** module. You don't need to install the +**PSDesiredStateConfiguration** module to use PSDSC resources in DSC through this adapter. + +### PowerShell resource adapter cache + +The process for discovering the PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches PowerShell resources and modules during +discovery. If the cache doesn't exist during discovery, the adapter creates it. + +The location of the cache depends on your operating system. The following table defines the path +for each platform. + +| Platform | Path | +| :------: | :----------------------------------------| +| Linux | `$HOME/.dsc/PSAdapterCache.json` | +| macOS | `$HOME/.dsc/PSAdapterCache.json` | +| Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | + +The adapter versions the cache. The current version is `1`. If the version of the cache on a +machine differs from the current version, the adapter refreshes the cache. + +The adapter checks whether the cache is stale on each run and refreshes it if: + +- The `PSModulePath` environmental variable is updated. +- Any module is added or removed from the `PSModulePath`. +- Any related file in a cached PSDSC resource module has been updated since the cache was written. + The adapter watches the `LastWriteTime` property of module files with the following extensions: + `.ps1`, `.psd1`, and `.psm1`. + +You can directly call the adapter script to clear the cache with the **Operation** parameter value +set to `ClearCache`: + +```powershell +$adapterScript = dsc resource list Microsoft.DSC/PowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path + +& $adapterScript -Operation CLearCache +``` + +## Requirements + +- Using this adapter requires a supported version of PowerShell. DSC invokes the adapter as a + PowerShell script. For more information about installing PowerShell, see + [Install PowerShell on Windows, Linux, and macOS](/powershell/scripting/install/installing-powershell). + +## Examples + +- [Invoke a resource with the PowerShell adapter][02] +- [Configure a machine with the PowerShell adapter][03] + +## Required properties + +The following properties are required. + +### resources + +The `resources` property defines a list of adapted PSDSC resource instances that the adapter manages. +Every instance in the list must be unique, but instances may share the same DSC resource type. + +For more information about defining a valid adapted resource instance, see the +[Adapted resource instances](#adapted-resource-instances) section of this document. + +```yaml +Type: array +Required: true +MinimumItemCount: 1 +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json +``` + +## Adapted resource instances + +Adapted resources instances always adhere to the +[DSC Configuration document resource instance schema](../../../../schemas/config/resource.md). + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-name), and [properties](#adapted-instance-properties) for the instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property should be unique within the adapter's `resources` array. + +> ![NOTE] +> The adapter doesn't currently raise an error when you define two adapted instances with the same +> name. In a future release, the adapter will be updated to emit a warning when adapted instances +> share the same name. In the next major version of the adapter, name conflicts will raise an +> error. +> +> Using the same name for multiple instances can make debugging and reviewing output more +> difficult. Always use unique names for every instance. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's PSDSC Resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a PSDSC +resource implemented as a PowerShell class: + +```Syntax +/ +``` + +For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. The specified properties are validated at runtime when the adapter +tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting +for adapted instance properties in a configuration document. + +Each name for each property must be a configurable property of the PSDSC resource. The property +name isn't case sensitive. The value for each property must be valid for that property. If you +specify an invalid property name or value, the adapter raises an error when it tries to invoke the +resource. + +```yaml +Type: object +Required: true +``` + +## Exit Codes + +The resource uses the following exit codes to report success and errors: + +- `0` - Success +- `1` - Error + +## See also + +- [Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/resource.md) + + +[01]: ../../../concepts/resources.md#test-operations +[02]: examples/validate-with-dsc-resource.md +[03]: examples/validate-in-a-configuration.md +[04]: cli/osinfo.md diff --git a/docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/index.md b/docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml new file mode 100644 index 00000000..4ab82496 --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Operating System Assertion + type: Microsoft.DSC/Assertion + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Is64BitOS + type: Microsoft/OSInfo + properties: + bitness: '32' diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration.md b/docs/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration.md new file mode 100644 index 00000000..e696911f --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration.md @@ -0,0 +1,625 @@ +--- +description: > + Use the Microsoft/OSInfo resource to Use the Microsoft/OSInfo resource to validate operating + system in a DSC Configuration Document. +ms.date: 03/25/2025 +ms.topic: reference +title: Validate operating system information in a configuration +--- + +# Validate operating system information in a configuration + +This example shows how you can use the `Microsoft/OSInfo` resource to assert that a configuration +document applies to a specific operating system. + +> [!IMPORTANT] +> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with +> DSC. Don't use it in production. + +## Definition + +The configuration document for this example defines a group resource instance called +`Operating System Assertion` with a nested instance of the `Microsoft/OSInfo` resource. + +The configuration uses the `Microsoft.DSC/Assertion` group resource to ensure that the **Test** +operation is called for every instance in the group, regardless of the actual configuration +operation being applied. When DSC processes the group resource, it calls the **Test** operation for +the nested instances instead of the **Get** or **Set** operations. Instances in the group never +change the state of the system. + +The instance of the `Microsoft/OSInfo` resource defines the `bitness` property to validate that the +configuration is applied on a 64-bit operating system. + +:::code language="yaml" source="osinfo.config.dsc.yaml"::: + +## Getting the current state + +To get the current state of the instances in the configuration document, use the +[dsc config get][01] command with the [--file][02] option. + +# [Linux](#tab/linux) + +```bash +dsc config get --file ./osinfo.config.dsc.yaml +``` + +# [macOS](#tab/macos) + +```zsh +dsc config get --file ./osinfo.config.dsc.yaml +``` + +# [Windows](#tab/windows) + +```powershell +dsc config get --file .\osinfo.config.dsc.yaml +``` + +--- + +The output depends on whether the operating system is 32-bit or 64-bit. + +# [32-bit Linux](#tab/32bit/linux) + +For a 32-bit Linux operating system, the get result shows that the `Is64BitOS` instance is +out of the desired state because the `bitness` property is `32`. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '32' + architecture: i386 +messages: [] +hadErrors: false +``` + +# [64-bit Linux](#tab/64bit/linux) + +For a 64-bit Linux operating system, the get result shows that the `Is64BitOS` instance is +in the desired state. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: x86_64 +messages: [] +hadErrors: false +``` + +# [32-bit macOS](#tab/32bit/macos) + +For a 32-bit macOS operating system, the get result shows that the `Is64BitOS` instance is +out of the desired state because the `bitness` property is `32`. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '32' + architecture: arm +messages: [] +hadErrors: false +``` + +# [64-bit macOS](#tab/64bit/macos) + +For a 64-bit macOS operating system, the get result shows that the `Is64BitOS` instance is +in the desired state. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 +messages: [] +hadErrors: false +``` + +# [32-bit Windows](#tab/32bit/windows) + +For a 32-bit Windows operating system, the get result shows that the `Is64BitOS` instance is +out of the desired state because the `bitness` property is `32`. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '32' +messages: [] +hadErrors: false +``` + +# [64-bit Windows](#tab/64bit/windows) + +For a 64-bit Windows operating system, the get result shows that the `Is64BitOS` instance is +in the desired state. + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: get + executionType: actual + startDatetime: 2025-03-07T13:32:15.787101400-06:00 + endDatetime: 2025-03-07T13:32:19.077737200-06:00 + duration: PT3.2906358S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.5803652S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '64' +messages: [] +hadErrors: false +``` + +--- + +## Verify the desired state + +DSC can use the resource to validate the operating system information in a configuration with the [dsc config test][03] command. When you use the `dsc config test` command, DSC invokes the **Test** operation against every resource in the configuration document. + +The `Microsoft/OSInfo` resource doesn't implement the [test operation][04]. It relies on the +synthetic testing feature of DSC instead. The synthetic test uses a case-sensitive equivalency +comparison between the actual state of the instance properties and the desired state. If any +property value isn't an exact match, DSC considers the instance to be out of the desired state. + +# [Linux](#tab/linux) + +```bash +dsc config set --file ./osinfo.config.dsc.yaml +``` + +# [macOS](#tab/macos) + +```zsh +dsc config set --file ./osinfo.config.dsc.yaml +``` + +# [Windows](#tab/windows) + +```powershell +dsc config set --file .\osinfo.config.dsc.yaml +``` + +--- + +The output depends on whether the operating system is 32-bit or 64-bit. In all cases, the +`changedProperties` field for the result is an empty list. The `Microsoft.DSC/Assertion` group resource +never changes system state and the `Microsoft/OSInfo` resource doesn't implement the **Set**** operation. + +# [32-bit Linux](#tab/32bit/linux) + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-07T13:40:50.014780900-06:00 + endDatetime: 2025-03-07T13:40:54.009892500-06:00 + duration: PT3.9951116S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT3.2687015S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '32' + architecture: i386 + afterState: + - metadata: + Microsoft.DSC: + duration: PT0.0439438S + name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '32' + architecture: i386 + inDesiredState: false + differingProperties: + - bitness + changedProperties: [] +messages: [] +hadErrors: false + +``` + +# [64-bit Linux](#tab/64bit/linux) + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-07T13:39:27.847812500-06:00 + endDatetime: 2025-03-07T13:39:32.089234100-06:00 + duration: PT4.2414216S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT3.498287S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: i386 + afterState: + - metadata: + Microsoft.DSC: + duration: PT0.0500784S + name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: i386 + inDesiredState: false + differingProperties: [] + changedProperties: [] +messages: [] +hadErrors: false +``` + +# [32-bit macOS](#tab/32bit/macos) + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-07T13:40:50.014780900-06:00 + endDatetime: 2025-03-07T13:40:54.009892500-06:00 + duration: PT3.9951116S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT3.2687015S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '32' + architecture: arm + afterState: + - metadata: + Microsoft.DSC: + duration: PT0.0439438S + name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '32' + architecture: arm + inDesiredState: false + differingProperties: + - bitness + changedProperties: [] +messages: [] +hadErrors: false +``` + +# [64-bit macOS](#tab/64bit/macos) + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-07T13:39:27.847812500-06:00 + endDatetime: 2025-03-07T13:39:32.089234100-06:00 + duration: PT4.2414216S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT3.498287S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 + afterState: + - metadata: + Microsoft.DSC: + duration: PT0.0500784S + name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 + inDesiredState: false + differingProperties: [] + changedProperties: [] +messages: [] +hadErrors: false +``` + +# [32-bit Windows](#tab/32bit/windows) + +```yaml +results: +- name: Operating System Assertion + type: DSC/AssertionGroup + result: + beforeState: + results: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '32' + inDesiredState: false + differingProperties: + - bitness + messages: [] + hadErrors: false + afterState: + results: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '32' + inDesiredState: false + differingProperties: + - bitness + messages: [] + hadErrors: false + changedProperties: [] +messages: [] +hadErrors: false +``` + +# [64-bit Windows](#tab/64bit/windows) + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-07T13:39:27.847812500-06:00 + endDatetime: 2025-03-07T13:39:32.089234100-06:00 + duration: PT4.2414216S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT3.498287S + name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Is64BitOS + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '64' + afterState: + - metadata: + Microsoft.DSC: + duration: PT0.0500784S + name: Is64BitOS + type: Microsoft/OSInfo + result: + desiredState: + bitness: '64' + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '64' + inDesiredState: false + differingProperties: [] + changedProperties: [] +messages: [] +hadErrors: false +``` + +--- + + +[01]: ../../../../cli/config/get.md +[02]: ../../../../cli/config/get.md#--file +[03]: ../../../../cli/config/test.md +[04]: ../../../../../concepts/resources/operations.md#test-operation diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md new file mode 100644 index 00000000..b229a311 --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md @@ -0,0 +1,245 @@ +--- +description: > + Validate operating system information with the Microsoft/OSInfo DSC Resource + and the dsc resource commands. +ms.date: 03/25/2025 +ms.topic: reference +title: Validate operating system information with dsc resource +--- + +# Validate operating system information with dsc resource + +## Description + +This example shows how you can use the `Microsoft/OSInfo` DSC Resource to retrieve and validate +information about an operating system with the `dsc resource` commands. + +> [!IMPORTANT] +> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with +> DSC. Don't use it in production. + +## Getting the operating system information + +The [dsc resource get][01] command returns an instance of the resource. The `Microsoft/OSInfo` +resource doesn't require any instance properties to return the instance. The resource returns the +available information for the operating system. + +# [Linux](#tab/linux) + +```bash +dsc resource get -r Microsoft/OSInfo +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: x86_64 +``` + +# [macOS](#tab/macos) + +```zsh +resource=$(dsc resource list Microsoft/OSInfo) +dsc resource get -r Microsoft/OSInfo +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 +``` + +# [Windows](#tab/windows) + +```powershell +dsc resource get --resource Microsoft/OSInfo +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '64' +``` + +--- + +## Testing the operating system information + +DSC can use the resource to validate the operating system information. When you use the +[dsc resource test][02] command, input JSON representing the desired state of the instance is +required. The JSON must define at least one instance property to validate. + +The resource doesn't implement the [test operation][03]. It relies on the synthetic testing feature +of DSC instead. The synthetic test uses a case-sensitive equivalency comparison between the actual +state of the instance properties and the desired state. If any property value isn't an exact match, +DSC considers the instance to be out of the desired state. + +# [Linux](#tab/linux) + +This test checks whether the `family` property for the instance is `Linux`. It passes the desired +state for the instance to the command from stdin with the `--file` (`-f`) option. + +```bash +invalid_instance='{"family": "Linux"}' +echo $invalid_instance | dsc resource test -r "${resource}" -f - +``` + +```yaml +desiredState: + family: linux +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: x86_64 +inDesiredState: false +differingProperties: +- family +``` + +The result shows that the resource is out of the desired state because the actual state of the +`family` property wasn't case-sensitively equal to the desired state. + +The next test validates that the operating system is a 64-bit Linux operating system. It passes +the desired state for the instance to the command with the `--input` (`-i`) option. + +```bash +valid_instance='{ "family": "Linux", "bitness": "64" }' +echo $valid_instance | dsc resource test -r Microsoft/OSInfo -i $valid_instance +``` + +```yaml +desiredState: + family: Linux + bitness: '64' +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Linux + version: '20.04' + codename: focal + bitness: '64' + architecture: x86_64 +inDesiredState: true +differingProperties: [] +``` + +# [macOS](#tab/macos) + +This test checks whether the `family` property for the instance is `macOS`. It passes the desired +state for the instance to the command from stdin with the `--file` (`-f`) option. + +```zsh +invalid_instance='{"family": "macOS"}' +echo $invalid_instance | dsc resource test -r Microsoft/OSInfo -f - +``` + +```yaml +desiredState: + family: macOS +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 +inDesiredState: false +differingProperties: +- family +``` + +The result shows that the resource is out of the desired state because the actual state of the +`family` property wasn't case-sensitively equal to the desired state. + +The next test validates that the operating system is a 64-bit macOS operating system. It passes the +desired state for the instance to the command with the `--input` (`-i`) option. + +```zsh +valid_instance='{ "family": "MacOS", "bitness": "64" }' +dsc resource test -r Microsoft/OSInfo -i $valid_instance +``` + +```yaml +desiredState: + family: MacOS + bitness: '64' +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: MacOS + version: 13.5.0 + bitness: '64' + architecture: arm64 +inDesiredState: true +differingProperties: [] +``` + +# [Windows](#tab/windows) + +This test checks whether the `family` property for the instance is `windows`. It passes the desired +state for the instance to the command from stdin with the `--file` (`-f`) option. + +```powershell +$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON +$invalidInstance | dsc resource test --resource Microsoft/OSInfo --file - +``` + +```yaml +desiredState: + family: windows +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: "64" +inDesiredState: false +differingProperties: +- family +``` + +The result shows that the resource is out of the desired state because the actual state of the +`family` property wasn't case-sensitively equal to the desired state. + +The next test validates that the operating system is a 64-bit Windows operating system. It passes +the desired state for the instance to the command with the `--input` (`-i`) option. + +```powershell +$validInstance = @{ + family = 'Windows' + bitness = '64' +} | ConvertTo-JSON + +dsc resource test --resource Microsoft/OSInfo --input $validInstance +``` + +```yaml +desiredState: + family: Windows + bitness: '64' +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: "64" +inDesiredState: true +differingProperties: [] +``` + +--- + + +[01]: ../../../../cli/resource/get.md +[02]: ../../../../cli/resource/test.md +[03]: ../../../../../concepts/resources/overview.md#test-operations diff --git a/docs/reference/resources/Microsoft/OSInfo/index.md b/docs/reference/resources/Microsoft/OSInfo/index.md new file mode 100644 index 00000000..9e72cd48 --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/index.md @@ -0,0 +1,258 @@ +--- +description: Microsoft/OSInfo DSC resource reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft/OSInfo +--- + +# Microsoft/OSInfo + +## Synopsis + +Returns information about the operating system. + +> [!IMPORTANT] +> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with +> DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [os, linux, windows, macos] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft/OSInfo + properties: + # Instance Properties + architecture: + bitness: + codename: + edition: + family: + version: +``` + +## Description + +The `Microsoft/OSInfo` resource enables you to assert whether a machine meets criteria related to +the operating system. The resource is only capable of assertions. It doesn't implement the set +operation and can't configure the operating system. + +The resource doesn't implement the [test operation][01]. It relies on the synthetic testing feature +of DSC instead. The synthetic test uses a case-sensitive equivalency comparison between the actual +state of the instance properties and the desired state. If any property value isn't an exact match, +DSC considers the instance to be out of the desired state. + +The instance properties returned by this resource depend on the operating system `family` as +listed in the following table: + +| `family` | Returned instance properties | +| :-------: | :--------------------------------------------------------- | +| `Linux` | `architecture`, `bitness`, `codename`, `family`, `version` | +| `MacOS` | `architecture`, `bitness`, `family`, `version` | +| `Windows` | `bitness`, `edition`, `family`, `version` | + +> [!NOTE] +> This resource is installed with DSC itself on all platforms. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +None. + +## Capabilities + +This resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of an instance. +- `export` - You can use the resource to retrieve the actual state of every instance. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is +in the desired state. + +This resource doesn't have the `set` capability. You can't use it to modify the state of a system. + +For more information about resource capabilities, see +[DSC resource capabilities][02]. + +## Examples + +1. [Validate operating system information with dsc resource][03] +1. [Validate operating system information in a configuration][04] + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** This resource doesn't have any required + properties. +- **Key properties:** This resource doesn't have any key properties. +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [architecture](#architecture) - Defines the processor architecture on Linux and macOS systems. + - [bitness](#bitness) - Defines whether the operating system is 32-bit or 64-bit. + - [codename](#codename) - Defines the codename for Linux systems. + - [edition](#edition) - Defines the edition for Windows systems. + - [family](#family) - Defines whether the system is Linux, macOS, or Windows. + - [version](#version) - Defines the version of the operating system. +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][05]. + + - [$id](#id) - Returns the unique ID for the OSInfo instance data type. + +### architecture + +
Expand for architecture property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the processor architecture as reported by `uname -m` on the operating system. The resource +doesn't return this property for Windows machines. + +### bitness + +
Expand for bitness property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +ValidValues : ['32', '64', unknown] +``` + +
+ +Defines whether the operating system is a 32-bit or 64-bit operating system. When the resource +can't determine this information, it returns a value of `unknown`. + +### codename + +
Expand for codename property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the codename for the operating system as returned from `lsb_release --codename`. The +resource only returns this property for Linux machines. + +### edition + +
Expand for edition property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the operating system edition, like `Windows 11` or `Windows Server 2016`. The resource only +returns this property for Windows machines. + +### family + +
Expand for family property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +ValidValues : [Linux, macOS, Windows] +``` + +
+ +### version + +
Expand for version property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the version of the operating system as a string. + +### $id + +
Expand for $id property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +ConstantValue : https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json +``` + +
+ +Returns the unique ID for the OSInfo instance data type. + +## Exit Codes + +The resource uses the following exit codes to report success and errors: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed. Review the error message for more information about the +operation failure. + +## See also + +- [Command line reference for the osinfo command][06] + + +[01]: ../../../../concepts/resources/overview.md#test-operations +[02]: ../../../../concepts/resources/capabilities.md +[03]: examples/validate-with-dsc-resource.md +[04]: examples/validate-in-a-configuration.md +[05]: ../../../../concepts/resources/properties.md#read-only-resource-properties +[06]: ../../../tools/osinfo.md diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md b/docs/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md new file mode 100644 index 00000000..29152200 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md @@ -0,0 +1,240 @@ +--- +description: > + Examples showing how you can use the Microsoft.Windows/Registry resource to manage registry keys + and values in a DSC configuration document. +ms.date: 03/25/2025 +ms.topic: reference +title: Configure registry keys and values +--- + +# Configure registry keys and values + +This example shows how you can use the `Microsoft.Windows/Registry` resource to manage registry +keys and values. + +## Definition + +The configuration document for this example defines two instances of the `Registry` resource. + +The first instance defines the desired state for the `ManagedKey` registry key, ensuring it +exists. The second instance defines the desired state for the `ManagedValue` registry value, +ensuring it exists and has the string data `Default`. + +:::code language="yaml" source="registry.config.dsc.yaml"::: + +Copy the configuration document and save it as `registry.config.dsc.yaml`. + +## Test the configuration + +To see whether the system is in the desired state, use the [dsc config test][01] command on the +configuration document. + +```powershell +dsc config test --file ./registry.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: test + executionType: actual + startDatetime: 2025-03-12T11:51:24.606655-05:00 + endDatetime: 2025-03-12T11:51:25.994942800-05:00 + duration: PT1.3882878S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.2552945S + name: Managed key + type: Microsoft.Windows/Registry + result: + desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + inDesiredState: false + differingProperties: + - _exist +- metadata: + Microsoft.DSC: + duration: PT0.0605464S + name: Managed value + type: Microsoft.Windows/Registry + result: + desiredState: + _exist: true + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default + actualState: + keyPath: HKCU\DscExamples + _exist: false + inDesiredState: false + differingProperties: + - _exist + - valueName + - valueData +messages: [] +hadErrors: false +``` + +Review the individual results to understand whether each instance is in the desired state. + +The result for the first instance, named `Managed key`, was: + +```yaml +desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey +actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +The output indicates that the registry key doesn't exist. When you use the **Set** operation on +this configuration, the resource will create the registry key. + +The result for the second instance, named `Managed value`, was: + +```yaml +desiredState: + _exist: true + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +actualState: + keyPath: HKCU\DscExamples + _exist: false +inDesiredState: false +differingProperties: +- _exist +- valueName +- valueData +``` + +The actual state for the instance reports that `_exist` is `false` and doesn't include the +`valueName` property. For the `Registry` resource, this result indicates that the registry key +itself doesn't exist. In this case, the `Registry` resource is reporting that the `DscExamples` +registry key in the current user hive doesn't exist. When the key exists but the value doesn't, the +actual state includes the `valueName` property. + +Together, the results show that none of the instances in the configuration are in the desired +state. + +## Enforce the configuration + +To update the system to the desired state, use the [dsc config set][02] command on the +configuration document. + +```powershell +dsc config set --file ./registry.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-03-12T11:59:40.172845800-05:00 + endDatetime: 2025-03-12T11:59:42.127979800-05:00 + duration: PT1.955134S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.6354747S + name: Managed key + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + afterState: + keyPath: HKCU\DscExamples\ManagedKey + changedProperties: + - _exist +- metadata: + Microsoft.DSC: + duration: PT0.2081512S + name: Managed value + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + _exist: false + afterState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default + changedProperties: + - valueData + - _exist +messages: [] +hadErrors: false +``` + +Review the individual results to understand how the resource modified the system to enforce the +desired state for each instance. + +The result for the first instance, named `Managed key`, was: + +```yaml +beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +afterState: + keyPath: HKCU\DscExamples\ManagedKey +changedProperties: +- _exist +``` + +The output indicates that the resource created the registry key. + +The result for the second instance, named `Managed value`, was: + +```yaml +beforeState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + _exist: false +afterState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +changedProperties: +- valueData +- _exist +``` + +The output indicates that the resource created the registry value with the specified data. + +## Cleanup + +To return your system to its original state: + +1. Save the following configuration as `registry.cleanup.config.dsc.yaml`. + + :::code language="yaml" source="registry.cleanup.config.dsc.yaml"::: + +2. Use the **Set** operation on the cleanup configuration document. + + ```powershell + dsc config set --file ./registry.cleanup.config.dsc.yaml + ``` + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md b/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md new file mode 100644 index 00000000..9ef43862 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md @@ -0,0 +1,137 @@ +--- +description: > + Examples showing how you can invoke the Microsoft.Windows/Registry with DSC to create and delete + a registry key. + +ms.date: 03/25/2025 +ms.topic: reference +title: Manage a registry key +--- + +# Manage a registry key + +This example shows how you can use the `Microsoft.Windows/Registry` resource to manage whether a +registry key exists. These examples manage the `DscExamples\ManagedKey` registry key in the current +user hive. + +## Test whether a key exists + +The following snippet shows how you can use the resource with the [dsc resource test][01] command +to check whether the `ManagedKey` registry key exists. + +```powershell +$instance = @{ + _exist = $true + keyPath = 'HKCU\DscExamples\ManagedKey' +} | ConvertTo-Json + +dsc resource test --resource Microsoft.Windows/Registry --input $instance +``` + +When the registry key doesn't exist, DSC returns the following result: + +```yaml +desiredState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: true +actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +The `inDesiredState` field of the result object is set to `false`, indicating that the +instance isn't in the desired state. The `differingProperties` field indicates that the +`_exist` property is mismatched between the desired state and actual state. + +Because the resource uses the [_exist canonical resource property][02], we know that: + +- This result indicates that the +registry key doesn't exist on the system. +- The resource will create the instance during a **Set** operation. + +## Ensure a registry key exists + +To set the system to the desired state and create the registry key, use the [dsc resource set][03] +command. + +```powershell +dsc resource set --resource Microsoft.Windows/Registry --input $instance +``` + +When the resource creates the key, DSC returns the following result: + +```yaml +beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +afterState: + keyPath: HKCU\DscExamples\ManagedKey +changedProperties: +- _exist +``` + +You can test the instance again to confirm that the key exists: + +```powershell +dsc resource test --resource Microsoft.Windows/Registry --input $instance +``` + +```yaml +desiredState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: true +actualState: + keyPath: HKCU\DscExamples\ManagedKey +inDesiredState: true +differingProperties: [] +``` + +## Remove a key + +The following snippet shows how you can use the [dsc resource delete][04] command to remove the +registry key. + +```powershell +dsc resource delete --resource Microsoft.Windows/Registry --input $instance +``` + +The `dsc resource delete` command doesn't return any output. To verify the registry key no +longer exists, use the `dsc resource get` command. + +```powershell +dsc resource get --resource Microsoft.Windows/Registry --input $instance +``` + +```yaml +actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +``` + +> [!NOTE] +> Although this example used the **Delete** operation to remove the registry key instance, you can +> also use the **Set** operation. +> +> Because the resource uses the `_exist` canonical property, has the `delete` capability, and +> doesn't have the `setHandlesExist` capability, DSC knows to call the **Delete** operation for the +> resource when an instance defines `_exist` as `false`. + +## Cleanup + +To return your system to its original state, use the following snippet to remove the `DscExamples` +registry key and any remaining subkeys or values. + +```powershell +dsc resource delete --resource Microsoft.Windows/Registry --input @' +keyPath: HKCU\DscExamples +'@ +``` + + +[01]: ../../../../../cli/resource/test.md +[02]: ../../../../../schemas/resource/properties/exist.md +[03]: ../../../../../cli/resource/set.md +[04]: ../../../../../cli/resource/delete.md diff --git a/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md b/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md new file mode 100644 index 00000000..da9a4de2 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md @@ -0,0 +1,287 @@ +--- +description: > + Examples showing how you can invoke the Microsoft.Windows/Registry resource with DSC to create, modify, and delete + a registry key value. + +ms.date: 03/25/2025 +ms.topic: reference +title: Manage a registry value +--- + +# Manage a registry value + +This example shows how you can use the `Microsoft.Windows/Registry` resource to manage whether a +registry value exists and its data. These examples manage the `ManagedValue` registry value for the +`DscExamples` registry key in the current user hive. + +## Test whether a value exists + +The following snippet shows how you can use the resource with the [dsc resource test][01] command +to check whether the `ManagedValue` registry value exists. + +```powershell +$instance = @{ + _exist = $true + keyPath = 'HKCU\DscExamples' + valueName = 'ManagedValue' +} +$instanceJson = $instance | ConvertTo-Json + +dsc resource test --resource Microsoft.Windows/Registry --input $instanceJson +``` + +When the registry key doesn't exist, DSC returns the following result: + +```yaml +desiredState: + _exist: true + valueName: ManagedValue + keyPath: HKCU\DscExamples +actualState: + keyPath: HKCU\DscExamples + _exist: false +inDesiredState: false +differingProperties: +- _exist +- valueName +``` + +The `inDesiredState` field of the result object is set to `false`, indicating that the +instance isn't in the desired state. The `differingProperties` field indicates that the +`_exist` property is mismatched between the desired state and actual state. + +In this case, the `valueName` property isn't returned from the resource. When the actual state of a +`Registry` resource instance doesn't specify the `valueName` property and `_exist` is false, it +indicates that the _key_ doesn't exist. + +Because the resource uses the [_exist canonical resource property][02], we know that: + +- This result indicates that the +registry key doesn't exist on the system. +- The resource will create the instance during a **Set** operation. + +To show the difference, first use the following snippet to create the registry key with the +[dsc resource set][03] command. + +```powershell +dsc resource set --resource Microsoft.Windows/Registry --input @' +keyPath: HKCU\DscExamples +_exist: true +'@ +``` + +Then test the instance again: + +```powershell +dsc resource test --resource Microsoft.Windows/Registry --input $instanceJson +``` + +```yaml +desiredState: + _exist: true + valueName: ManagedValue + keyPath: HKCU\DscExamples +actualState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +Now that the `DscExamples` registry key exists, the `valueName` property is included in the actual +state and `_exist` is defined as `false` - the key exists but the value doesn't. + +## Ensure a registry value exists + +In the previous section, the desired state of the instance tested for whether the `ManagedValue` +registry value existed. However, the Registry API requires _creating_ a registry value to define +data for the value. Before you can use the **Set** operation to create the value, the desired state +must define the `valueData` property. + +The following snippet defines the data for the registry value as the string `Default` and updates +the `$instanceJson` variable to represent the updated desired state. + +```powershell +$instance.valueData = @{ String = 'Default' } +$instance | ConvertTo-Json -OutVariable instanceJson +``` + +```json +{ + "_exist": true, + "valueName": "ManagedValue", + "valueData": { + "String": "Default" + }, + "keyPath": "HKCU\\DSC\\Examples" +} +``` + +Next, invoke the **Set** operation for the instance. + +```powershell +dsc resource set --resource Microsoft.Windows/Registry --input $instanceJson +``` + +When the resource creates the value, DSC returns the following result: + +```yaml +beforeState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + _exist: false +afterState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +changedProperties: +- valueData +- _exist +``` + +You can test the instance to confirm that the key exists: + +```powershell +dsc resource test --resource Microsoft.Windows/Registry --input $instanceJson +``` + +```yaml +desiredState: + _exist: true + valueName: ManagedValue + valueData: + String: Default + keyPath: HKCU\DscExamples +actualState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +inDesiredState: true +differingProperties: [] +``` + +## Modify the data for a registry value + +The previous section created the `ManagedValue` registry value and defined the value data as the +string `Default`. The following snippet shows how you can modify the data with the **Set** +operation. + +First, change the desired state for the instance to specify the value as `Modified` and update the +`$instanceJson` variable to reflect the new desired state. + +```powershell +$instance.valueData.String = 'Modified' +$instance | ConvertTo-Json -OutVariable instanceJson +``` + +```json +{ + "_exist": true, + "valueName": "ManagedValue", + "valueData": { + "String": "Modified" + }, + "keyPath": "HKCU\\DSC\\Examples" +} +``` + +Next, compare the actual state of the instance to the desired state with the **Test** operation. + +```powershell +dsc resource test --resource Microsoft.Windows/Registry --input $instanceJson +``` + +```yaml +desiredState: + _exist: true + valueName: ManagedValue + valueData: + String: Modified + keyPath: HKCU\DscExamples +actualState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +inDesiredState: false +differingProperties: +- valueData +``` + +As expected, the output shows that the `valueData` isn't in the desired state. + +Finally, invoke the **Set** operation. + +```powershell +dsc resource set --resource Microsoft.Windows/Registry --input $instanceJson +``` + +```yaml +beforeState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default +afterState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Modified +changedProperties: +- valueData +``` + +The resource reports that it changed the `valueData` property and shows the actual state after the +**Set** operation as `Modified` instead of `Default`. + +## Remove a registry value + +The following snippet shows how you can use the [dsc resource delete][04] command to remove the +`ManagedValue` registry value. + +```powershell +dsc resource delete --resource Microsoft.Windows/Registry --input $instanceJson +``` + +The `dsc resource delete` command doesn't return any output. To verify the registry value no +longer exists, use the `dsc resource get` command. + +```powershell +dsc resource get --resource Microsoft.Windows/Registry --input $instanceJson +``` + +```yaml +actualState: + keyPath: HKCU\DscExamples + valueName: ManagedValue + _exist: false +``` + +> [!NOTE] +> Although this example used the **Delete** operation to remove the registry value instance, you can +> also use the **Set** operation. +> +> Because the resource uses the `_exist` canonical property, has the `delete` capability, and +> doesn't have the `setHandlesExist` capability, DSC knows to call the **Delete** operation for the +> resource when an instance defines `_exist` as `false`. + +## Cleanup + +To return your system to its original state, use the following snippet to remove the `DscExamples` +registry key and any remaining subkeys or values. + +```powershell +dsc resource delete --resource Microsoft.Windows/Registry --input @' +keyPath: HKCU\DscExamples +'@ +``` + + +[01]: ../../../../../cli/resource/test.md +[02]: ../../../../../schemas/resource/properties/exist.md +[03]: ../../../../../cli/resource/set.md +[04]: ../../../../../cli/resource/delete.md diff --git a/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.cleanup.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.cleanup.config.dsc.yaml new file mode 100644 index 00000000..1a7b8211 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.cleanup.config.dsc.yaml @@ -0,0 +1,8 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Remove DscExamples key remaining subkeys or values + type: Microsoft.Windows/Registry + properties: + _exist: false + keyPath: HKCU\DscExamples diff --git a/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.config.dsc.yaml new file mode 100644 index 00000000..66a1ef63 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/examples/registry.config.dsc.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Managed key + type: Microsoft.Windows/Registry + properties: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + - name: Managed value + type: Microsoft.Windows/Registry + properties: + _exist: true + keyPath: HKCU\DscExamples + valueName: ManagedValue + valueData: + String: Default diff --git a/docs/reference/resources/Microsoft/Windows/Registry/index.md b/docs/reference/resources/Microsoft/Windows/Registry/index.md new file mode 100644 index 00000000..ee107aa1 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/Registry/index.md @@ -0,0 +1,473 @@ +--- +description: Microsoft.Windows/Registry resource reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/Registry +--- + +# Microsoft.Windows/Registry + +## Synopsis + +Manage Windows Registry keys and values. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/Registry + properties: + # Required properties + keyPath: string + # Instance properties + _exist: + valueData: + valueName: +``` + +## Description + +The `Microsoft.Windows/Registry` resource enables you to idempotently manage registry keys and +values. The resource can: + +- Add and remove registry keys. +- Add, update, and remove registry values. + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has permissions to manage the keys in the hive + specified by the value of the **keyPath** property. For more information, see + [Registry key Security and Access Rights][01]. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of an instance. +- `set` - You can use the resource to enforce the desired state for an instance. +- `whatIf` - The resource is able to report how it would change system state during a **Set** + operation in what-if mode. +- `delete` - You can use the resource to directly remove an instance from the system. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][02]. + +## Examples + +1. [Manage a registry key][03] - Shows how to create and delete registry keys with the + `dsc resource` commands. +1. [Manage a registry value][04] - Shows how to create, modify, and delete registry values with the + `dsc resource` commands. +1. [Configure registry keys and values][05] - Shows how to define registry keys and values in a + configuration document. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. An instance that doesn't define each of these + properties is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][06] + + - [keyPath](#keypath) - The path to the registry key. + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][07]. + + - [keyPath](#keypath) (required) - The path to the registry key. + - [valueName](#valuename) (optional) - The name of the registry value. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [_exist](#_exist) - Defines whether the registry key or value should exist. + - [valueData](#valuedata) - The data for a registry value. + - [valueName](#valuename) - The name of the registry value. + +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][08]. + + - [_metadata](#_metadata) - Defines metadata returned by the resource. + +### keyPath + +
Expand for keyPath property metadata + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the path to the registry key for the instance. The path must start with a valid hive +identifier. Separate each segment of the path with a backslash (`\`). + +The following table describes the valid hive identifiers for the key path. + +| Short Name | Long Name | NT Path | +|:----------:|:---------------------:|:------------------------------------------------------------------------| +| `HKCR` | `HKEY_CLASSES_ROOT` | `\Registry\Machine\Software\Classes\` | +| `HKCU` | `HKEY_CURRENT_USER` | `\Registry\User\\` | +| `HKLM` | `HKEY_LOCAL_MACHINE` | `\Registry\Machine\` | +| `HKU` | `HKEY_USERS` | `\Registry\User\` | +| `HKCC` | `HKEY_CURRENT_CONFIG` | `\Registry\Machine\System\CurrentControlSet\Hardware Profiles\Current\` | + +### _exist + +
Expand for _exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +DefaultValue : true +``` + +
+ +The `_exist` canonical resource property determines whether an instance should exist. When the +value for `_exist` is `true`, the resource adds or creates the instance if it doesn't exist. When +the value for `_exist` is `false`, the resource removes or deletes the instance if it does exist. +The default value for this property when not specified for an instance is `true`. + +### valueData + +
Expand for valueData property metadata + +```yaml +Type : object +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +RequiresProperties : [valueName] +MinimumPropertyCount : 1 +MaximumPropertyCount : 1 +``` + +
+ +Defines the data for the registry value. If specified, this property must be an object with a +single property. The property name defines the data type. The property value defines the data +value. When the instance defines this property, the `valueName` property must also be defined. An +instance that defines `valueData` without `valueName` is invalid. + +`valueData` has the following properties: + +- [String](#string-valuedata) - Defines the value as a string (`REG_SZ`). +- [ExpandString](#expandstring-valuedata) - Defines the value as a string with expandable + references (`REG_EXPAND_SZ`). +- [MultiString](#multistring-valuedata) - Defines the value as a sequence of strings + (`REG_MULTI_SZ`). +- [Binary](#binary-valuedata) - Defines the value as a sequence of bytes (`REG_BINARY`). +- [DWord](#dword-valuedata) - Defines the value as a 32-bit unsigned integer (`REG_DWORD`). +- [QWord](#qword-valuedata) - Defines the value as a 64-bit unsigned integer (`REG_QWORD`). + +For more information on registry value data types, see +[Registry value types][09]. + +#### String valueData + +
Expand for valueData.String subproperty metadata + +```yaml +Type : string +``` + +
+ +Defines the registry value data as a null-terminated UTF-16 string. The resource handles +terminating the string. + +#### ExpandString valueData + +
Expand for valueData.ExpandString subproperty metadata + +```yaml +Type : string +``` + +
+ +Defines the registry value data as a null-terminated UTF-16 that contains unexpanded references to +environment variables, like `%PATH%`. The resource handles terminating the string. + +#### MultiString valueData + +
Expand for valueData.MultiString subproperty metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +ItemsMinimumCount : 0 +``` + +
+ +Defines the registry value data as a sequence of null-terminated UTF-16 strings. The resource +handles terminating the strings. + +#### Binary valueData + +
Expand for valueData.Binary subproperty metadata + +```yaml +Type : array +ItemsType : integer +ItemsInclusiveMinimumValue : 0 +ItemsInclusiveMaximumValue : 255 +ItemsMustBeUnique : false +``` + +
+ +Defines the registry value data as binary data in any form. The value must be an array of 8-bit +unsigned integers. + +#### DWord valueData + +
Expand for valueData.DWord subproperty metadata + +```yaml +Type : integer +InclusiveMinimumValue : 0 +InclusiveMaximumValue : 4294967295 +``` + +
+ +Defines the registry value data as a 32-bit unsigned integer. + +#### QWord valueData + +
Expand for valueData.QWord subproperty metadata + +```yaml +Type : integer +InclusiveMinimumValue : 0 +InclusiveMaximumValue : 18446744073709551615 +``` + +
+ +Defines the registry value data as a 64-bit unsigned integer. + +### valueName + +
Expand for valueName property metadata + +```yaml +Type: string +IsKey: false +``` + +
+ +Defines the name of the value to manage for the registry key. This property is required when +specifying the `valueData` property. + +### _metadata + +
Expand for _metadata property metadata + +```yaml +Type : object +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +IsDeprecated : false +``` + +
+ +This property is returned by the resource for **Set** operations invoked in what-if mode. For other +operations, the return data from the resource doesn't include this property. + +`_metadata` has the following properties: + +- [whatIf](#whatif) - Contains messages about how the resource would change the system in a **Set** + operation. + +#### whatIf + +
Expand for _metadata.whatIf subproperty metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +ItemsMinimumCount : 0 +``` + +
+ +This metadata property is only returned when invoking the resource set operation in what-if mode. +It contains any number of messages from the resource about how it would change the system in a set +operation without the `--what-if` flag. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +nonvalidating keywords are omitted. + +```json +{ + "type": "object", + "required": [ + "keyPath" + ], + "dependentRequired": { + "valueData": [ + "valueName" + ] + }, + "additionalProperties": false, + "properties": { + "_exist": { + "type": "boolean", + "default": true + }, + "_metadata": { + "type": "object", + "readOnly": true, + "properties": { + "whatIf": { + "type": "array", + "readOnly": true, + "items": { + "type": "string" + } + } + } + }, + "keyPath": { + "type": "string", + "pattern": "^(HKCR|HKEY_CLASSES_ROOT|HKCU|HKEY_CURRENT_USER|HKLM|HKEY_LOCAL_MACHINE|HKU|HKEY_USERS|HKCC|HKEY_CURRENT_CONFIG)\\\\" + }, + "valueData": { + "type": "object", + "minProperties": 1, + "maxProperties": 1, + "properties": { + "String": { + "type": "string" + }, + "ExpandString": { + "type": "string" + }, + "MultiString": { + "type": "string" + }, + "Binary": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0, + "maximum": 255 + } + }, + "DWord": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + }, + "QWord": { + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + } + } + }, + "valueName": { + "type": "string" + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid parameter +- [2](#exit-code-2) - Invalid input +- [3](#exit-code-3) - Registry error +- [4](#exit-code-4) - Json serialization failed + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed due to an invalid parameter. When the resource returns this +exit code, it also emits an error message with details about the invalid parameter. + +### Exit code 2 + +Indicates the resource operation failed because the input instance was invalid. When the resource +returns this exit code, it also emits one or more error messages with details describing how the +input instance was invalid. + +### Exit code 3 + +Indicates the resource operation failed due to an error raised by the Windows Registry API. When +the resource returns this exit code, it also emits the error message raised by the registry. + +### Exit code 4 + +Indicates the resource operation failed because the result couldn't be serialized to JSON. + +## See also + +- [Microsoft/OSInfo resource][10] +- For more information about the Windows Registry, see [About the Registry][11] + + +[01]: /windows/win32/sysinfo/registry-key-security-and-access-rights +[02]: ../../../../../concepts/resources/capabilities.md +[03]: ./examples/manage-a-registry-key.md +[04]: ./examples/manage-a-registry-value.md +[05]: ./examples/configure-registry-keys-and-values.md +[06]: ../../../../../concepts/resources/properties.md#required-resource-properties +[07]: ../../../../../concepts/resources/properties.md#key-resource-properties +[08]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[09]: /en-us/windows/win32/sysinfo/registry-value-types +[10]: ../../osinfo/index.md +[11]: /windows/win32/sysinfo/about-the-registry diff --git a/docs/reference/resources/Microsoft/Windows/WMI/index.md b/docs/reference/resources/Microsoft/Windows/WMI/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/resources/overview.md b/docs/reference/resources/overview.md new file mode 100644 index 00000000..050999f1 --- /dev/null +++ b/docs/reference/resources/overview.md @@ -0,0 +1,59 @@ +# Built-in DSC resource reference + +Each release of DSC includes built-in resources that you can use immediately after you install DSC. +This document lists the available resources and links to the reference documentation for each. + +## All built-in resources + +- [Microsoft/OSInfo](./microsoft/osinfo/resource.md) +- [Microsoft.DSC/Assertion](./microsoft/dsc/assertion/resource.md) +- [Microsoft.DSC/Group](./microsoft/dsc/group/resource.md) +- [Microsoft.DSC/Include](./microsoft/dsc/include/resource.md) +- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) +- [Microsoft.DSC.Debug/Echo](./microsoft/dsc/debug/echo/resource.md) +- [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) +- [Microsoft.Windows/RebootPending](./microsoft/windows/rebootpending/resource.md) +- [Microsoft.Windows/Registry](./microsoft/windows/registry/resource.md) +- [Microsoft.Windows/WindowsPowerShell](./microsoft/windows/windowspowershell/resource.md) +- [Microsoft.Windows/WMI](./microsoft/windows/wmi/resource.md) + +## Built-in assertion resources + +You can use the following built-in resources to query the current state of a machine but not to +change the state of the machine directly: + +- [Microsoft/OSInfo](./microsoft/osinfo/resource.md) +- [Microsoft.DSC/Assertion](./microsoft/dsc/assertion/resource.md) +- [Microsoft.Windows/RebootPending](./microsoft/windows/rebootpending/resource.md) + +## Built-in adapter resources + +You can use the following built-in resources to leverage resources that don't define a DSC Resource +Manifest: + +- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) +- [Microsoft.Windows/WindowsPowerSHell](./microsoft/windows/windowspowershell/resource.md) +- [Microsoft.Windows/WMI](./microsoft/windows/wmi/resource.md) + +## Built-in configurable resources + +The following built-in resources to change the state of a machine directly: + +- [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) +- [Microsoft.Windows/Registry](./microsoft/windows/registry/resource.md) + +## Built-in debugging resources + +You can use the following built-in resources when debugging or exploring DSC. They don't affect +the state of the machine. + +- [Microsoft.DSC.Debug/Echo](./microsoft/dsc/debug/echo/resource.md) + +## Built-in group resources + +You can use the following built-in resources to change how DSC processes a group of nested resource +instances: + +- [Microsoft.DSC/Assertion](./microsoft/dsc/assertion/resource.md) +- [Microsoft.DSC/Group](./microsoft/dsc/group/resource.md) +- [Microsoft.DSC/Include](./microsoft/dsc/include/resource.md) diff --git a/docs/reference/schemas/overview.md b/docs/reference/schemas/overview.md new file mode 100644 index 00000000..076f667a --- /dev/null +++ b/docs/reference/schemas/overview.md @@ -0,0 +1,87 @@ +--- +description: >- + Overview of the reference documentation for the JSON schemas describing data types for + Microsoft's Desired State Configuration platform. +ms.date: 03/25/2025 +ms.topic: reference +title: DSC JSON Schema reference overview +--- + +# DSC JSON Schema reference overview + +Microsoft's Desired State Configuration platform uses [JSON schemas][01] to describe and validate +the data that DSC takes as input and returns as output. + +These schemas define the structure, purpose, and validation for data in DSC and are published to +the DSC GitHub repository. DSC publishes updated schemas with every release. Each schema has an +`$id` keyword that uniquely identifies the schema. For convenience, DSC provides shortened links to +the schemas under the `aka.ms/dsc/schemas` namespace. + +For more information about how the DSC schemas are published and the URIs that identify them, see +[DSC JSON Schema URIs][02]. + +The articles in this section provide reference documentation for the latest supported version of +the DSC schemas. + +## Configuration document schemas + +The article [DSC configuration document schema reference][03] describes the root JSON schema for +configuration documents. + +The article [DSC Configuration document functions reference][04] describes DSC configuration +functions generally and links to the reference documentation for the available functions. + +## Resource schemas + +The article [DSC command resource manifest schema reference][05] describes the root JSON schema for +resource manifests. + +The article [# DSC canonical properties reference][06] describes DSC canonical resource properties +generally and links to the reference documentation for the available canonical properties. + +## Output schemas + +The following table links to the reference documentation for the JSON schemas describing the output +DSC returns for its commands: + +| Command | Article link | +|:--------------------|:------------------------------------------------------------------------| +| `dsc config get` | [dsc config get result schema reference][07] | +| `dsc config set` | [dsc config set result schema reference][08] | +| `dsc config test` | [dsc config test result schema reference][09] | +| `dsc resource get` | [dsc resource get result schema reference][10] | +| `dsc resource list` | [dsc resource list result schema reference][11] | +| `dsc resource set` | [dsc resource set result schema reference][12] | +| `dsc resource test` | [dsc resource test result schema reference][13] | + +## Definition schemas + +The following list defines the reference documentation for JSON schemas included as subschemas +throughout DSC. + +- For more information about the `Microsoft.DSC` metadata property, see + [Microsoft.DSC metadata property schema reference][14] +- For more information about the messages DSC emits, see [Structured message schema reference][15] +- For more information about the kinds of DSC resources and how they affect schema validation, see + [DSC Resource kind schema reference][16]. +- For more information about the naming of DSC resources and how they're validated, see + [DSC Resource fully qualified type name schema reference][17] + + +[01]: https://json-schema.org/overview/what-is-jsonschema +[02]: ./schema-uris.md +[03]: ./config/document.md +[04]: ./config/functions/overview.md +[05]: ./resource/manifest/root.md +[06]: ./resource/properties/overview.md +[07]: ./outputs/config/get.md +[08]: ./outputs/config/set.md +[09]: ./outputs/config/test.md +[10]: ./outputs/resource/get.md +[11]: ./outputs/resource/list.md +[12]: ./outputs/resource/set.md +[13]: ./outputs/resource/test.md +[14]: ./metadata/Microsoft.DSC/properties.md +[15]: ./definitions/message.md +[16]: ./definitions/resourceKind.md +[17]: ./definitions/resourceType.md diff --git a/docs/reference/schemas/schema-uris.md b/docs/reference/schemas/schema-uris.md index 84c3c299..f0fae111 100644 --- a/docs/reference/schemas/schema-uris.md +++ b/docs/reference/schemas/schema-uris.md @@ -1,6 +1,6 @@ --- description: Reference for how DSC schemas are versioned and published and the URIs used to retrieve them. -ms.date: 02/28/2025 +ms.date: 03/25/2025 ms.topic: reference title: DSC JSON Schema URIs --- @@ -25,16 +25,16 @@ The URIs for DSC schemas use the following syntax: The schemas for DSC are hosted in the `schemas` folder of the DSC repository. The URI prefix for accessing the schemas in GitHub is `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas`. -However, DSC also provides short links for every schema URI. When using the short link to a schema, -the URI prefix is `https://aka.ms/dsc/schemas`. +However, DSC also provides short links for every schema URI. When you use the short link to a +schema, the URI prefix is `https://aka.ms/dsc/schemas`. You can use either prefix in your configuration documents, resource manifests, or when retrieving the schemas programmatically. ## Schema Versioning -DSC uses [semantic versioning](https://semver.org) and aligns the version of the CLI, the platform, -and the JSON schemas. A non-prerelease semantic version includes three segments: +DSC uses [semantic versioning][01] and aligns the version of the CLI, the platform, and the JSON +schemas. A nonprerelease semantic version includes three segments: ```syntax .. @@ -75,21 +75,21 @@ Publishing the schemas under multiple version folders enables you to choose whic to use for your resource manifests, configuration documents, and integrating tools. If you pin to a full semantic version folder, like `v3.0.0`, you're pinning to schemas that won't -change. However, to take advantage of any improvements or fixes to the schemas, you'll need to -update the URI with each release. +change. However, to take advantage of any improvements or fixes to the schemas, you need to update +the URI with each release. If you pin to a minor version folder, like `v3.0`, the schemas you use will update with every patch -release. This enables you to take advantage of fixes to the schemas without continually updating -your schema URIs. However, to take advantage of any improvements or new features, you'll need to -update the URI whenever a new minor version is released. +release. Pinning to a minor version folder enables you to take advantage of fixes to the schemas +without continually updating your schema URIs. However, to take advantage of any improvements or +new features, you need to update the URI whenever a new minor version is released. If you pin to a major version folder, like `v3`, the schemas you use will update with every -non-breaking release. You can use those schemas until you want or need to migrate to a new major +nonbreaking release. You can use those schemas until you want or need to migrate to a new major version of DSC. -Microsoft recommends that the majority of users pin to the major version folder for ease of use. If -you're an integrating developer or a resource author, consider pinning to a specific minor version -to indicate that your resource or software hasn't been updated to take advantage of new features. +Microsoft recommends that most users pin to the major version folder for ease of use. If you're an +integrating developer or a resource author, consider pinning to a specific minor version to +indicate that your resource or software isn't updated to take advantage of new features. ## Schema forms @@ -98,54 +98,53 @@ URI. Schemas for top-level items, like configuration documents, resource manifes types for DSC, are also published in their canonically bundled form and in their enhanced authoring form. -All JSON schemas published for DSC use the [2020-12 JSON Schema Specification][xx] unless otherwise +All JSON schemas published for DSC use the [2020-12 JSON Schema Specification][02] unless otherwise noted, regardless of their form. -The canonical (non-bundled) form schemas don't have a prefix folder for their path. They always use +The canonical (nonbundled) form schemas don't have a prefix folder for their path. They always use the `.json` file extension for their URI. For example, the URI for the canonical schema describing a resource manifest is `//resource/manifest.json`. The `$id` keyword for every schema is always set to the canonical form of the schema for that version folder and uses -the GitHub URI prefix. This ensures that the schemas can always be correctly resolved by reference. +the GitHub URI prefix. Using the canonical form ensures that the schemas are always correctly +resolvable by reference. The canonically bundled form schemas are placed in the `bundled` prefix folder for their path. They always use the `.json` file extension for their URI. For example, the URI for the canonically bundled schema describing a resource manifest is `//bundled/resource/manifest.json`. -The enhanced authoring form for schemas are placed in the `bundled` prefix folder for their path. -They always use the `.vscode.json` file extension for their URI. For example, the URI for the -enhanced authoring schema describing a resource manifest is +The enhanced authoring form schemas are placed in the `bundled` prefix folder for their path. They +always use the `.vscode.json` file extension for their URI. For example, the URI for the enhanced +authoring schema describing a resource manifest is `//bundled/resource/manifest.vscode.json`. The following table illustrates these differences between schema forms: | Schema form | Prefix folder | File extension | |:------------------------|:-------------:|:--------------:| -| Canonical (non-bundled) | _None_ | `.json` | +| Canonical (nonbundled) | _None_ | `.json` | | Canonically bundled | `bundled` | `.json` | | Enhanced autoring | `bundled` | `.vscode.json` | -### Canonical (non-bundled) schemas +### Canonical (nonbundled) schemas The canonical form for each schema describes a single type for DSC. If the schema references any -other DSC types with the [$ref keyword](), those references are site-relative. Publishing the -schemas in this format enables users and developers to select only the schemas for the data types -they want to use without needing to download or handle other schemas they may not require. +other DSC types with the [$ref keyword][03], those references are site-relative. This format +enables you to select only the schemas for the data types you want to use. -While DSC is able to validate any of its data without network connectivity, be aware that using the -canonical non-bundled form for a schema may require more than one network call to retrieve any -references schemas. To minimize the number of network operations, use the canonically bundled form -for the schema instead. +> [!NOTE] +> While DSC can validate any of its data without network connectivity, using the canonical +> nonbundled form for a schema might require more than one network call to resolve references. To +> minimize the number of network operations, use the canonically bundled form for the schema +> instead. ### Canonically bundled schemas -Not every DSC schema is available in the -[canonically bundled](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents) -form. Only top-level schemas, like configuration documents, resource manifests, and DSC's output, -are published in this form. +Not every DSC schema is available in the [canonically bundled][04] form. Only top-level schemas, +like configuration documents, resource manifests, and DSC's output, are published in this form. -Canonically bundled schemas generally reference numerous other schemas with the [$ref keyword](). -As with the non-bundled form, these references are site-relative. Unlike the non-bundled form, +Canonically bundled schemas generally reference numerous other schemas with the [$ref keyword][03]. +As with the nonbundled form, these references are site-relative. Unlike the nonbundled form, the bundled form recursively includes every referenced schema in the `$defs` keyword. The `$defs` keyword is always an object. For canonically bundled schemas, every key is the @@ -156,16 +155,16 @@ the `$schema` keyword. ### Enhanced authoring schemas Every DSC Schema published in the canonically bundled form is also published in the enhanced -authoring form. These schemas leverage the extended vocabulary that VS Code recognizes for JSON -Schemas to provide improved IntelliSense, hover documentation, error messaging, and default -snippets. These schemas make it easier to author, edit, and review your configuration documents, -resource manifests, and DSC's output in VS Code. +authoring form. These schemas use the extended vocabulary that VS Code recognizes for JSON Schemas +to provide improved IntelliSense, hover documentation, error messaging, and default snippets. These +schemas make it easier to author, edit, and review your configuration documents, resource +manifests, and DSC's output in VS Code. These schemas validate the data with the same vocabulary as the canonical forms of the schema. They only affect the experience for authoring, editing, and reviewing the data in VS Code. These JSON Schemas are _not_ canonical. They use a vocabulary that most JSON Schema libraries and -tools don't understand. In most cases, using these schemas with those tools should not raise any +tools don't understand. In most cases, using these schemas with those tools shouldn't raise any errors. However, when you want to use the DSC schemas with tools other than VS Code, you should consider using the canonically bundled form of the schema instead. @@ -187,8 +186,8 @@ schemas from the following uri: ### Configuration document schema The following table defines the value of the `$id` keyword for each published version of the -configuration document schema. The `$id` is the same across all forms of the schema and regardless of -the prefix URI used to retrieve the schema. +configuration document schema. The `$id` is the same across all forms of the schema and regardless +of the prefix URI used to retrieve the schema. | Version folder | ID | |:---------------|:--------------------------------------------------------------------------------------------| @@ -202,9 +201,9 @@ The following list of tables defines the recognized URIs for the configuration d | Form | Version | Recognized URI | |:------------------------|:---------|:------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/config/document.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/config/document.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/config/document.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/config/document.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/config/document.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/config/document.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/config/document.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/config/document.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json` | @@ -216,9 +215,9 @@ The following list of tables defines the recognized URIs for the configuration d | Form | Version | Recognized URI | |:------------------------|:---------|:-----------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.json` | @@ -244,9 +243,9 @@ The following list of tables defines the recognized URIs for the resource manife | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/resource/manifest.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/resource/manifest.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/resource/manifest.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json` | @@ -258,9 +257,9 @@ The following list of tables defines the recognized URIs for the resource manife | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json` | @@ -286,9 +285,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/get.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/get.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/get.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/get.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/get.json` | @@ -300,9 +299,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/get.json` | @@ -328,9 +327,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/set.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/set.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/set.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/set.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/set.json` | @@ -342,9 +341,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/set.json` | @@ -370,9 +369,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/test.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/test.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/test.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/test.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/test.json` | @@ -384,9 +383,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/test.json` | @@ -412,9 +411,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/get.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/get.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/get.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/get.json` | @@ -426,9 +425,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/get.json` | @@ -454,9 +453,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/list.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/list.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/list.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/list.json` | @@ -468,9 +467,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/list.json` | @@ -496,9 +495,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/schema.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/schema.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/schema.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/schema.json` | @@ -510,9 +509,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/schema.json` | @@ -538,9 +537,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/set.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/set.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/set.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/set.json` | @@ -552,9 +551,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/set.json` | @@ -580,9 +579,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/test.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/test.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/test.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/test.json` | @@ -594,9 +593,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/test.json` | @@ -622,9 +621,9 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:--------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/schema.json` | - | Canonical (non-bundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/schema.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/schema.json` | + | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/schema.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/schema.json` | | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/schema.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/schema.json` | @@ -636,12 +635,18 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------| - | Canonical (non-bundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` | - | Canonical (non-bundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` | - | Canonical (non-bundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | + | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` | + | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/schema.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/schema.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/schema.vscode.json` | + + +[01]: https://semver.org +[02]: https://json-schema.org/draft/2020-12 +[03]: https://json-schema.org/draft/2020-12/json-schema-core#section-8.2.3.1 +[04]: https://json-schema.org/blog/posts/bundling-json-schema-compound-documents diff --git a/docs/reference/tools/builtin.md b/docs/reference/tools/builtin.md new file mode 100644 index 00000000..7f9f5b4f --- /dev/null +++ b/docs/reference/tools/builtin.md @@ -0,0 +1,45 @@ +--- +description: >- + Lists the tools that ship with DSC, their purpose, and links to the reference documentation for + each tool. +ms.date: 03/25/2025 +ms.topic: reference +title: osinfo +--- + +# DSC tools overview + +Microsoft's Desired State Configuration (DSC) platform includes commandline tools for early +feedback and functionality. + +The following table describes the tools included in current releases of DSC and the platforms those +tools are available for: + +| Executable | Platforms | Description | +|:-----------|:----------------------|:--------------------------------------------------------| +| `osinfo` | Linux, macOS, Windows | Returns information about the operating system as JSON. | +| `registry` | Windows | Manages registry keys and values. | + +## osinfo + +The `osinfo` command returns information about the operating system as JSON. `osinfo` is +available in the DSC release for all supported platforms. DSC includes this command to provide the +`Microsoft/OSInfo` DSC resource. + +For more information about the command, see [osinfo command reference][01]. For more +information about the resource, see [Microsoft/OSInfo][02]. + +## registry + +The `registry` command manages Windows Registry keys and values. `registry` is only available in +DSC releases for Windows. DSC includes this command to provide the `Microsoft.Windows/Registry` DSC +resource. + +For more information about the command, see [registry command reference][03]. For +more information about the resource, see [Microsoft.Windows/Registry][04]. + + +[01]: ./osinfo.md +[02]: ../resources/Microsoft/OSInfo/index.md +[03]: ./registry/index.md +[04]: ../resources/Microsoft/Windows/Registry/index.md diff --git a/docs/reference/tools/osinfo.md b/docs/reference/tools/osinfo.md new file mode 100644 index 00000000..9d5cc535 --- /dev/null +++ b/docs/reference/tools/osinfo.md @@ -0,0 +1,99 @@ +--- +description: Command line reference for the 'osinfo' command +ms.date: 03/25/2025 +ms.topic: reference +title: osinfo command reference +--- + +# osinfo command reference + +## Synopsis + +Returns information about the operating system. + +> [!IMPORTANT] +> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with +> DSC. Don't use it in production. + +## Syntax + +```sh +osinfo +``` + +## Description + +The `osinfo` command returns information about the operating system as a single line of compressed +JSON without any whitespace. The command doesn't accept any options or arguments. + +The properties of the output JSON object are the properties for the `Microsoft/OSInfo` DSC +Resource. For more information about those properties and using the resource, see +[Microsoft/OSInfo][01]. + +## Examples + +### Example 1 - Get operating system information + +Call the command to return information about the operating system. + +```sh +osinfo +``` + +### [Linux](#tab/linux) + +```Output +{"$id":"https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json","family":"Linux","version":"20.04","codename":"focal","bitness":"64","architecture":"x86_64"} +``` + +The following code block shows the output with newlines and indentation for readability. + +```json +{ + "$id": "https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json", + "family": "Linux", + "version": "20.04", + "codename": "focal", + "bitness": "64", + "architecture": "x86_64" +} +``` + +### [macOS](#tab/macos) + +```Output +{"$id":"https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json","family":"MacOS","version":"13.5.0","bitness":"64","architecture":"arm64"} +``` + +The following code block shows the output with newlines and indentation for readability. + +```json +{ + "$id": "https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json", + "family": "MacOS", + "version": "13.5.0", + "bitness": "64", + "architecture": "arm64" +} +``` + +### [Windows](#tab/windows) + +```Output +{"$id":"https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json","family":"Windows","version":"10.0.22621","edition":"Windows 11 Enterprise","bitness":"64"} +``` + +The following code block shows the output with newlines and indentation for readability. + +```json +{ + "$id": "https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json", + "family": "Windows", + "version": "10.0.22621", + "edition": "Windows 11 Enterprise", + "bitness": "64" +} +``` + + +[01]: ../resources/Microsoft/OSInfo/index.md diff --git a/docs/reference/tools/registry/config/delete.md b/docs/reference/tools/registry/config/delete.md new file mode 100644 index 00000000..b0607179 --- /dev/null +++ b/docs/reference/tools/registry/config/delete.md @@ -0,0 +1,104 @@ +--- +description: Command line reference for the 'registry config delete' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry config delete +--- + +# registry config delete + +## Synopsis + +Retrieve registry configuration. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry config delete [OPTIONS] --input +``` + +## Description + +The `delete` command removes a registry key or value as an instance of the +`Microsoft.Windows/Registry` resource. It expects input as a JSON instance of the resource for the +`--input` option. + +The input instance must define the [keyPath][01] property. It uses the `keyPath` value to determine +which registry key to operate on. If the input instance includes the [valueName][02] property, the +command remove that value instead of the registry key itself. + +## Examples + +### Example 1 - delete a registry value + + + +The command returns the current state of the specified registry value as a single line of compressed +JSON without any whitespace. + +```powershell +$instance = @{ + keyPath = 'HKCU\Example\Key' + valueName = 'ExampleValue' +} | ConvertTo-Json + +registry config delete --input $instance | ConvertFrom-Json | Format-List +``` + +### Example 2 - delete a registry key + + + +The command returns the current state of the specified registry key as a single line of compressed +JSON without any whitespace. + +```powershell +$instance = @{ + _exist = $true + keyPath = 'HKCU\Example\Key' +} | ConvertTo-Json + +registry config delete --input $instance | ConvertFrom-Json | Format-List +``` + +## Options + +### -i, --input + + + + +Specifies the resource instance to remove from the system. + +The instance must be a string containing a JSON object that is valid for the resource's instance +schema. + +```yaml +Type : string +Mandatory : true +LongSyntax : --input +ShortSyntax : -i +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all other options and arguments. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h +``` + + +[01]: ../../../resources/Microsoft/Windows/Registry/index.md#keypath +[02]: ../../../resources/Microsoft/Windows/Registry/index.md#valuename diff --git a/docs/reference/tools/registry/config/get.md b/docs/reference/tools/registry/config/get.md new file mode 100644 index 00000000..510e00fb --- /dev/null +++ b/docs/reference/tools/registry/config/get.md @@ -0,0 +1,162 @@ +--- +description: Command line reference for the 'registry config get' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry config get +--- + +# registry config get + +## Synopsis + +Retrieve registry configuration. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry config get [OPTIONS] --input +``` + +## Description + +The `get` command returns the current state of a registry key or value as an instance of the +`Microsoft.Windows/Registry` resource. It expects input as a JSON instance of the resource for the +`--input` option. + +The input instance must define the [keyPath][01] property. It uses the `keyPath` value to determine +which registry key to retrieve. If the input instance includes the [valueName][02] property, the +command retrieves the current state of that value instead of the registry key. + +## Examples + +### Example 1 - Get a registry key + + + +The command returns the current state of the specified registry key as a single line of compressed +JSON without any whitespace. + +```powershell +$instance = @{ + keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion' +} | ConvertTo-Json + +registry config get --input $instance +``` + +```json +{"keyPath":"HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion"} +``` + +When the specified key doesn't exist, the `_exist` property is `false`. + +```powershell +$instance = @{ + keyPath = 'HKCU\Example\Nested\Key' +} | ConvertTo-Json + +$instance | registry config get +``` + +```json +{"keyPath":"HKCU\\Example\\Nested\\Key","_exist":false} +``` + +### Example 2 - Get a registry value + + + +The command returns the current state of the specified registry value as a single line of compressed +JSON without any whitespace. + +```powershell +$instance = @{ + keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion' + valueName = 'SystemRoot' +} | ConvertTo-Json + +registry config get --input $instance | ConvertFrom-Json | Format-List +``` + +```Output +keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion +valueName : SystemRoot +valueData : @{String=C:\WINDOWS} +``` + +When the specified key doesn't exist, the output only includes the `keyPath` and `_exist` +properties with `_exist` defined as `false`. + +```powershell +$instance = @{ + keyPath = 'HKLM\Software\Microsoft\Windows NT\DoesNotExist' + valueName = 'SystemRoot' +} | ConvertTo-Json + +registry config get --input $instance | ConvertFrom-Json | Format-List +``` + +```Output +keyPath : HKLM\Software\Microsoft\Windows NT\DoesNotExist +_exist : False +``` + +When the specified key exists but the value doesn't, the output only includes the `keyPath`, +`valueName`, and `_exist` properties with `_exist` defined as `false`. + +```powershell +$instance = @{ + keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion' + valueName = 'DoesNotExist' +} | ConvertTo-Json + +registry config get --input $instance | ConvertFrom-Json | Format-List +``` + +```Output +keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion +valueName : DoesNotExist +_exist : False +``` + +## Options + +### -i, --input + + + + +Specifies the resource instance to retrieve from the system. + +The instance must be a string containing a JSON object that is valid for the resource's instance +schema. + +```yaml +Type : string +Mandatory : true +LongSyntax : --input +ShortSyntax : -i +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all other options and arguments. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h +``` + + +[01]: ../../../resources/Microsoft/Windows/Registry/index.md#keypath +[02]: ../../../resources/Microsoft/Windows/Registry/index.md#valuename diff --git a/docs/reference/tools/registry/config/index.md b/docs/reference/tools/registry/config/index.md new file mode 100644 index 00000000..ef59f83e --- /dev/null +++ b/docs/reference/tools/registry/config/index.md @@ -0,0 +1,97 @@ +--- +description: Command line reference for the 'registry config' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry config +--- + +# registry config + +## Synopsis + +Manage registry configuration. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry config [Options] +``` + +## Description + +The `registry config` commands manage registry keys and values as instances of the +`Microsoft.Windows/Registry` DSC Resource. They expect to receive an instance as JSON over stdin +and are usable for invoking the get, test, and set operations for the resource. + +For more information about using `registry` with DSC, see [Microsoft.Windows/Registry][01]. + +## Commands + +### get + +The `get` command returns the current state of a registry key or value. For more information, see +[get][02]. + +### set + +The `set` command enforces the desired state for a registry key or value. For more information, see +[set][03]. + +### delete + +The `delete` command validates wether a registry key or value is in the desired state. For more +information, see [delete][04]. + +### help + +The `help` command returns help information for this command or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +registry config help [] +``` + +For example, `registry config help` gets the help for this command. `registry config help get` +gets the help for the `get` subcommand. + +You can also use the [--help](#-h---help) option on the command or subcommand to display the help +information. For example, `registry config --help` or `registry config set --help`. + +## Options + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +### -V, --version + + + + +Displays the version of the application. When you specify this option, the application ignores all +options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + + +[01]: ../../../resources/Microsoft/Windows/Registry/index.md +[02]: ./get.md +[03]: ./set.md +[04]: ./delete.md diff --git a/docs/reference/tools/registry/config/set.md b/docs/reference/tools/registry/config/set.md new file mode 100644 index 00000000..389190d4 --- /dev/null +++ b/docs/reference/tools/registry/config/set.md @@ -0,0 +1,160 @@ +--- +description: Command line reference for the 'registry config set' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry config set +--- + +# registry config set + +## Synopsis + +Apply registry configuration. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry config config set [OPTIONS] --input +``` + +## Description + +The `set` command returns the current state of a registry key or value as an instance of the +`Microsoft.Windows/Registry` resource. It expects input as a JSON instance of the resource for the +`--input` option. + +The input instance must define the [keyPath][01] property. It uses the `keyPath` value to determine +which registry key to configure. If the input instance includes the [valueName][02] property, the +command configures the current state of that value instead of the registry key. + +This command can only create and modify registry keys and values. To delete a registry key or +value, use the [registry config delete][03] command. + +For more information about the available properties for configuring registry keys and values, see +[Microsoft.Windows/Registry][04]. + +## Examples + +### Example 1 - Ensure a registry key exists + + + +Because the input instance defines the `_exist` property as `true`,the command creates the +`HKCU\ExampleKey` if it doesn't exist. + +```powershell +$InputInstance = @{ + _exist = $true + keyPath = 'HKCU\Example\Key' +} | ConvertTo-Json + +registry config get --input $InputInstance | ConvertFrom-Json | Format-List +registry config set --input $InputInstance | ConvertFrom-Json | Format-List +registry config get --input $InputInstance | ConvertFrom-Json | Format-List +``` + +```Output +keyPath : HKCU\Example\Key +_exist : False + + + +keyPath : HKCU\Example\Key +``` + +### Example 2 - Ensure a registry value exists + + + +The instance combines the values of the `keyPath`, `valueName`, and `valueData` properties to +ensure that the `ExampleKey` registry key in the current user hive has a value named +`ExampleValue`. If the value doesn't already exist, the command creates the value with the string +`SomeValue` as its data. + +```powershell +$InputInstance = @{ + _exist = $true + keyPath = 'HKCU\Example\Key' + valueName = 'ExampleValue' + valueData = @{ + String = 'SomeValue' + } +} | ConvertTo-Json + +registry config get --input $InputInstance | ConvertFrom-Json | Format-List +registry config set --input $InputInstance | ConvertFrom-Json | Format-List +registry config get --input $InputInstance | ConvertFrom-Json | Format-List +``` + +```Output +keyPath : HKCU\ExampleKey +valueName : ExampleValue +_exist : False + + + +keyPath : HKCU\Example\Key +valueName : ExampleValue +valueData : @{String=SomeValue} +``` + +## Options + +### -i, --input + + + + +Specifies the desired state of the resource instance to enforce on the system. + +The instance must be a string containing a JSON object that is valid for +the resource's instance schema. + +```yaml +Type : string +Mandatory : true +LongSyntax : --input +ShortSyntax : -i +``` + +### -w, --what-if + + + + +When you specify this flag option, the command doesn't actually change the system state. Instead, +it returns JSON messages to stderr indicating _how_ the operation will change system state when +called without this option. This option enables the resource to support the what-if mode for +**Set** operations in DSC. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --what-if +ShortSyntax : -w +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all other options and arguments. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h +``` + + +[01]: ../../../resources/Microsoft/Windows/Registry/index.md#keypath +[02]: ../../../resources/Microsoft/Windows/Registry/index.md#valuename +[03]: ./delete.md +[04]: ../../../resources/Microsoft/Windows/Registry/index.md diff --git a/docs/reference/tools/registry/find/index.md b/docs/reference/tools/registry/find/index.md new file mode 100644 index 00000000..e5952ed0 --- /dev/null +++ b/docs/reference/tools/registry/find/index.md @@ -0,0 +1,113 @@ +--- +description: Command line reference for the 'registry find' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry find +--- + +# registry find + +## Synopsis + +Find a registry key or value. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry find [Options] --key-path +``` + +## Description + +The `find` command isn't implemented yet. It returns a string that echoes the specified options. + +## Options + +### -k, --key-path + + + + +Specifies the registry key path to use as the base for the search. The path must start with a valid +hive identifier. Each segment of the path must be separated by a backslash (`\`). + +The following table describes the valid hive identifiers for the key path. + +| Short Name | Long Name | NT Path | +| :--------: | :-------------------: | :---------------------------------------------------------------------- | +| `HKCR` | `HKEY_CLASSES_ROOT` | `\Registry\Machine\Software\Classes\` | +| `HKCU` | `HKEY_CURRENT_USER` | `\Registry\User\\` | +| `HKLM` | `HKEY_LOCAL_MACHINE` | `\Registry\Machine\` | +| `HKU` | `HKEY_USERS` | `\Registry\User\` | +| `HKCC` | `HKEY_CURRENT_CONFIG` | `\Registry\Machine\System\CurrentControlSet\Hardware Profiles\Current\` | + +```yaml +Type: String +Mandatory: true +``` + +### -f, --find + + + + +The string to search for in the registry key and value names. + +```yaml +Type: String +Mandatory: true +``` + +### -r, --recurse + + + + +Indicates whether the command should recursively find subkeys and values. By default, the command +isn't recursive. + +```yaml +Type: boolean +Mandatory: false +``` + +### --keys_only + + + +Indicates whether the command should limit results to registry keys. By default, the command +returns matching registry keys and values. + +```yaml +Type: boolean +Mandatory: false +``` + +### --values_only + + + +Indicates whether the command should limit results to registry values. By default, the command +returns matching registry keys and values. + +```yaml +Type: boolean +Mandatory: false +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: boolean +Mandatory: false +``` diff --git a/docs/reference/tools/registry/index.md b/docs/reference/tools/registry/index.md new file mode 100644 index 00000000..c1d81966 --- /dev/null +++ b/docs/reference/tools/registry/index.md @@ -0,0 +1,130 @@ +--- +description: Command line reference for the 'registry' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry +--- + +# registry + +## Synopsis + +Manage state of Windows registry + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry [Options] +``` + +## Description + +DSC includes an example command, `registry`, for managing keys and values in the Windows registry. +The command also defines a DSC resource manifest, making it available as a [DSC resource][01] on +Windows machines. + +You can use `registry` to: + +- Query the registry for keys and values +- Create, update, and delete registry keys and values +- Invoke the `Microsoft.Windows/Registry` resource with DSC to manage registry keys and values + idempotently. +- Define instances of the `Microsoft.Windows/Registry` resource in DSC Configuration Documents. + +For more information about using `registry` as a resource, see [Microsoft.Windows/Registry][02]. + +## Commands + +### query + +The `query` command isn't implemented yet. It returns a string that echoes the specified options. +For more information, see [query][03]. + +### set + +The `set` command isn't implemented yet. It returns a string that echoes the specified options. For +more information, see [set][04]. + +### remove + +The `remove` command isn't implemented yet. It returns a string that echoes the specified options. +For more information, see [remove][05]. + +### find + +The `find` command isn't implemented yet. It returns a string that echoes the specified options. +For more information, see [find][06]. + +### config + +The `config` command manages registry keys and values as instances of a [DSC Resource][01]. You can +use it to: + +- Get the current state of a registry key or value +- Test whether a registry key or value is in the desired state +- Set a registry key or value to the desired state. + +For more information, see [config][07]. + +### schema + +The `schema` command returns the JSON schema for an instance of the `Microsoft.Windows/Registry` +DSC Resource. For more information, see [schema][08]. + +### help + +The `help` command returns help information for `registry`, a command, or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +registry help [] +``` + +For example, `registry help config` gets the help for the `config` subcommand. +`registry help config set` gets the help for the `config set` subcommand. + +You can also use the [--help](#-h---help) option on a command to display the help information. For +example, `registry config --help` or `registry config set --help`. + +## Options + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +### -V, --version + + + + +Displays the version of the application. When you specify this option, the application ignores all +options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + + +[01]: ../../../concepts/resources/overview.md +[02]: ../../resources/Microsoft/Windows/Registry/index.md +[03]: ./query/index.md +[04]: ./set/index.md +[05]: ./remove/index.md +[06]: ./find/index.md +[07]: ./config/index.md +[08]: ./schema/index.md diff --git a/docs/reference/tools/registry/query/index.md b/docs/reference/tools/registry/query/index.md new file mode 100644 index 00000000..b1f931c5 --- /dev/null +++ b/docs/reference/tools/registry/query/index.md @@ -0,0 +1,105 @@ +--- +description: Command line reference for the 'registry query' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry query +--- + +# registry query + +## Synopsis + +Query a registry key or value. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry query [Options] --key-path +``` + +## Description + +The `query` command isn't implemented yet. It returns a string that echoes the specified options. + +## Examples + +### Example 1 - Echo the options + + + +The options are returned as a string on a single line. + +```powershell +registry query --key-path HKCU\SYSTEM --recurse +``` + +```Output +Get key_path: HKCU\SYSTEM, value_name: None, recurse: true +``` + +## Options + +### -k, --key-path + + + + +Specifies the registry key path to query. The path must start with a valid hive identifier. Each +segment of the path must be separated by a backslash (`\`). + +The following table describes the valid hive identifiers for the key path. + +| Short Name | Long Name | NT Path | +| :--------: | :-------------------: | :---------------------------------------------------------------------- | +| `HKCR` | `HKEY_CLASSES_ROOT` | `\Registry\Machine\Software\Classes\` | +| `HKCU` | `HKEY_CURRENT_USER` | `\Registry\User\\` | +| `HKLM` | `HKEY_LOCAL_MACHINE` | `\Registry\Machine\` | +| `HKU` | `HKEY_USERS` | `\Registry\User\` | +| `HKCC` | `HKEY_CURRENT_CONFIG` | `\Registry\Machine\System\CurrentControlSet\Hardware Profiles\Current\` | + +```yaml +Type: String +Mandatory: true +``` + +### -v, --value-name + + + + +Defines the name of the value to query for in the specified registry key path. + +```yaml +Type: String +Mandatory: false +``` + +### -r, --recurse + + + + +Indicates whether the command should recursively query subkeys. By default, the command isn't +recursive. + +```yaml +Type: boolean +Mandatory: false +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: boolean +Mandatory: false +``` diff --git a/docs/reference/tools/registry/remove/index.md b/docs/reference/tools/registry/remove/index.md new file mode 100644 index 00000000..ad655a79 --- /dev/null +++ b/docs/reference/tools/registry/remove/index.md @@ -0,0 +1,121 @@ +--- +description: Command line reference for the 'registry remove' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry remove +--- + +# registry remove + +## Synopsis + +Remove a registry key or value. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry remove [Options] --key-path +``` + +## Description + +The `remove` command deletes a registry key or value. The [Microsoft.Windows/Registry] resource +uses this command for the **Delete** resource operation. + +## Examples + +### Example 1 - Remove a registry value + + + +This example deletes the `ExampleValue` value on the `HKCU\Example\Key` registry key. + +```powershell +registry remove --key-path HKCU\Example\Key --value-name ExampleValue +``` + +```Output +{"timestamp":"2025-03-17T20:43:48.472328Z","level":"DEBUG","fields":{"message":"Remove key_path: HKCU\\Example\\Key, value_name: Some(\"ExampleValue\"), recurse: false"},"target":"registry","line_number":47} +``` + +### Example 2 - Remove a registry key recursively + + + +This example deletes the `HKCU\ExampleKey` registry key recursively. The command also deletes any +subkeys or values of the `HKCU\ExampleKey` key. + +```powershell +registry remove --key-path HKCU\Example\Key --recurse +``` + +```Output +{"timestamp":"2025-03-17T20:44:13.597157Z","level":"DEBUG","fields":{"message":"Remove key_path: HKCU\\Example\\Key, value_name: None, recurse: true"},"target":"registry","line_number":47} +``` + +## Options + +### -k, --key-path + + + + +Specifies the registry key path to remove. The path must start with a valid hive identifier. Each +segment of the path must be separated by a backslash (`\`). + +The following table describes the valid hive identifiers for the key path. + +| Short Name | Long Name | NT Path | +| :--------: | :-------------------: | :---------------------------------------------------------------------- | +| `HKCR` | `HKEY_CLASSES_ROOT` | `\Registry\Machine\Software\Classes\` | +| `HKCU` | `HKEY_CURRENT_USER` | `\Registry\User\\` | +| `HKLM` | `HKEY_LOCAL_MACHINE` | `\Registry\Machine\` | +| `HKU` | `HKEY_USERS` | `\Registry\User\` | +| `HKCC` | `HKEY_CURRENT_CONFIG` | `\Registry\Machine\System\CurrentControlSet\Hardware Profiles\Current\` | + +```yaml +Type: String +Mandatory: true +``` + +### -v, --value-name + + + + +Defines the name of the value to remove for in the specified registry key path. + +```yaml +Type: String +Mandatory: false +``` + +### -r, --recurse + + + + +Indicates whether the command should recursively remove subkeys. By default, the command isn't +recursive. + +```yaml +Type: boolean +Mandatory: false +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: boolean +Mandatory: false +``` diff --git a/docs/reference/tools/registry/schema/index.md b/docs/reference/tools/registry/schema/index.md new file mode 100644 index 00000000..6e8062e8 --- /dev/null +++ b/docs/reference/tools/registry/schema/index.md @@ -0,0 +1,88 @@ +--- +description: Command line reference for the 'registry schema' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry schema +--- + +# registry schema + +## Synopsis + +Returns the JSON schema for `Microsoft.Windows/Registry` resource instances. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry schema [Options] +``` + +## Description + +The `schema` command returns the JSON schema for instances of the `Microsoft.Windows/Registry` DSC +Resource. The `registry` command, DSC, and integrating tools use this schema to validate the +properties for resource instances. + +By default, the command outputs the schema as a single line string of JSON. + +For more information about defining an instance of the `Microsoft.Windows/Registry` resource, see +[Microsoft.Windows/Registry][01]. + +## Examples + +### Example 1 - Get the compressed schema + + + +The output is a single line containing the JSON schema without any unquoted whitespace. + +```powershell +registry schema +``` + +### Example 2 - Get the pretty-print schema + + + +With the `--pretty` flag, the output includes whitespace between key-value pairs, newlines after +each key-value pair and array item, and indentation to make the schema easier to read. + +```powershell +registry schema --pretty +``` + +## Options + +### -p, --pretty + + + + +Returns the schema with indentation and newlines between key-value pairs and array items. By +default, the command returns the schema compressed on a single line without any unquoted +whitespace. + +```yaml +Type: boolean +Mandatory: false +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: boolean +Mandatory: false +``` + + +[01]: ../../../resources/Microsoft/Windows/Registry/index.md diff --git a/docs/reference/tools/registry/set/index.md b/docs/reference/tools/registry/set/index.md new file mode 100644 index 00000000..3b469bf4 --- /dev/null +++ b/docs/reference/tools/registry/set/index.md @@ -0,0 +1,92 @@ +--- +description: Command line reference for the 'registry set' command +ms.date: 03/25/2025 +ms.topic: reference +title: registry set +--- + +# registry set + +## Synopsis + +Set a registry key or value. + +> [!IMPORTANT] +> The `registry` command and `Microsoft.Windows/Registry` resource are a proof-of-concept example +> for use with DSCv3. Don't use it in production. + +## Syntax + +```sh +registry set [Options] --key-path --value +``` + +## Description + +The `set` command isn't implemented yet. It returns a string that echoes the specified options. + +## Examples + +### Example 1 - Echo the options + + + +The options are returned as a string on a single line. + +```powershell +registry set --key-path HKCU\example --value hello +``` + +```Output +Set key_path: HKCU\example, value: hello +``` + +## Options + +### -k, --key-path + + + + +Specifies the registry key path to set. The path must start with a valid hive identifier. Each +segment of the path must be separated by a backslash (`\`). + +The following table describes the valid hive identifiers for the key path. + +| Short Name | Long Name | NT Path | +| :--------: | :-------------------: | :---------------------------------------------------------------------- | +| `HKCR` | `HKEY_CLASSES_ROOT` | `\Registry\Machine\Software\Classes\` | +| `HKCU` | `HKEY_CURRENT_USER` | `\Registry\User\\` | +| `HKLM` | `HKEY_LOCAL_MACHINE` | `\Registry\Machine\` | +| `HKU` | `HKEY_USERS` | `\Registry\User\` | +| `HKCC` | `HKEY_CURRENT_CONFIG` | `\Registry\Machine\System\CurrentControlSet\Hardware Profiles\Current\` | + +```yaml +Type: String +Mandatory: true +``` + +### -v, --value + + + + +Defines the name of the value to set for in the specified registry key path. + +```yaml +Type: String +Mandatory: false +``` + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: boolean +Mandatory: false +```