diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
index daccd6c..9fabfde 100644
--- a/.openpublishing.redirection.json
+++ b/.openpublishing.redirection.json
@@ -40,10 +40,170 @@
"redirect_url": "/powershell/dsc/concepts/glossary?view=dsc-2.0",
"redirect_document_id": true
},
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.md",
+ "redirect_url": "/powershell/dsc/get-started",
+ "redirect_document_id": false
+ },
{
"source_path": "dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/provider.md",
"redirect_url": "/powershell/dsc/reference/schemas/resource/manifest/adapter",
"redirect_document_id": true
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md",
+ "redirect_url": "/powershell/dsc/concepts/resources/anatomy",
+ "redirect_document_id": true
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/overview.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/OSInfo",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/cli/osinfo.md",
+ "redirect_url": "/powershell/dsc/reference/tools/osinfo",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/resource.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/OSInfo",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-in-a-configuration.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-with-dsc-resource.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/overview.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/Windows/Registry",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/resource.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/Windows/Registry",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/registry.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/get.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/config/get",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/set.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/config/set",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/test.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/config",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/config",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/find/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/find",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/query/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/query",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/remove/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/remove",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/schema/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/schema",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/set/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry/set",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/test/command.md",
+ "redirect_url": "/powershell/dsc/reference/tools/registry",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md",
+ "redirect_url": "/powershell/dsc/reference/cli/config",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md",
+ "redirect_url": "/powershell/dsc/reference/cli/completer",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md",
+ "redirect_url": "/powershell/dsc/reference/cli/config",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/cli/resource/command.md",
+ "redirect_url": "/powershell/dsc/reference/cli/resource",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md",
+ "redirect_url": "/powershell/dsc/reference/cli/schema",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/configure-registry-keys-and-values.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-key.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-value.md",
+ "redirect_url": "/powershell/dsc/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/resources/samples/overview.md",
+ "redirect_url": "/powershell/dsc/tutorials/resources/authoring/overview",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/resources/tutorials/overview.md",
+ "redirect_url": "/powershell/dsc/tutorials/resources/authoring/overview",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/resources/samples/first-resource/overview.md",
+ "redirect_url": "/powershell/dsc/tutorials/resources/authoring/first-resource/overview",
+ "redirect_document_id": false
+ },
+ {
+ "source_path": "dsc/docs-conceptual/dsc-3.0/resources/tutorials/first-resource/overview.md",
+ "redirect_url": "/powershell/dsc/tutorials/resources/authoring/first-resource/overview",
+ "redirect_document_id": false
}
]
}
\ No newline at end of file
diff --git a/dsc/docs-conceptual/dsc-3.0/changelog.md b/dsc/docs-conceptual/dsc-3.0/changelog.md
index b695665..6633d01 100644
--- a/dsc/docs-conceptual/dsc-3.0/changelog.md
+++ b/dsc/docs-conceptual/dsc-3.0/changelog.md
@@ -1,9 +1,9 @@
---
title: "Desired State Configuration changelog"
description: >-
- A log of the changes for releases of DSCv3.
+ A log of the changes for releases of DSC.
ms.topic: whats-new
-ms.date: 06/24/2024
+ms.date: 03/25/2025
---
# Changelog
@@ -33,20 +33,24 @@ ms.date: 06/24/2024
you from the work item ID.
-->
-All notable changes to DSCv3 are documented in this file. The format is based on
-[Keep a Changelog][m1], and DSCv3 adheres to [Semantic Versioning][m2].
+All notable changes to DSC after the `3.0.0` release are documented in this file. The format is
+based on [Keep a Changelog][m1], and DSC adheres to [Semantic Versioning][m2].
+
+To see the changes for the earlier development of DSC before version `3.0.0`, see the
+[DSC prerelease changelog][m3] on GitHub.
[m1]: https://keepachangelog.com/en/1.1.0/
[m2]: https://semver.org/spec/v2.0.0.html
+[m3]: https://github.com/PowerShell/DSC/blob/main/CHANGELOG.md
-## Unreleased
+
-[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.8...main
+
+[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0...main -->
-## [v3.0.0-preview.8][release-v3.0.0-preview.8] - 2024-06-19
-
-This section includes a summary of changes for the `preview.8` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-preview.8].
-
-
-[release-v3.0.0-preview.8]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-preview.8 "Link to the DSC v3.0.0-preview.8 release on GitHub"
-[compare-v3.0.0-preview.8]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.7...v3.0.0-preview.8
-
-### Changed
-
-- Changed the `Microsoft.DSC/PowerShell` adapter to only handle PowerShell DSC Resources
- implemented as classes. The `Microsoft.Windows/WindowsPowerShell` adapter continues to work with
- classic PSDSC resources. Neither adapter supports composite PSDSC resources. This change
- simplified the code and coincided with ensuring that the `Microsoft.DSC/PowerShell` adapter works
- correctly on Linux and macOS as well as Windows. This change also brought performance
- improvements to the adapter, speeding up resource invocation and discovery.
-
- Related work items
-
- - Issues: _None_.
- - PRs:
- - [#435][#435]
- - [#439][#439]
-
-
-
-### Added
-
-- Added the [`--what-if` (`-w`)][p8-01] option to the [dsc config set][cmd-cset] command. When you
- call `dsc config set` with the `--what-if` option, DSC doesn't actually invoke the resources to
- enforce the desired state. Instead, it returns the expected output for the command, showing the
- before and after state for each resource instance.
-
- The output for the `dsc config set` operation with the `--what-if` operation is the same as an
- [actual configuration set operation][p8-02], except that the metadata field
- [executionType][p8-03] is set to `WhatIf` instead of `Actual`.
-
- By default, the generated output is synthetic, based on the results of the resources' `test`
- operation. Resources can define the [whatIf][p8-04] property in their resource manifest to
- participate in what-if operations, reporting more specifically how they will change the system.
- For example, participating resources could indicate whether an actual set operation will require
- a reboot or whether the current user has the correct permissions to manage that resource
- instance.
-
- Participating resources have the [WhatIf capability][p8-05].
-
- Related work items
-
- - Issues: [#70][#70]
- - PRs:
- - [#400][#400]
- - [#441][#441]
-
-
-
-- Added support for [importer resources][p8-06]. These resources resolve external sources to a
- nested DSC Configuration document. The resolved instances are processed as nested resource
- instances.
-
- This required some updates to the schemas, all backwards-compatible:
-
- - Added a new [resourceKind][p8-07] named `Import`.
- - Added the [resolve][p8-08] command to resource manifests.
- - Added the new [`Resolve`][p8-09] capability, returned in the output for the
- [dsc resource list][cmd-rlist] command when DSC discovers an importer resource.
-
- Related work items
-
- - Issues: [#429][#429]
- - PRs:
- - [#412][#412]
- - [#464][#464]
-
-
-
-- Added the `Microsoft.DSC/Include` importer resource to resolve instances from an external
- configuration document. The resolved instances are processed as nested instances for the
- `Microsoft.DSC/Include` resource instance.
-
- You can use this resource to write smaller configuration documents and compose them as needed.
- For example, you could define a security baseline and a web server configuration separately, then
- combine them for a given application:
-
- ```yaml
- $schema: &schema https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
- resources:
- # Group of included baseline configurations
- - name: Baselines
- type: Microsoft.DSC/Group
- properties:
- $schema: *schema
- resources:
- - name: Security Baseline
- type: Microsoft.DSC/Include
- properties:
- configurationFile: security_baseline.dsc.yaml
- parametersFile: security_baseline.parameters.yaml
- - name: Web Server Baseline
- type: Microsoft.DSC/Include
- properties:
- configurationFile: web_baseline.dsc.yaml
- parametersFile: web_baseline.parameters.yaml
- dependsOn:
- - "[resourceId('Microsoft.DSC/Include', 'Security Baseline')]"
-
- # application configuration instances, all depend on the baselines
- - name: Application configuration
- type: MyApp/Settings
- properties:
- someSetting: someValue
- dependsOn:
- - "[resourceId('Microsoft.DSC/Group', 'Baselines')]"
- ```
-
- Related work items
-
- - Issues: [#429][#429]
- - PRs: [#412][#412]
-
-
-
-- Added caching for PowerShell Desired State Configuration (PSDSC) resources when using the
- `Microsoft.DSC/PowerShell` and `Microsoft.Windows/PowerShell` adapters. The adapters use the
- cache to speed up resource discovery. The performance improvement reduced the resource list time
- under tests from eight seconds to two seconds, and reduced invocation operation times by half.
-
- The adapters cache the resources in the following locations, depending on your platform:
-
- | Adapter | Platform | Path |
- | :----------------------------: | :------: | :---------------------------------------------- |
- | `Microsoft.DSC/PowerShell` | Linux | `$HOME/.dsc/PSAdapterCache.json` |
- | `Microsoft.DSC/PowerShell` | macOS | `$HOME/.dsc/PSAdapterCache.json` |
- | `Microsoft.DSC/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` |
- | `Microsoft.Windows/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` |
-
- The adapters check whether the cache is stale on each run and refresh it if:
-
- - The `PSModulePath` environmental variable is updated.
- - Any module is added or removed from the `PSModulePath`.
- - Any related files in a cached PSDSC resource module has been updated since the cache was
- written. The adapter watches the `LastWriteTime` of module files with the following extensions:
- `.ps1`, `.psd1`, `.psm1`, and `.mof`.
-
- Related work items
-
- - Issues: [#371][#371]
- - PRs: [#432][#432]
-
-
-
-- Added the `DSC.PackageManagement/Apt` resource for managing software on systems that use the
- advanced package tool (APT). In this release, you can use the resource to:
-
- - Install the latest version of a package.
- - Uninstall a package.
- - Get the current state of a package.
- - Export every installed package as a DSC resource instance.
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#434][#434]
-
-
-
-- Added the `Microsoft.DSC.Experimental/SystemctlService` class-based PSDSC resource. It has the
- `Get` and `Export` [capabilities][p8-10]. You can use it on Linux systems that manage services
- with SystemD and `systemctl`. In this release, it doesn't support setting services.
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#454][#454]
-
-
-
-### Fixed
-
-- Fixed the JSON Schema for [exit codes][p8-11] in the resource manifest to support negative
- integers. Prior to this release, the DSC engine supported negative exit codes but the JSON Schema
- forbid them.
-
- Related work items
-
- - Issues: [#407][#407]
- - PRs: [#410][#410]
-
-
-
-- Fixed the behavior of the [int()][int()] configuration function to error when given an input
- value other than a string or integer. Prior to this release, when you specified a number with
- a fractional part as input for the function, it coerced the input value to an integer representing
- the fractional part. Starting with this release, the `int()` function raises an invalid input
- error when the input value isn't a string or an integer.
-
- Related work items
-
- - Issues: [#390][#390]
- - PRs: [#438][#438]
-
-
-
-- Fixed the implementation to retrieve non-zero exit code descriptions for resource errors from the
- resource manifest, if defined. Prior to this release, these error descriptions weren't surfaced.
-
- Related work items
-
- - Issues: [#431][#431]
- - PRs: [#444][#444]
-
-
-
-
-[p8-01]: reference/cli/config/set.md#-w---what-if
-[p8-02]: reference/schemas/outputs/config/set.md
-[p8-03]: reference/schemas/metadata/Microsoft.DSC/properties.md#executiontype
-[p8-04]: reference/schemas/resource/manifest/whatif.md
-[p8-05]: reference/schemas/outputs/resource/list.md#capability-whatif
-[p8-06]: reference/schemas/definitions/resourceKind.md#importer-resources
-[p8-07]: reference/schemas/definitions/resourceKind.md
-[p8-08]: reference/schemas/resource/manifest/resolve.md
-[p8-09]: reference/schemas/outputs/resource/list.md#capability-resolve
-[p8-10]: reference/schemas/outputs/resource/list.md#capabilities
-[p8-11]: reference/schemas/resource/manifest/root.md#exitcodes
-
-## [v3.0.0-preview.7][release-v3.0.0-preview.7] - 2024-04-22
-
-This section includes a summary of changes for the `preview.7` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-preview.7].
-
-
-[release-v3.0.0-preview.7]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-preview.7 "Link to the DSC v3.0.0-preview.7 release on GitHub"
-[compare-v3.0.0-preview.7]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...v3.0.0-preview.7
-
-### Changed
-
-- The version segment of the schema URIs for DSC have been updated from `2023/10` to `2024/04` to
- accommodate breaking schema changes from the schemas that `alpha.5` used. You can find more
- information about the specific changes to the schemas in the following changelog entries:
-
- - [Renamed 'providers' to 'adapters'](#rename-provider-to-adapter)
- - [Added the 'delete' operation for resources](#add-delete-operation)
- - [Added the option to specify a required security context for a configuration document](#add-elevation-requirement)
- - [Add option to specify a JSON input argument for resource commands](#add-json-input-arg)
- - [Add 'kind' property to resource manifests](#add-kind-property)
- - [Camel-cased 'SecureObject' and 'SecureString' parameter types](#camel-casing-secure-types)
- - [Add 'capabilities' to 'dsc resource list' output](#add-capabilities)
- - [Added metadata to config and resource output](#add-metadata-output)
-
- Update your configuration documents and resource manifests to use the following URIs for the
- `$schema` keyword:
-
- ```yaml
- Canonical URI for configuration documents: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
-
- Bundled URI for configuration documents: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json
-
- Enhanced Authoring in VS Code URI for configuration documents: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json
-
- Canonical URI for resource manifests: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
-
- Bundled URI for resource manifests: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
-
- Enhanced Authoring in VS Code URI for resource manifests: >-
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
- ```
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#397][#397]
-
-
-
-- In this release, the term `DSC Resource Provider` is
- replaced with the more semantically accurate `DSC Resource Adapter`. These resources enable users
- to leverage resources that don't define a DSC Resource Manifest with DSC, like PSDSC resources -
- they're _adapters_ between DSCv3 and resources defined in a different way.
-
- Beyond using different terminology in the documentation, this change also renamed the resource
- manifest property `provider` to [adapter][p7-01], and the `requires` property in the output for
- `dsc resource list` has been renamed to [requireAdapter][p7-02].
-
- Related work items
-
- - Issues: [#310][#310]
- - PRs:
- - [#334][#334]
- - [#373][#373]
-
-
-
-- Changed the casing for the [parameter type enums][p7-03]
- from `SecureString` to `secureString` and `SecureObject` to `secureObject`, to better match the
- type enumerations in ARM.
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#364][#364]
-
-
-
-- The [envvar()][envvar()] function now raises an error when the specified environment variable
- doesn't exist instead of returning an empty string. This change helps reduce unexpected and
- difficult to diagnose errors when a configuration expects a value from the environment variable.
-
- Related work items
-
- - Issues: [#336][#336]
- - PRs: [#358][#358]
-
-
-
-- Renamed the `DscConfigRoot` environment variable to `DSC_CONFIG_ROOT`. DSC now correctly
- absolutizes the variable, even when the path to a configuration document is a relative path. DSC
- also raises a warning when you define the environment variable outside of DSC before overriding
- it.
-
- Related work items
-
- - Issues:
- - [#317][#317]
- - [#335][#335]
- - PRs: [#342][#342]
-
-
-
-- Updated the default behavior of the [dsc resource list][cmd-rlist] command and added the new
- [--adapter][p7-04] option to the command.
-
- Prior to this release, the command always called the `list` command for any discovered adapters,
- even when searching for a non-adapted resource by name. Enumerating the adapted resources can be
- a slow process, so the command no longer calls the adapters to list their adapted resources by
- default.
-
- Instead, you can use the `--adapter` option to specify a filter for the adapters you want to list
- adapted resources for. Specify the fully qualified type name of an adapter or a string including
- wildcards (`*`) to use as a filter for adapter names. You can specify the filter `*` to have DSC
- call the `list` operation for every discovered adapter, returning all adapted resources.
-
- For more information, see [dsc resource list][cmd-rlist].
-
- Related work items
-
- - Issues:
- - [#274][#274]
- - [#368][#368]
- - PRs: [#377][#377]
-
-
-
-- Updated the table view for the [dsc resource list][cmd-rlist] command to display the resource
- kind and capabilities. The capabilities column in the table uses bit flags for the display to
- keep the column width manageable.
-
- For more information, see the "Output" section of [dsc resource list][cmd-rlist].
-
- Related work items
-
- - Issues: [#329][#329]
- - PRs: [#346][#346]
-
-
-
-### Added
-
-- Added the [dsc resource delete][cmd-rdelete] command and the
- [delete][p7-05] operation property to the resource manifest. Prior to this release, resources had
- to handle deleting resources as part of their `set` operation, and the development guidance was
- to use the [_exist][p7-06] standard property to indicate whether a resource should exist.
-
- Now, resource authors can indicate through the resource manifest whether the resource supports
- the `delete` operation with a separate command or as part of the `set` operation. It can be
- simpler to implement a separate `delete` operation than to handle deleting instances as part of
- `set`. You can implement your resource to have an explicit `delete` command and handle deleting
- instances as part of a `set` operation.
-
- You can also use the `dsc resource delete` command to delete instances one at a time. For this
- command, the JSON input defines the filter to pass to the resource for deleting the instance. For
- more information, see [dsc resource delete command reference][cmd-rdelete].
-
- If your resource handles deleting instances as part of `set`, use the [handlesExist][p7-07]
- property to tell DSC so. When this property is `true`, the resource has the
- [SetHandlesExist capability][p7-08].
-
- If your resource has a separate command for deleting instances, use the [delete][p7-05] property
- in your resource manifest to tell DSC and other tools how to invoke the operation. When this
- property is defined, the resource has the [Delete capability][p7-09].
-
- If your resource handles deleting instances, you should add the `_exist` standard property to the
- resource's [instance schema][p7-10]. While you can use any property name for this, DSC is only aware of
- deletion operations when you use the `_exist` property. DSC won't know to call the `delete`
- operation for resources that don't have the [SetHandlesExist][p7-08] capability.
-
- For resources that implement `delete` but don't handle `_exist` in the `set` operation, DSC can
- now invoke the delete operation as-needed in a configuration whenever it enforces the desired
- state for an instance of a resource with the `_exist` property set to `false`.
-
- Related work items
-
- - Issues: [#290][#290]
- - PRs:
- - [#379][#379]
- - [#382][#382]
-
-
-
-- Added the option to specify whether a configuration
- document requires root or elevated permissions. Now, you can define the `securityContext`
- metadata property under the `Microsoft.DSC` namespace in a configuration document to specify
- which security context to use:
-
- - `Current` - Any security context. This is the default if you don't specify this property in a
- configuration document.
- - `Elevated` - Elevated as root or an administrator.
- - `Restricted` - Not elevated as root or an administrator.
-
- For example, the following metadata at the top of a configuration document indicates that DSC
- must run as a normal user account, not root or administrator:
-
- ```yaml
- metadata:
- Microsoft.DSC:
- securityContext: restricted
- ```
-
- For more information, see [DSC Configuration document metadata schema][p7-11].
-
- Related work items
-
- - Issues: [#258][#258]
- - PRs: [#351][#351]
-
-
-
-- Added the option to define a JSON input argument for resource
- commands. When you define the `args` list for the following commands, you can now define a
- special argument that the command expects to receive the compressed JSON data for:
-
- - [delete][p7-12]
- - [export][p7-13]
- - [get][p7-14]
- - [set][p7-15]
- - [test][p7-16]
- - [validate][p7-17]
-
- DSC sends data to these commands in three ways:
-
- 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed
- JSON object without spaces or newlines between the object properties.
- 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment
- variable for each property in the input data object, using the name and value of the property.
- 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a
- string representing the data as a compressed JSON object to the specified argument.
-
- If you don't define the `input` property and don't define a JSON input argument, DSC can't pass
- the input JSON to the resource. You can only define one JSON input argument for a command.
-
- You must define the `input` property, one JSON input argument in the `args` property array, or
- both. For more information, see the relevant schema documentation for the command property.
-
- Related work items
-
- - Issues: [#218][#218]
- - PRs: [#385][#385]
-
-
-
-- Added configuration functions:
-
- - New mathematics functions include [add()][add()], [div()][div()], [max()][max()],
- [min()][min()], [mod()][mod()], [mul()][mul()], and [sub()][sub()]. The mathematics functions
- only operate on integer values.
-
- - The [reference()][reference()] function enables you to reference the result output for other
- resources, so you can use properties of one resource instance as values for another. The
- `reference()` function only works for resources that DSC has already managed in a
- configuration. You should always add the resource you're referencing with the `reference()`
- function to the [dependsOn][p7-18] list for the instance using the reference.
-
- - The [createArray()][createArray()] function enables you to create arrays of a given type from
- values.
-
- - The [int()][int()] function enables you to convert strings and numbers with fractional parts
- into integers.
-
- Related work items
-
- - Issues:
- - [#57][#57]
- - PRs:
- - [#347][#347]
- - [#349][#349]
- - [#352][#352]
- - [#353][#353]
- - [#354][#354]
- - [#360][#360]
- - [#361][#361]
- - [#375][#375]
- - [#376][#376]
-
-
-
-- Added the [kind][p7-19] property to the resource manifest schema
- and the [output][p7-20] for the [dsc resource list][cmd-rlist] command. This property indicates
- whether the resource is a [group resource][p7-21] (`Group`), an [adapter resource][p7-22]
- (`Adapter`), or neither (`Resource`). For more information, see
- [DSC Resource kind schema reference][p7-23].
-
- This property is mandatory in the resource manifest for group resources. If your resource
- manifest doesn't define the `kind` property, DSC can infer whether the resource is an adapter
- resource or not. Microsoft recommends always explicitly defining this property in resource
- manifests, because the schema can apply enhanced validation based on the value of the `kind`
- property.
-
- Related work items
-
- - Issues: [#139][#139]
- - PRs: [#338][#338]
-
-
-
-- Added the [capabilities][p7-24] property to the output for the
- [dsc resource list][cmd-rlist] command. The `capabilities` property indicates how you can use the
- DSC Resource and how DSC and other higher order tools should handle it.
-
- Related work items
-
- - Issues: [#356][#356]
- - PRs: [#357][#357]
-
-
-
-- Added the `metadata` property to the outputs for `dsc config`
- and `dsc resource` subcommands. This property in the output defines the context DSC was run under
- and information about the operation. See the output reference for each command for more
- information:
-
- - [dsc config get][p7-25]
- - [dsc config test][p7-26]
- - [dsc config set][p7-27]
- - [dsc resource get][p7-28]
- - [dsc resource test][p7-29]
- - [dsc resource set][p7-30]
-
- Related work items
-
- - Issues: [#401][#401]
- - PRs: [#405][#405]
-
-
-
-- Added parsing for [configuration functions][cfuncs] in the [default values][p7-31] of parameters.
- Prior to this release, DSC interpreted configuration functions in parameter default values as
- literal strings.
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#364][#364]
-
-
-
-- Added type validation for parameter [default values][p7-31]. Prior to this release, DSC didn't
- validate that the default value for a parameter was valid for the parameter's [type][p7-32].
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#364]
-
-
-
-- Added support for resources to send trace information to DSC during command execution. DSC
- Resources can emit JSON objects to stderr. If the object has a property in the following list
- with a string value, DSC interprets the emitted object as a message of the matching level:
- `Error`, `Warning`, `Info`, `Debug`, `Trace`.
-
- For example, DSC would interpret a resource emitting the following JSON to stderr as a warning:
-
- ```json
- {"Warning":"Unable to access remote store, using cached local package data only"}
- ```
-
- DSC emits these messages along with its own messages when the specified trace level for the
- command is equal to or lower than the message's level.
-
- For more information about trace levels, see the [--trace-level][p7-33] option for the
- [dsc][cmd] root command.
-
- Related work items
-
- - Issues: [#89][#89]
- - PRs: [#287][#287]
-
-
-
-- Added validation to ensure resources return data for their instances that is valid against their
- own instance JSON schema. Prior to this release, the return data wasn't validated.
-
- Related work items
-
- - Issues: [#251][#251]
- - PRs: [#362][#362]
-
-
-
-- Added multi-line progress bars for the `dsc resource list` command to provide feedback to
- interactive users about the resource discovery process. Prior to this release, the command
- executed silently.
-
- Related work items
-
- - Issues: _None_.
- - PRs: [#323][#323]
-
-
-
-- Added functionality to insert metadata for adapter resources to indicate if the incoming data is
- for a configuration instead of direct resource invocation. Prior to this release, adapters had no
- way of discerning between a single-instance call for a configuration and a direct resource
- invocation.
-
- With this change, DSC inserts the following into the data object sent to the adapter during a
- `dsc config` command:
-
- ```json
- "metadata": {
- "Microsoft.DSC": {
- "context": "Configuration"
- }
- }
- ```
-
- Adapters can then check whether this value is set in the input data and handle it as-needed.
-
- Related work items
-
- - Issues: [#253][#253]
- - PRs: [#348][#348]
-
-
-
-- Added the `Microsoft.Windows/RebootPending` resource, which checks whether a Windows machine has
- a pending reboot. It can only be used for assertions, not to enforce state.
-
- Related work items
-
- - Issues: [#333][#333]
- - PRs: [#344][#344]
-
-
-
-- Added the `Microsoft.DSC.Transitional/RunCommandOnSet` resource, which runs a specified
- executable or script with given arguments during a `set` operation. This resource is intended as
- a temporary transitional resource while migrating to DSCv3 and implementing resources for your
- needs.
-
- Related work items
-
- - Issues: [#302][#302]
- - PRs: [#321][#321]
-
-
-
-
-[p7-01]: reference/schemas/resource/manifest/adapter.md
-[p7-02]: reference/schemas/outputs/resource/list.md#requireadapter
-[p7-03]: reference/schemas/definitions/parameters/dataTypes.md
-[p7-04]: reference/cli/resource/list.md#-a---adapter
-[p7-05]: reference/schemas/resource/manifest/delete.md
-[p7-06]: reference/schemas/resource/properties/exist.md
-[p7-07]: reference/schemas/resource/manifest/set.md#handlesexist
-[p7-08]: reference/schemas/outputs/resource/list.md#capability-sethandlesexist
-[p7-09]: reference/schemas/outputs/resource/list.md#capability-delete
-[p7-10]: reference/schemas/resource/manifest/root.md#schema-1
-[p7-11]: reference/schemas/config/metadata.md
-[p7-12]: reference/schemas/resource/manifest/delete.md#json-input-argument
-[p7-13]: reference/schemas/resource/manifest/export.md#json-input-argument
-[p7-14]: reference/schemas/resource/manifest/get.md#json-input-argument
-[p7-15]: reference/schemas/resource/manifest/set.md#json-input-argument
-[p7-16]: reference/schemas/resource/manifest/test.md#json-input-argument
-[p7-17]: reference/schemas/resource/manifest/validate.md#json-input-argument
-[p7-18]: reference/schemas/config/resource.md#dependson
-[p7-19]: reference/schemas/resource/manifest/root.md#kind
-[p7-20]: reference/schemas/outputs/resource/list.md
-[p7-21]: reference/schemas/definitions/resourceKind.md#group-resources
-[p7-22]: reference/schemas/definitions/resourceKind.md#adapter-resources
-[p7-23]: reference/schemas/definitions/resourceKind.md
-[p7-24]: reference/schemas/outputs/resource/list.md#capabilities
-[p7-25]: reference/schemas/outputs/config/get.md#metadata-1
-[p7-26]: reference/schemas/outputs/config/test.md#metadata-1
-[p7-27]: reference/schemas/outputs/config/set.md#metadata-1
-[p7-28]: reference/schemas/outputs/resource/get.md#metadata-1
-[p7-29]: reference/schemas/outputs/resource/test.md#metadata-1
-[p7-30]: reference/schemas/outputs/resource/set.md#metadata-1
-[p7-31]: reference/schemas/config/parameter.md#defaultvalue
-[p7-32]: reference/schemas/config/parameter.md#type
-[p7-33]: reference/cli/dsc.md#-l---trace-level
-
-## [v3.0.0-alpha.5][release-v3.0.0-alpha.5] - 2024-02-27
-
-This section includes a summary of changes for the `alpha.5` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5].
-
-
-[release-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.5 "Link to the DSC v3.0.0-alpha.5 release on GitHub"
-[compare-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...v3.0.0-alpha.5
-
-### Changed
-
-- Updated the options for the `dsc` root command:
+## [v3.0.0][release-v3.0.0] - 2025-02-28
- - Removed the global `--format` option, which controls the output format. Now, the relevant
- subcommands that return formattable output have the `--format` option (short option as `-f`)
- added to them.
- - Removed the global `--input` and `--input-file` options. Now, the `config` subcommands have the
- `--document` and `--path` options for specifying the configuration document as a string or from
- a file. The relevant `resource` subcommands have the `--input` and `--path` options for
- specifying the instance properties as a string or from a file.
- - The `--logging-level` option is renamed to [--trace-level][a5.05] with the short name `-l`. The
- default trace level is now `warning` instead of `info`.
- - Added the [--trace-format][a5.06] option with the `-f` short name. This option enables you to
- choose the format for the trace messages emitted to stderr. By default, the messages are
- emitted as lines of text with console colors. You can set this option to `plaintext` to emit
- the messages without console colors or to `json` to emit the messages as JSON objects.
-
- The trace messaging is also updated to only emit source files and line numbers for the `debug`
- and `trace` levels.
-
- Related work items
-
- - Issues:
- - [#286][#286]
- - [#227][#227]
- - [#226][#226]
- - PRs:
- - [#299][#299]
- - [#303][#303]
- - [#305][#305]
- - [#388][#388]
-
-
-
-- Updated the JSON schemas for the [get][a5.07], [set][a5.08], and [test][a5.09] output data. This
- change corrects an issue with how DSC surfaced information about instances nested inside group
- and adapter resources. Now when you review the output, you'll be able to see the results for each
- nested instance instead of a confusing object that loses the nested instance type and name
- information.
-
- This schema change is backwards compatible.
-
- Related work items
-
- - Issues:
- - [#165][#165]
- - [#266][#266]
- - [#284][#284]
- - PRs: [#318][#318]
-
- Related work items
-
- - Issues: [#271][#271]
- - PRs: [#322][#322]
-
- Related work items
-
- - Issues: [#49][#49]
- - PRs:
- - [#291][#291]
- - [#294][#294]
-
-
-
-- Added support for authoring DSC Resource manifests in YAML. DSC now recognizes resource manifests
- that use the `.dsc.resource.yml` or `.dsc.resource.yaml` file extension instead of only
- `.dsc.resource.json`.
-
- Related work Items
-
- - Issues: [#129][#129]
- - PRs: [#311][#311]
-
-
-
-- Added the [DSCConfigRoot][a5.11] environment variable and the
- [envvar() configuration function][a5.12] to enable users to reference files and folders relative
- to the folder containing the configuration document. DSC automatically and only creates the
- `DSCConfigRoot` environment variable when you use the `--path` option to specify the
- configuration document instead of passing the document as a string from stdin or with the
- `--document` option.
-
- > [!NOTE]
- > In this release, DSC doesn't expand the specified path to an absolute path. You should always
- > specify the full path to the configuration document if you want to reference the
- > `DSCConfigRoot` variable in your configuration. Further, DSC always sets the value for this
- > environment variable when you use the `--path` option. If the environment variable is already
- > set, it overrides it silently.
- >
- > In a future release, the variable will be renamed to `DSC_CONFIG_ROOT` and DSC will
- > automatically expand relative paths into absolute paths when setting the environment variable.
- > It will also emit a warning when it overrides the variable.
-
- Related work Items
-
- - Issues: [#75][#75]
- - PRs: [#313][#313]
-
-
-
-- Added support for using the [dsc config export][cmd-cexport] and
- [dsc resource export][cmd-rexport] commands with the PowerShell adapter resource. PSDSC resources
- can now participate in the `export` command if they define a static method that returns an array
- of the PSDSC resource class.
-
- Related work Items
-
- - Issues: [#183][#183]
- - PRs: [#307][#307]
-
-
-
-- Added the `methods` column to the default table view for the console output of the
- [dsc resource list][cmd-rlist] command. This new column indicates which methods the resource
- explicitly implements. Valid values include `get`, `set`, `test`, and `export`. This information
- is only available in the table view. It isn't part of the output object for the command. If you
- use the [--format][a5.16] parameter, capture the command output, or redirect the output, the
- `methods` information isn't included.
-
- Resources that don't implement `test` rely on DSC's synthetic test behavior instead. They can
- still be used for test and set operations.
-
- Resources that don't implement `export` can't be used with the `dsc config export` or
- `dsc resource export` commands.
-
- Resources that don't implement `set` can be used for auditing, but not `dsc resource set`. They
- can be used with the `dsc config set` command, but only if they're nested inside a
- `DSC/AssertionGroup` instance.
-
- Related work Items
-
- - Issues: [#309][#309]
- - PRs: [#314][#314]
-
-
-
-- Added an prototype for a WMI resource adapter to enable users to query WMI. The adapter is
- disabled by default, as enumerating the WMI resources can have a performance impact. To enable
- it, rename the resource manifest from `wmigroup.dsc.resource.json.optout` to
- `wmigroup.dsc.resource.json`.
-
- Related work Items
-
- - Issues: [#263][#263]
- - PRs: [#279][#279]
-
-
-
-
-[a5.01]: reference/schemas/config/functions/parameters.md
-[a5.02]: reference/cli/config/command.md#-p---parameters
-[a5.03]: reference/cli/config/command.md#-f---parameters_file
-[a5.04]: reference/cli/config/command.md
-[a5.05]: reference/cli/dsc.md#-l---trace-level
-[a5.06]: reference/cli/dsc.md#-f---trace-format
-[a5.07]: reference/schemas/outputs/resource/get.md
-[a5.08]: reference/schemas/outputs/resource/set.md
-[a5.09]: reference/schemas/outputs/resource/test.md
-[a5.10]: reference/schemas/config/functions/concat.md
-[a5.11]: reference/cli/config/command.md#environment-variables
-[a5.12]: reference/schemas/config/functions/envvar.md
-[a5.16]: reference/cli/resource/list.md#-f---format
-
-## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14
-
-This section includes a summary of changes for the `alpha.4` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4].
-
-
-[release-v3.0.0-alpha.4]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.4 "Link to the DSC v3.0.0-alpha.4 release on GitHub"
-[compare-v3.0.0-alpha.4]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.3...v3.0.0-alpha.4
-
-### Changed
-
-- Updated the canonical version of the schema URIs from `2023/08` to `2023/10`, as this release
- includes breaking changes for the schemas.
-
- As part of this change, the `$schema` keyword for both [configuration documents][a4.01] and
- [resource manifests][a4.02] accepts any valid URI for the schemas, instead of only one. Now, you
- can set the value for the keyword to the unbundled schema, the bundled schema, or the enhanced
- authoring schema for any supported version.
-
-- Replaced the `_ensure` well-known property with the boolean [_exist][a4.03] property. This
- improves the semantics for users and simplifies implementation for resources, replacing the
- string enum values `Present` and `Absent` with `true` and `false` respectively.
-
- Related work items
-
- - Issues: [#202][#202]
- - PRs: [#206][#206]
-
-
-
-- Updated the `Microsoft.Windows/Registry` resource to use the `_exist` property instead of
- `_ensure` and updated the output to be idiomatic for a DSC Resource.
-
- Related work items
-
- - Issues: [#162][#162]
- - PRs: [#206][#206]
-
-
-
-- When a user presses the Ctrl+C key combination, DSC now recursively
- terminates all child processes before exiting. This helps prevent dangling processes that were
- previously unhandled by the interrupt event.
-
- Related work items
-
- - PRs: [#213][#213]
-
-
-
-### Added
-
-- Added the `--input` and `--input-file` global options to the root `dsc` command. Now, you
- can pass input to DSC from a variable or file instead of piping from stdin.
-
- Related work items
-
- - Issues: [#130][#130]
- - PRs: [#217][#217]
-
-
-
-- Added the `arg` value as an option for defining how a command-based DSC Resource expects to
- receive input. This enables resource authors to define resources that handle DSC passing the
- instance JSON as an argument.
-
- Related work items
-
- - PRs: [#213][#213]
-
-
-
-- Added the new [completer][a4.04] command enables users to add shell completions for DSC to their
- shell. The command supports completions for Bash, Elvish, fish, PowerShell, and ZSH.
-
- Related work items
-
- - Issues: [#186][#186]
- - PRs: [#216][#216]
-
-
-
-- DSC now emits log messages to the stderr stream. This can make it easier to understand what DSC
- is doing. This doesn't affect the data output. By default, DSC emits errors, warnings, and
- informational messages, but not debug or trace messaging. You can control the level of the
- logging with the new `--logging-level` option on the root `dsc` command.
-
- Related work items
-
- - Issues:
- - [#107][#107]
- - [#158][#158]
- - PRs:
- - [#211][#211]
- - [#248][#248]
-
-
-
-- Added optimizations for the resource discovery process that runs before most `dsc` commands.
- These optimizations significantly reduce the command execution duration, especially for the
- `dsc resource *` commands, which rarely need to run a full discovery for resources.
-
- Related work items
-
- - Issues: [#173][#173]
- - PRs: [#240][#240]
-
-
-
-- Added initial [configuration document functions][a4.05] to DSC. You can now use the
- [base64()][a4.06], [concat()][a4.07], and [resourceId()][a4.08] functions in the configuration
- document.
-
- > [!NOTE]
- > The `resourceId` function has been reimplemented as a document function instead of a special
- > case, but it has the same functionality and parameters.
-
- Related work items
-
- - Issues: [#57][#57]
- - PRs:
- - [#241][#241]
- - [#252][#252]
-
-
-
-### Fixed
-
-- The `--format` option now works as users expect when the output is redirected or saved to a
- variable. Before this fix, DSC always returned JSON output, even when the user wanted to save
- the output as YAML. With this fix, the specified format is respected.
-
- Related work items
-
- - PRs: [#215][#215]
-
-
-
-- The `DSC/PowerShellGroup` resource now correctly returns the _labels_ for enumerations instead of
- their integer value, making it easier to understand and compare results.
-
- Related work items
-
- - Issues: [#159][#159]
- - PRs: [#208][#208]
-
-
-
-- DSC no longer terminates during discovery when a resource errors unless the erroring resource is
- being used for the command. DSC still terminates on a resource error during discovery under the
- following conditions:
-
- - When the erroring resource type is the same as the value of the `--resource` option for a
- `dsc resource *` command.
- - When an instance in the configuration document uses the erroring resource type for a
- `dsc config *` command.
-
- DSC emits the resource errors during discovery as warning messages for the `dsc resource list`
- command. In all other cases, DSC emits the errors as debug messages.
-
- Related work items
-
- - Issues: [#121][#121]
- - PRs: [#240][#240]
-
-
-
-
-[a4.01]: reference/schemas/config/document.md#schema
-[a4.02]: reference/schemas/resource/manifest/root.md#schema
-[a4.03]: reference/schemas/resource/properties/exist.md
-[a4.04]: reference/cli/completer/command.md
-[a4.05]: reference/schemas/config/functions/overview.md
-[a4.06]: reference/schemas/config/functions/base64.md
-[a4.07]: reference/schemas/config/functions/concat.md
-[a4.08]: reference/schemas/config/functions/resourceId.md
-
-## [v3.0.0-alpha.3][release-v3.0.0-alpha.3] - 2023-09-26
-
-This section includes a summary of changes for the `alpha.3` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3].
+Version `3.0.0` is the first generally available release of DSC.
-[release-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.3 "Link to the DSC v3.0.0-alpha.3 release on GitHub"
-[compare-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.2...v3.0.0-alpha.3
-
-### Changed
-
-- Replaced the `manifestVersion` property for resource manifests with [$schema][a3.01]. Instead of
- specifying a semantic version, resources need to indicate which canonical schema DSC should use
- to validate and process the manifest.
-
- Related work items
-
- - Issues: [#127][#127]
- - PRs: [#199][#199]
-
-
-
-- Updated the `preTest` property for the `set` command in resource manifests to
- [implementsPretest][a3.02] to more make the manifest easier to read and understand.
-
- Related work items
-
- - PRs: [#197][#197]
-
-
-
-- The [dsc resource set][cmd-rset] command no longer tests the resource instance before invoking the
- `set` operation. This simplifies the behavior for the command and adheres more accurately to the
- implied contract for directly invoking a resource with DSC.
-
- Related work items
-
- - Issues: [#98][#98]
- - PRs: [#197][#197]
-
-
-
-- Replaced the `args` option with `env` for defining how a command-based resource expects to
- receive input for the [get][a3.04], [set][a3.05], and [test][a3.06] commands in the resource
- manifest.
-
- The `args` option was never implemented. Instead, resource authors can set the `input` property
- to `env` to indicate that the resource expects input as environmental variables.
-
- Related work items
-
- - PRs: [#198][#198]
-
-
-
-- The `input` property for the [get][a3.04] command in a resource manifest no longer has a default
- value. Instead, when a resource doesn't define `input` for the `get` command, DSC doesn't send
- any input to the resource for that command.
-
- Related work items
-
- - PRs: [#198][#198]
-
-
-
-
-[a3.01]: reference/schemas/resource/manifest/root.md#schema
-[a3.02]: reference/schemas/resource/manifest/set.md#implementspretest
-[a3.04]: reference/schemas/resource/manifest/get.md#input
-[a3.05]: reference/schemas/resource/manifest/set.md#input
-[a3.06]: reference/schemas/resource/manifest/test.md#input
-
-## [v3.0.0-alpha.2][release-v3.0.0-alpha.2] - 2023-09-05
-
-This section includes a summary of changes for the `alpha.2` release. For the full list of changes
-in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-
-
-[release-v3.0.0-alpha.2]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.2 "Link to the DSC v3.0.0-alpha.2 release on GitHub"
-[compare-v3.0.0-alpha.2]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.1...v3.0.0-alpha.2
-
-### Changed
-
-- The [$schema][a2.14] value for configuration documents now points to the canonical published
- schema URI,
- `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json`.
-
- Related work items
-
- - PRs: [#156][#156]
-
-
-
-### Added
-
-- Implemented functionality for the [dependsOn property of resource instances][a2.01] in
- configuration documents, enabling resource instances to depend on the successful processing of
- one or more other instances in the document.
-
- Related work items
-
- - Issues: [#45][#45]
- - PRs: [#175][#175]
-
-
-
-- Added the [export][a2.02] property to the resource manifest schema, indicating that the resource
- is exportable and defining how DSC can retrieve the current state for every instance of the
- resource.
-
- Related work items
-
- - Issues: [#73][#73]
- - PRs: [#171][#171]
-
-
-
-- Added the [dsc config export][cmd-cexport] command to convert an input configuration document
- defining a list of resource types into a usable configuration document that defines the current
- state for every instance of those resources.
-
- Related work items
-
- - Issues: [#73][#73]
- - PRs: [#171][#171]
-
-
-
-- Added the [dsc resource export][cmd-rexport] command to generate a usable configuration document
- that defines the current state for every instance of a specified resource.
-
- Related work items
-
- - Issues: [#73][#73]
- - PRs: [#171][#171]
-
-
-
-- Added the [--all][a2.05] option for the [dsc resource get][cmd-rget] command, enabling users to
- retrieve the current state for every instance of an exportable resource with a single command.
-
- Related work items
-
- - Issues:
- - [#73][#73]
- - [#174][#174]
- - PRs: [#171][#171]
-
-
-
-- Added handling for the Ctrl+C key combination to cancel a DSC operation.
- When `dsc` cancels an operation due to this key-press, it indicates that the operation was
- cancelled with [exit code 6][a2.07].
-
- Related work items
-
- - PRs: [#177][#177]
- - Issues: [#150][#150]
-
-
-
-- Added support for using the [DSC_RESOURCE_PATH environment variable][a2.08] to define a list of
- folders to search for command-based DSC Resource manifests. When `DSC_RESOURCE_PATH` is defined,
- DSC searches those folders for resources and ignores the `PATH` variable for resource discovery.
-
- Related work items
-
- - PRs: [#176][#176]
- - Issues: [#133][#133]
-
-
-
-- The `DSC/AssertionGroup`, `DSC/Group`, and `DSC/ParallelGroup` resources now define semantic exit
- codes in their manifests. These resources now indicate that they use the same
- [exit codes as the dsc command][a2.08].
-
- Related work items
-
- - PRs: [#182][#182]
- - Issues: [#181][#181]
-
-
-
-- Added type validation in the schema for the [defaultValue][a2.09] and [allowedValues][a2.10]
- properties of [configuration document parameters][a2.11] to improve the authoring experience.
- Now, when a parameter defines values for these properties that are incompatible with the defined
- data type, validation raises an error indicating that the values are invalid and why.
-
- Related work items
-
- - PRs: [#172][#172]
-
-
-
-- Enhanced VS Code-specific schemas for configuration documents and resource manifests to improve
- the authoring experience. The enhanced schemas use keywords only supported by VS Code to:
-
- - Render Markdown help information for properties and enums.
- - Provide contextual error messages when a value fails pattern validation.
- - Define default snippets to autocomplete values.
-
- These schemas are non-canonical and should only be used for authoring. For more information, see
- [Authoring with enhanced schemas][a2.12].
-
- Related work items
-
- - PRs: [#172][#172]
-
-
-
-- Documentation to the [Microsoft/OSInfo][a2.13] resource instance schema and command-line tool to
- provide contextual help about the properties the resource can validate.
-
- Related work items
-
- - PRs: [#168][#168]
-
-
-
-### Fixed
-
-- The data-type conditionals for the [configuration parameters][a2.11] schema so that the `min*`
- and `max*` keywords apply to the correct data types. Previously, the logic prevented them from
- ever applying.
-
- Related work items
-
- - PRs: [#172][#172]
-
-
-
-- Using the `registry find` command no longer raises a panic error due to conflicting option
- definitions on the command.
-
- Related work items
-
- - PRs: [#163][#163]
-
-
-
-
-[a2.01]: reference/schemas/config/resource.md#dependson
-[a2.02]: reference/schemas/resource/manifest/export.md
-[a2.05]: reference/cli/resource/get.md#-a---all
-[a2.07]: reference/cli/dsc.md#exit-codes
-[a2.08]: reference/cli/dsc.md#environment-variables
-[a2.09]: reference/schemas/config/parameter.md#defaultvalue
-[a2.10]: reference/schemas/config/parameter.md#allowedvalues
-[a2.11]: reference/schemas/config/parameter.md
-[a2.12]: /powershell/dsc/concepts/enhanced-authoring?view=dsc-3.0&preserve-view=true
-[a2.13]: /powershell/dsc/reference/microsoft/osinfo/resource?view=dsc-3.0&preserve-view=true
-[a2.14]: reference/schemas/config/document.md#schema
-
-## [v3.0.0-alpha.1][release-v3.0.0-alpha.1] - 2023-08-04
-
-This is the first public release of DSC v3. Consider this release alpha quality. Use it only for
-development evaluation, as it has known issues and isn't feature complete.
-
-For the full list of changes in this release, see the [diff on GitHub][compare-v3.0.0-alpha.1].
-
-
-[release-v3.0.0-alpha.1]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.1 "Link to the DSC v3.0.0-alpha.1 release on GitHub"
-[compare-v3.0.0-alpha.1]: https://github.com/PowerShell/DSC/compare/6090b1464bbf81fded5453351708482a4db35258...v3.0.0-alpha.1
-
-
-[cmd]: reference/cli/dsc.md
-[cmd-completion]: reference/cli/completer/command.md
-[cmd-schema]: reference/cli/schema/command.md
-[cmd-c]: reference/cli/config/command.md
-[cmd-cexport]: reference/cli/config/export.md
-[cmd-cget]: reference/cli/config/get.md
-[cmd-cset]: reference/cli/config/set.md
-[cmd-ctest]: reference/cli/config/test.md
-[cmd-r]: reference/cli/resource/command.md
-[cmd-rdelete]: reference/cli/resource/delete.md
-[cmd-rexport]: reference/cli/resource/export.md
-[cmd-rget]: reference/cli/resource/get.md
-[cmd-rlist]: reference/cli/resource/list.md
-[cmd-rschema]: reference/cli/resource/schema.md
-[cmd-rset]: reference/cli/resource/set.md
-[cmd-rtest]: reference/cli/resource/test.md
-
-[cfuncs]: reference/schemas/config/functions/overview.md
-[add()]: reference/schemas/config/functions/add.md
-[base64()]: reference/schemas/config/functions/base64.md
-[concat()]: reference/schemas/config/functions/concat.md
-[createArray()]: reference/schemas/config/functions/createArray.md
-[div()]: reference/schemas/config/functions/div.md
-[envvar()]: reference/schemas/config/functions/envvar.md
-[int()]: reference/schemas/config/functions/int.md
-[max()]: reference/schemas/config/functions/max.md
-[min()]: reference/schemas/config/functions/min.md
-[mod()]: reference/schemas/config/functions/mod.md
-[mul()]: reference/schemas/config/functions/mul.md
-[parameters()]: reference/schemas/config/functions/parameters.md
-[reference()]: reference/schemas/config/functions/reference.md
-[resourceId()]: reference/schemas/config/functions/resourceId.md
-[sub()]: reference/schemas/config/functions/sub.md
-
-
-[#107]: https://github.com/PowerShell/DSC/issues/107
-[#121]: https://github.com/PowerShell/DSC/issues/121
-[#127]: https://github.com/PowerShell/DSC/issues/127
-[#129]: https://github.com/PowerShell/DSC/issues/129
-[#130]: https://github.com/PowerShell/DSC/issues/130
-[#133]: https://github.com/PowerShell/DSC/issues/133
-[#139]: https://github.com/PowerShell/DSC/issues/139
-[#150]: https://github.com/PowerShell/DSC/issues/150
-[#156]: https://github.com/PowerShell/DSC/issues/156
-[#158]: https://github.com/PowerShell/DSC/issues/158
-[#159]: https://github.com/PowerShell/DSC/issues/159
-[#162]: https://github.com/PowerShell/DSC/issues/162
-[#163]: https://github.com/PowerShell/DSC/issues/163
-[#165]: https://github.com/PowerShell/DSC/issues/165
-[#168]: https://github.com/PowerShell/DSC/issues/168
-[#171]: https://github.com/PowerShell/DSC/issues/171
-[#172]: https://github.com/PowerShell/DSC/issues/172
-[#173]: https://github.com/PowerShell/DSC/issues/173
-[#174]: https://github.com/PowerShell/DSC/issues/174
-[#175]: https://github.com/PowerShell/DSC/issues/175
-[#176]: https://github.com/PowerShell/DSC/issues/176
-[#177]: https://github.com/PowerShell/DSC/issues/177
-[#181]: https://github.com/PowerShell/DSC/issues/181
-[#182]: https://github.com/PowerShell/DSC/issues/182
-[#183]: https://github.com/PowerShell/DSC/issues/183
-[#186]: https://github.com/PowerShell/DSC/issues/186
-[#197]: https://github.com/PowerShell/DSC/issues/197
-[#198]: https://github.com/PowerShell/DSC/issues/198
-[#199]: https://github.com/PowerShell/DSC/issues/199
-[#202]: https://github.com/PowerShell/DSC/issues/202
-[#206]: https://github.com/PowerShell/DSC/issues/206
-[#208]: https://github.com/PowerShell/DSC/issues/208
-[#211]: https://github.com/PowerShell/DSC/issues/211
-[#213]: https://github.com/PowerShell/DSC/issues/213
-[#215]: https://github.com/PowerShell/DSC/issues/215
-[#216]: https://github.com/PowerShell/DSC/issues/216
-[#217]: https://github.com/PowerShell/DSC/issues/217
-[#218]: https://github.com/PowerShell/DSC/issues/218
-[#226]: https://github.com/PowerShell/DSC/issues/226
-[#227]: https://github.com/PowerShell/DSC/issues/227
-[#240]: https://github.com/PowerShell/DSC/issues/240
-[#241]: https://github.com/PowerShell/DSC/issues/241
-[#248]: https://github.com/PowerShell/DSC/issues/248
-[#251]: https://github.com/PowerShell/DSC/issues/251
-[#252]: https://github.com/PowerShell/DSC/issues/252
-[#253]: https://github.com/PowerShell/DSC/issues/253
-[#258]: https://github.com/PowerShell/DSC/issues/258
-[#263]: https://github.com/PowerShell/DSC/issues/263
-[#266]: https://github.com/PowerShell/DSC/issues/266
-[#271]: https://github.com/PowerShell/DSC/issues/271
-[#274]: https://github.com/PowerShell/DSC/issues/274
-[#279]: https://github.com/PowerShell/DSC/issues/279
-[#284]: https://github.com/PowerShell/DSC/issues/284
-[#286]: https://github.com/PowerShell/DSC/issues/286
-[#287]: https://github.com/PowerShell/DSC/issues/287
-[#290]: https://github.com/PowerShell/DSC/issues/290
-[#291]: https://github.com/PowerShell/DSC/issues/291
-[#294]: https://github.com/PowerShell/DSC/issues/294
-[#299]: https://github.com/PowerShell/DSC/issues/299
-[#302]: https://github.com/PowerShell/DSC/issues/302
-[#303]: https://github.com/PowerShell/DSC/issues/303
-[#305]: https://github.com/PowerShell/DSC/issues/305
-[#307]: https://github.com/PowerShell/DSC/issues/307
-[#309]: https://github.com/PowerShell/DSC/issues/309
-[#310]: https://github.com/PowerShell/DSC/issues/310
-[#311]: https://github.com/PowerShell/DSC/issues/311
-[#313]: https://github.com/PowerShell/DSC/issues/313
-[#314]: https://github.com/PowerShell/DSC/issues/314
-[#317]: https://github.com/PowerShell/DSC/issues/317
-[#318]: https://github.com/PowerShell/DSC/issues/318
-[#321]: https://github.com/PowerShell/DSC/issues/321
-[#322]: https://github.com/PowerShell/DSC/issues/322
-[#323]: https://github.com/PowerShell/DSC/issues/323
-[#329]: https://github.com/PowerShell/DSC/issues/329
-[#333]: https://github.com/PowerShell/DSC/issues/333
-[#334]: https://github.com/PowerShell/DSC/issues/334
-[#335]: https://github.com/PowerShell/DSC/issues/335
-[#336]: https://github.com/PowerShell/DSC/issues/336
-[#338]: https://github.com/PowerShell/DSC/issues/338
-[#342]: https://github.com/PowerShell/DSC/issues/342
-[#344]: https://github.com/PowerShell/DSC/issues/344
-[#346]: https://github.com/PowerShell/DSC/issues/346
-[#347]: https://github.com/PowerShell/DSC/issues/347
-[#348]: https://github.com/PowerShell/DSC/issues/348
-[#349]: https://github.com/PowerShell/DSC/issues/349
-[#351]: https://github.com/PowerShell/DSC/issues/351
-[#352]: https://github.com/PowerShell/DSC/issues/352
-[#353]: https://github.com/PowerShell/DSC/issues/353
-[#354]: https://github.com/PowerShell/DSC/issues/354
-[#356]: https://github.com/PowerShell/DSC/issues/356
-[#357]: https://github.com/PowerShell/DSC/issues/357
-[#358]: https://github.com/PowerShell/DSC/issues/358
-[#360]: https://github.com/PowerShell/DSC/issues/360
-[#361]: https://github.com/PowerShell/DSC/issues/361
-[#362]: https://github.com/PowerShell/DSC/issues/362
-[#364]: https://github.com/PowerShell/DSC/issues/364
-[#368]: https://github.com/PowerShell/DSC/issues/368
-[#371]: https://github.com/PowerShell/DSC/issues/371
-[#373]: https://github.com/PowerShell/DSC/issues/373
-[#375]: https://github.com/PowerShell/DSC/issues/375
-[#376]: https://github.com/PowerShell/DSC/issues/376
-[#377]: https://github.com/PowerShell/DSC/issues/377
-[#379]: https://github.com/PowerShell/DSC/issues/379
-[#382]: https://github.com/PowerShell/DSC/issues/382
-[#385]: https://github.com/PowerShell/DSC/issues/385
-[#388]: https://github.com/PowerShell/DSC/issues/388
-[#390]: https://github.com/PowerShell/DSC/issues/390
-[#397]: https://github.com/PowerShell/DSC/issues/397
-[#400]: https://github.com/PowerShell/DSC/issues/400
-[#401]: https://github.com/PowerShell/DSC/issues/401
-[#405]: https://github.com/PowerShell/DSC/issues/405
-[#407]: https://github.com/PowerShell/DSC/issues/407
-[#410]: https://github.com/PowerShell/DSC/issues/410
-[#412]: https://github.com/PowerShell/DSC/issues/412
-[#429]: https://github.com/PowerShell/DSC/issues/429
-[#431]: https://github.com/PowerShell/DSC/issues/431
-[#432]: https://github.com/PowerShell/DSC/issues/432
-[#434]: https://github.com/PowerShell/DSC/issues/434
-[#435]: https://github.com/PowerShell/DSC/issues/435
-[#438]: https://github.com/PowerShell/DSC/issues/438
-[#439]: https://github.com/PowerShell/DSC/issues/439
-[#441]: https://github.com/PowerShell/DSC/issues/441
-[#444]: https://github.com/PowerShell/DSC/issues/444
-[#454]: https://github.com/PowerShell/DSC/issues/454
-[#464]: https://github.com/PowerShell/DSC/issues/464
-[#45]: https://github.com/PowerShell/DSC/issues/45
-[#49]: https://github.com/PowerShell/DSC/issues/49
-[#57]: https://github.com/PowerShell/DSC/issues/57
-[#70]: https://github.com/PowerShell/DSC/issues/70
-[#73]: https://github.com/PowerShell/DSC/issues/73
-[#75]: https://github.com/PowerShell/DSC/issues/75
-[#89]: https://github.com/PowerShell/DSC/issues/89
-[#98]: https://github.com/PowerShell/DSC/issues/98
+[release-v3.0.0]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0 "Link to the DSC v3.0.0 release on GitHub"
diff --git a/dsc/docs-conceptual/dsc-3.0/concepts/configurations.md b/dsc/docs-conceptual/dsc-3.0/concepts/configuration-documents/overview.md
similarity index 50%
rename from dsc/docs-conceptual/dsc-3.0/concepts/configurations.md
rename to dsc/docs-conceptual/dsc-3.0/concepts/configuration-documents/overview.md
index ea26cb5..c1a2313 100644
--- a/dsc/docs-conceptual/dsc-3.0/concepts/configurations.md
+++ b/dsc/docs-conceptual/dsc-3.0/concepts/configuration-documents/overview.md
@@ -1,47 +1,48 @@
---
description: >-
DSC configuration documents are YAML or JSON data files that define the desired state of a system
- declaratively. They are used to retrieve, validate, and enforce the state of multiple resource
+ declaratively. They're used to retrieve, validate, and enforce the state of multiple resource
instances.
-ms.date: 08/07/2023
-title: DSC Configuration Documents
+ms.date: 03/25/2025
+title: DSC configuration documents
---
-# 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 the configuration document
-instances.
+[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.
-DSCv3 can process configuration documents to:
+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 DSCv3 processes the document. The top-level properties for a document are:
+properties define how DSC processes the document. The top-level properties for a document are:
-- `$schema` (required) - Defines the canonical URI for the JSON Schema the document adheres to. DSC
- uses this to know how to validate and interpret the document.
+- `$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. 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.
-- `parameters` (optional) - Defines a set of runtime options for the configuration. Parameters can
- be referenced by resource instances to reduce duplicate definitions or enable dynamic values.
+- `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. Variables can be
- referenced by resource instances to reduce duplicate definitions.
-
-> [!NOTE]
-> DSC isn't implemented to process the `parameters` and `variables` properties yet. They can be
-> defined in a document, but not referenced.
+- `variables` (optional) - Defines a set of reusable values for the configuration. Resource
+ instances can reference variables to reduce duplicate definitions.
## Defining a configuration document
@@ -53,7 +54,7 @@ For example:
```yaml
# example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: example key value
type: Microsoft.Windows/Registry
@@ -64,7 +65,7 @@ resources:
String: This is an example.
```
-The example document defines a single resource instance called `example key value`. The instance
+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.
@@ -75,17 +76,21 @@ The example document is _declarative_. It describes the desired state, not how t
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.
+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][02] of the resource that DSC should use to manage 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.
@@ -96,60 +101,90 @@ 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. DSC also collects any message emitted by the resources during the operation
-and indicates whether any of the resources raised an error.
+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
-cat ./example.config.dsc.yaml | dsc config get
+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:
-- name: example key value
+- metadata:
+ Microsoft.DSC:
+ duration: PT0.2751153S
+ name: example key value
type: Microsoft.Windows/Registry
result:
actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
+ 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 `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.
-DSC also collects any message emitted by the resources during the operation and indicates whether
-any of the resources raised an error.
+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
-cat ./example.config.dsc.yaml | dsc config test
+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:
-- name: example key value
+- metadata:
+ Microsoft.DSC:
+ duration: PT0.2234078S
+ name: example key value
type: Microsoft.Windows/Registry
result:
desiredState:
- valueData:
- String: This is an example.
keyPath: HKCU\example\key
valueName: Example
+ valueData:
+ String: This is an example.
actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
- _inDesiredState: false
+ keyPath: HKCU\example\key
+ _exist: false
inDesiredState: false
differingProperties:
- - valueData
- - keyPath
- valueName
+ - valueData
+ - _exist
messages: []
hadErrors: false
```
@@ -163,31 +198,45 @@ their desired state. The result for each instance includes:
- The state of the instance after the operation.
- Which properties the operation changed, if any.
-DSC also collects any message emitted by the resources during the operation and indicates whether
-any of the resources raised an error.
+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
-cat ./example.config.dsc.yaml | dsc config set
+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:
-- name: example key value
+- metadata:
+ Microsoft.DSC:
+ duration: PT0.4070001S
+ name: example key value
type: Microsoft.Windows/Registry
result:
beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
+ keyPath: HKCU\example\key
+ _exist: false
afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: HKCU\example\key
valueName: Example
valueData:
String: This is an example.
changedProperties:
- - keyPath
- valueName
- valueData
+ - _exist
messages: []
hadErrors: false
```
@@ -195,10 +244,12 @@ hadErrors: false
## See also
- [DSC Resources][01] to learn about resources.
-- [DSC Configuration document schema reference][03]
-- [Command line reference for the 'dsc config' command][04]
-
-[01]: ./resources.md
-[02]: ./resources.md#resource-type-names
-[03]: ../reference/schemas/config/document.md
-[04]: ../reference/cli/config/command.md
+- [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/dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md b/dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md
index 7ee6a27..91d7edb 100644
--- a/dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md
+++ b/dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md
@@ -3,16 +3,18 @@ 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: 09/13/2023
+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 data files
-that define a command-based DSC Resource.
+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
@@ -22,17 +24,24 @@ 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.
-- Add default snippets to autocomplete values.
+- Provide IntelliSense and default snippets.
> [!NOTE]
-> The enhanced schemas are non-canonical. Never specify them for the `$schema` keyword in a
-> configuration document or resource manifest. These schemas are only for improving the authoring
-> experience.
+> 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 non-canonical keywords. For maximum compatibility
+> 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
@@ -41,7 +50,7 @@ specific to VS Code that:
:::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.
@@ -52,9 +61,9 @@ When possible, the hover help includes a link to the online documentation.
:::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 using IntelliSense while authoring with an enhanced schema, the quick info shown for the
+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.
@@ -64,7 +73,7 @@ the online 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
@@ -80,7 +89,7 @@ for the property an enum belongs to.
:::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
@@ -90,19 +99,19 @@ snippets in VS Code.
:::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 non-empty string containing only letters, numbers, and spaces."
+ 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 defining values, the enhanced schemas have contextual error messages instead of the default
-error messages that JSON schema validation raises. This is particularly 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.
+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
+your `settings.json` file in VS Code. You can define these options in your user settings or for a
specific workspace.
@@ -113,14 +122,14 @@ specific workspace.
"**/*.dsc.json",
"**/*.dsc.config.json"
],
- "url": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json"
+ "url": "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json"
}
],
"yaml.schemas": {
- "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}"
+ "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:
@@ -133,13 +142,13 @@ following suffixes:
- `.dsc.yml`
To associate a specific configuration document formatted as YAML with the enhanced schema, add the
-following comment to the top of the configuration document:
+following comment to the top of the document:
```yml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
+# 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
@@ -148,19 +157,37 @@ when authoring configuration documents in JSON, you must define the schema assoc
## 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
+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://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json"
+ "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]: configurations.md
-[02]: ../resources/concepts/anatomy.md#dsc-resource-manifests
+[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/dsc/docs-conceptual/dsc-3.0/concepts/output-accessibility.md b/dsc/docs-conceptual/dsc-3.0/concepts/output-accessibility.md
index 6f770e6..4b403b4 100644
--- a/dsc/docs-conceptual/dsc-3.0/concepts/output-accessibility.md
+++ b/dsc/docs-conceptual/dsc-3.0/concepts/output-accessibility.md
@@ -1,7 +1,9 @@
---
-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.
+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: 09/12/2024
+ms.date: 03/25/2025
title: Improve the accessibility of DSC output in PowerShell
---
@@ -100,10 +102,17 @@ dsc resource list -a Microsoft.Windows/WindowsPowerShell |
Format-List
```
-## Additional reading
+## Related content
-- [Improve the accessibility of output in PowerShell](/powershell/scripting/learn/shell/output-for-screen-reader)
-- [Out-GridView](xref:Microsoft.PowerShell.Utility.Out-GridView)
-- [Export-Csv](xref:Microsoft.PowerShell.Utility.Export-Csv)
-- [ConvertTo-Html](xref:Microsoft.PowerShell.Utility.ConvertTo-Html)
-- [about_Calculated_Properties](/powershell/module/microsoft.powershell.core/about/about_calculated_properties)
+- [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/dsc/docs-conceptual/dsc-3.0/concepts/resources/anatomy.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/anatomy.md
new file mode 100644
index 0000000..1955fe1
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/concepts/resources/capabilities.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/capabilities.md
new file mode 100644
index 0000000..9327015
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/concepts/resources/instances.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/instances.md
new file mode 100644
index 0000000..e01b331
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/concepts/resources/kinds.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/kinds.md
new file mode 100644
index 0000000..55c4126
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/concepts/resources/operations.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/operations.md
new file mode 100644
index 0000000..22d9c42
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/concepts/resources.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/overview.md
similarity index 51%
rename from dsc/docs-conceptual/dsc-3.0/concepts/resources.md
rename to dsc/docs-conceptual/dsc-3.0/concepts/resources/overview.md
index 1c60f45..64d70a2 100644
--- a/dsc/docs-conceptual/dsc-3.0/concepts/resources.md
+++ b/dsc/docs-conceptual/dsc-3.0/concepts/resources/overview.md
@@ -2,7 +2,7 @@
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: 08/07/2023
+ms.date: 03/25/2025
title: DSC Resources
---
@@ -21,22 +21,23 @@ Resources manage _instances_ of a configurable component. For example, the
different instance of the resource. Every resource defines a schema that describes how to validate
and manage an instance of the resource.
-DSCv3 supports several kinds of resources:
+DSC supports several kinds of resources:
-- A resource defined with a resource manifest is a _command-based_ resource. DSC uses the manifest
+- 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 _resource group_ is a command-based resource with a `resources` property that takes an array of
- resource instances and processes them. Resource groups may apply special handling to their nested
+- 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.
-- A _resource provider_ is a resource group that enables the use of non-command-based resources
- with DSCv3. For example, the `DSC/PowerShellGroup` resource provider enables the use of DSC
- Resources implemented in PowerShell modules.
+- 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
-Resources are identified by their fully qualified type name. The type name is used to specify a
-resource in configuration documents and as the value of the `--resource` flag when using the
-`dsc resource *` commands.
+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:
@@ -55,11 +56,11 @@ For more information about type names and how DSC validates them, see
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
-schema.
+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 may have default values for their
+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:
@@ -74,6 +75,25 @@ Most properties are one of the basic types:
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
@@ -87,26 +107,30 @@ dsc resource list
```
```Output
-type version tags description
----- ------- ---- -----------
-Test/TestGroup 0.1.0
-Microsoft/OSInfo 0.1.0 {os, linux, windows, macos} Returns information about the operating system.
-Microsoft.Windows/Registry 0.1.0 {Windows, NT} Registry configuration provider for the Windows Registry
- This is a test resource.
-DSC/PowerShellGroup 0.1.0 {PowerShell} Resource provider to classic DSC Powershell resources.
-DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration.
-DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently.
- This is a test resource.
-DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group.
+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][02]
+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 DSC operations **Get**, **Test**, and **Set**.
+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
@@ -117,15 +141,14 @@ For example, you can use the `Microsoft.Windows/Registry` resource to get the ac
registry key value:
```powershell
-'{
+dsc resource get --resource Microsoft.Windows/Registry --input '{
"keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
"valueName": "SystemRoot"
-}' | dsc resource get --resource Microsoft.Windows/Registry
+}'
```
```yaml
actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
valueName: SystemRoot
valueData:
@@ -135,7 +158,7 @@ actualState:
### Test operations
Some resources implement the **Test** operation. For resources that don't implement the **Test**
-operation, DSCv3 can validate an instance's state with a synthetic test. The synthetic test is a
+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.
@@ -150,21 +173,22 @@ Use the `dsc resource test` command to invoke the operation. DSC returns data th
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",
-}' | dsc resource test --resource Microsoft.Windows/Registry
+ "exist": true
+}'
```
```yaml
desiredState:
keyPath: HKCU\key\that\does\not\exist
+ _exist: true
actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
- _inDesiredState: false
+ keyPath: HKCU\key\that\does\not\exist
+ _exist: false
inDesiredState: false
differingProperties:
-- keyPath
+- _exist
```
### Set operations
@@ -172,7 +196,7 @@ differingProperties:
Most resources implement the **Set** operation, which enforces the desired state for an
-instance. When used with DSCv3, the **Set** operation is _idempotent_, which means that the
+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.
@@ -193,35 +217,60 @@ For example, you can create a registry key by setting the desired state for a ke
exist.
```powershell
-'{
+dsc resource set --resource Microsoft.Windows/Registry --input '{
"keyPath": "HKCU\\example\\key",
"valueName": "Example",
"valueData": { "String": "This is an example." }
-}' | dsc resource set --resource Microsoft.Windows/Registry
+}'
```
```yaml
beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
+ keyPath: HKCU\example\key
+ _exist: false
afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: HKCU\example\key
valueName: Example
valueData:
String: This is an example.
changedProperties:
-- keyPath
- 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. This
-makes 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.
+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:
@@ -249,13 +298,14 @@ resources:
## See also
-- [Anatomy of a command-based DSC Resource][03] to learn about authoring resources in your language
+- [Anatomy of a DSC command resource][04] to learn about authoring resources in your language
of choice.
-- [Configuration Documents][04] to learn about using resources in a configuration document.
-- [Command line reference for the 'dsc resource' command][05]
-
-[01]: ../reference/schemas/definitions/resourceType.md
-[02]: ../reference/cli/resource/list.md
-[03]: ../resources/concepts/anatomy.md
-[04]: configurations.md
-[05]: ../reference/cli/resource/command.md
+- [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/dsc/docs-conceptual/dsc-3.0/concepts/resources/properties.md b/dsc/docs-conceptual/dsc-3.0/concepts/resources/properties.md
new file mode 100644
index 0000000..449f8f9
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/get-started/index.md b/dsc/docs-conceptual/dsc-3.0/get-started/index.md
new file mode 100644
index 0000000..c8f963c
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.md b/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.md
deleted file mode 100644
index 0e24ab1..0000000
--- a/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-description: >-
- Learn how to use Microsoft's Desired State Configuration platform to manage the state of a
- machine as code.
-ms.date: 08/07/2023
-title: Get started managing state with DSCv3
----
-
-# Get started managing state with DSCv3
-
-> [!NOTE]
-> The team is rewriting this document for DSCv3.
diff --git a/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.old.md b/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.old.md
deleted file mode 100644
index 571ccad..0000000
--- a/dsc/docs-conceptual/dsc-3.0/getting-started/getting-started.old.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-description: Learn how to use the Desired State Configuration feature of PowerShell to manage the state of a machine as code.
-ms.date: 04/04/2023
-title: Manage configuration using PowerShell DSC
----
-
-# Manage configuration using PowerShell DSC
-
-There are three options for managing the state of a machine from PowerShell DSC. The solutions are
-the same for both Linux and Windows operating systems.
-
-## The `Invoke-DSCResource` command
-
-You can deliver changes to a machine using a script. The `Invoke-DSCResource` command can be used to
-reference a DSC resource and pass through the properties that define how to manage the end state.
-
-Test if the machine is in the correct state, for an example resource.
-
-```powershell
-$TestParameters = @{
- Name = 'Environment'
- ModuleName = 'PSDscResources'
- Property = @{
- Name = 'TestEnvironmentVariable'
- Value = 'TestValue'
- Ensure = 'Present'
- Path = $false
- Target = @('Process', 'Machine')
- }
- Method = Test
-}
-Invoke-DscResource @TestParameters
-```
-
-Get the current state of a machine, for an example resource.
-
-```powershell
-$GetParameters = @{
- Name = 'Environment'
- ModuleName = 'PSDscResources'
- Property = @{
- Name = 'TestEnvironmentVariable'
- Value = 'TestValue'
- Ensure = 'Present'
- Path = $false
- Target = @('Process', 'Machine')
- }
- Method = Get
-}
-Invoke-DscResource @GetParameters
-```
-
-Set the state of the machine, for an example resource.
-
-```powershell
-$SetParameters = @{
- Name = 'Environment'
- ModuleName = 'PSDscResources'
- Property = @{
- Name = 'TestEnvironmentVariable'
- Value = 'TestValue'
- Ensure = 'Present'
- Path = $false
- Target = @('Process', 'Machine')
- }
- Method = Set
-}
-Invoke-DscResource @SetParameters
-```
-
-For more information, view the [Invoke-DscResource][01] help.
-
-## Azure machine configuration
-
-For machines hosted in Microsoft Azure, or connected for hybrid management, the machine
-configuration feature of Azure Automanage offers the ability to audit or apply configurations. The
-feature can be used stand-alone to assign configurations as a machine is deployed, or dynamically
-to assign configurations to a machine based on properties defined by the API.
-
-For more information, see [Understanding Azure Machine Configuration][02].
-
-## DSC resources with third-party tools
-
-PowerShell DSC resources can also be used with most popular configuration management platforms. For
-additional details, see the documentation for each third-party solution.
-
-## See Also
-
-- [DSC Configurations][03]
-- [DSC Resources][04]
-
-
-[01]: /powershell/module/psdesiredstateconfiguration/invoke-dscresource
-[02]: /azure/governance/machine-configuration/overview
-[03]: ../concepts/configurations.md
-[04]: ../concepts/resources.md
diff --git a/dsc/docs-conceptual/dsc-3.0/glossary.md b/dsc/docs-conceptual/dsc-3.0/glossary.md
index 1b9c011..3607b25 100644
--- a/dsc/docs-conceptual/dsc-3.0/glossary.md
+++ b/dsc/docs-conceptual/dsc-3.0/glossary.md
@@ -1,24 +1,24 @@
---
title: "Glossary: Desired State Configuration"
description: >-
- A glossary of terms for PowerShell Desired State Configuration (DSC) v3.
+ A glossary of terms for Microsoft Desired State Configuration (DSC)
ms.topic: glossary
-ms.date: 08/07/2023
+ms.date: 03/25/2025
---
# Glossary: Desired State Configuration
-Desired State Configuration (DSC) v3 uses several terms that may have different definitions
-elsewhere. This document lists the terms, their meanings, and shows how they're formatted in the
-documentation.
+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 file that defines a list of resource instances and their desired state.
+The JSON or YAML data that defines a list of resource instances and their desired state.
#### Guidelines
@@ -27,7 +27,7 @@ The JSON or YAML file that defines a list of resource instances and their desire
#### Examples
-> A DSC Configuration Document may be formatted as JSON or YAML.
+> A DSC Configuration Document can be formatted as JSON or YAML.
> Define the `scope` variable in the document as `machine`.
@@ -35,7 +35,7 @@ The JSON or YAML file that defines a list of resource instances and their desire
### DSC Resource
-The DSC interface for managing the settings of a component. DSC v3 supports several kinds of
+The DSC interface for managing the settings of a component. DSC supports several kinds of
resources.
#### Guidelines
@@ -50,37 +50,58 @@ resources.
> You can inspect a resource's definition with the `dsc resource list ` command.
-### Command-based DSC Resource
+### DSC resource instance
-A resource defined with a resource manifest is a _command-based_ resource. DSC uses the manifest to
+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
-- Always specify the term with the hyphen.
+- Use this term when distinguishing between command resources and adapted resources.
#### Examples
-> `Microsoft.Windows/Registry` is a command-based resource.
+> `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 Resource group
+### DSC group resource
-A _resource group_ is a command-based resource with a `resources` property that takes an array of
-resource instances and processes them. Resource groups may apply special handling to their nested
-resource instances, like changing the user the resources run as.
+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 resource group. Don't omit "group" from the term.
+- Always specify the term as group resource. Don't omit "group" from the term.
#### Examples
-> To ensure resources are invoked in parallel, use the `DSC/ParallelGroup` resource group.
+> To invoke resources in parallel, use the `Microsoft.DSC/ParallelGroup` group resource.
### Nested resource instance
-A resource instance that's included in the `resources` property of a resource group or resource
-provider.
+A resource instance defined in the `resources` property of a group or adapter
+resource instance.
#### Guidelines
@@ -94,55 +115,64 @@ provider.
> Add a nested resource instance to the `DSC/ParallelGroup` instance. Define the `type` of the
> nested instance as `Microsoft.Windows/Registry`.
-### DSC Resource provider
+### DSC adapter resource
-A _resource provider_ is a resource group that enables the use of non-command-based resources with
-DSC v3. Every nested resource instance must be a resource type the provider supports.
+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 Resource provider
-- **Subsequent mentions:** provider
+- **First mention:** DSC adapter resource
+- **Subsequent mentions:** adapter
#### Examples
-> To use PowerShell DSC Resources in your configuration document, add an instance of the
-> `DSC/PowerShellGroup` resource provider and define the PowerShell resource instances as nested
-> instances.
+> 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
-### PowerShell DSC Resources
+A resource implemented in PowerShell is a PowerShell resource.
-A resource implemented in PowerShell. DSC v3 supports two types of PowerShell resources.
+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 resource defined as a PowerShell class in a module is a _class-based_ resource.
+- 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 resource must define
- the `Get()`, `Set()`, and `Test()` methods.
-- MOF-based - A resource defined with a MOF file (`.mof`), a script module file (`.psm1`), and
- optional module manifest file (`.psd1`) is a _MOF-based_ resource. MOF-based resources are only
- supported through Windows PowerShell.
+ 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** methods.
+ `Test-TargetResource`. These functions map to the **Get**, **Set**, and **Test** operations.
#### Guidelines
-- **First mention:** PowerShell DSC Resources
-- **Subsequent mentions:** PowerShell resources or PSDSC resources.
+- **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 resources_.
-- The PowerShell and PSDSC prefix may be omitted when the context is clearly or only about
- PowerShell resources, like a tutorial for authoring a class-based resource.
+ _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
-> `DSC/PowerShellGroup` resource provider and define the PowerShell resource instances as nested
+> `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.
@@ -150,17 +180,18 @@ A resource implemented in PowerShell. DSC v3 supports two types of PowerShell re
### DSC Resource manifest
-The JSON file that defines the metadata and implementation of a command-based resource.
+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
+- **First mention:** DSC resource manifest
- **Subsequent mentions:** manifest
#### Examples
-> Every command-based resource must define a DSC Resource manifest. The manifest's filename must
-> end with `.dsc.resource.json`.
+> Every command resource must define a DSC resource manifest. The manifest's filename must end with
+> `.dsc.resource.json`.
### DSC Resource type name
@@ -173,14 +204,21 @@ syntax:
#### Guidelines
-- **First mention:** DSC Resource type name
-- **Subsequent mentions:** resource type or type name.
+- **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 resource type name.
+> 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
@@ -189,59 +227,202 @@ 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
-1. Capitalize the operations.
-1. When referring to the operation specifically, format it as **bold**.
-1. 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.
+- 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 resource can't use any `return`
-> statements.
+> The implementation of the `Set()` method in a class-based PowerShell resource can't use any
+> `return` statements.
-> DSC is constructed around a **Get**, **Test**, and **Set** process.
+> 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.
-### Property
+### 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.
-**Guidelines**
+> Specify the `settingsScope` key property defines whether the settings file should be updated for
+> the machine or current user.
-1. Format property names as bold.
-1. Format property values as code.
+### Canonical resource properties
-**Examples**
+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]
-> The value of the **Format** property in this example is `JSON`.
+#### 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, where 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.
+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, DSCv3, or 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.
-- Specify the version suffix when discussing DSC in contexts where the term historically has also
- applied to PowerShell DSC.
#### Examples
-> In Microsoft's Desired State Configuration (DSC) platform, DSC Resources represent a standardized
+> 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, DSCv3 can validate an instance's state
+> For resources that don't implement the **Test** operation, DSC can validate an instance's state
> with a synthetic test.
### `dsc`
@@ -251,8 +432,6 @@ The DSC command line tool that invokes resources and manages configuration docum
#### Guidelines
- Specify the term as DSC when discussing the command line tool in general.
-- Specify the term as DSCv3 when discussing the command line tool in contexts where the term
- historically has also applied to PowerShell DSC.
- Use code formatting when discussing running the command, a specific subcommand, or to distinguish
the command line tool from the conceptual platform.
@@ -265,27 +444,32 @@ The DSC command line tool that invokes resources and manages configuration docum
> - Whether the instance is in the desired state.
> - The list of properties that aren't in the desired state.
-### PowerShell Desired State Configuration
+### PowerShell Desired State Configuration (PSDSC)
-The Desired State Configuration feature of PowerShell. Before DSCv3, this term included the
+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 DSCv3, this term applies to defining and using DSC Resources that are implemented in
-PowerShell with the **PSDesiredStateConfiguration** 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
+- **First mention:** PowerShell Desired State Configuration (PSDSC)
- **Subsequent mentions:** PowerShell DSC or PSDSC
-- Always distinguish PowerShell DSC from DSCv3.
+- 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 Resources with DSCv3.
+> 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.
+> 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/dsc/docs-conceptual/dsc-3.0/overview.md b/dsc/docs-conceptual/dsc-3.0/overview.md
index 732d74c..5f43cbe 100644
--- a/dsc/docs-conceptual/dsc-3.0/overview.md
+++ b/dsc/docs-conceptual/dsc-3.0/overview.md
@@ -2,31 +2,33 @@
description: >-
Learn about Microsoft's Desired State Configuration platform, including what it does and when
it should be used.
-ms.date: 01/29/2024
+ms.date: 03/25/2025
ms.topic: overview
-title: Microsoft Desired State Configuration v3 overview
+title: Microsoft Desired State Configuration overview
---
-# Microsoft Desired State Configuration v3 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 the script logic that implements how it's delivered.
+application environment is separate from programming logic that enforces that definition.
-The DSCv3 command line application abstracts the management of software components declaratively
-and idempotently. DSCv3 runs on Linux, macOS, and Windows without any external dependencies.
+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 DSCv3, you can:
+With DSC, you can:
- Author DSC Resources to manage your systems in any language.
-- Invoke individual resources.
+- Invoke individual resources directly.
- Create configuration documents that define the desired state of a system.
## Configuration Documents
-DSC Configuration Documents are declarative YAML files that define instances of resources.
-Typically, configuration documents define what state to enforce.
+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.
@@ -39,63 +41,107 @@ used with the **Get** and **Test** operations to retrieve the current state of a
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, or how to configure settings of an application.
+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
-DSCv3 leverages the [PSDesiredStateConfiguration module][00] to support compatibility with
-existing PowerShell based resources.
+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_.
-DSCv3 differs from PowerShell Desired State Configuration (PSDSC) in a few important ways:
+ 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.
-- DSCv3 doesn't depend on PowerShell. You can use DSCv3 without PowerShell installed and manage
- resources written in bash, python, C#, Go, or any other language.
-- DSCv3 doesn't include a local configuration manager. DSCv3 is invoked as a command. It doesn't
+ 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.
-- Non-PowerShell resources define their schemas with JSON files, not MOF files.
+- 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.
-
-Importantly, while DSCv3 represents a major change to the DSC platform, DSCv3 is able to invoke
-PSDSC Resources, including script-based and class-based DSC Resources, as they exist today. The
-configuration documents aren't compatible, but all published PSDSC Resources are. You can use PSDSC
-resources in DSCv3 with both Windows PowerShell and PowerShell.
+ 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
-To install DSCv3:
+### Install DSC manually
+
+To install DSC on any platform:
-1. Download the [latest release from the PowerShell/DSC repository][01].
+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`.
-To install the `PSDesiredStateConfiguration` version 3 beta from the PowerShell Gallery:
+### 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
-# Using PSResourceGet
-Install-PSResource -Name PSDesiredStateConfiguration -Version 3.0.0-beta1 -Prerelease
-# Using PowerShellGet
-Install-Module -Name PSDesiredStateConfiguration -RequiredVersion 3.0.0-beta1 -AllowPrerelease
+# Install latest stable
+winget install --id 9NVTPZWRC6KQ --source msstore
```
-## Integrating with DSCv3
+```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.
-DSCv3 is a platform tool that abstracts the concerns for defining and invoking resources. Higher
-order tools, like Azure Dev Box, Windows Dev Home, and WinGet are early partners
-for DSCv3 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.
-DSCv3 uses JSON schemas to define the structure of resources, configuration documents, and the
-outputs that DSCv3 returns. These schemas make it easier to integrate DSCv3 with other tools,
-because they standardize and document how to interface with DSCv3.
+For more information, see [DSC JSON Schema reference overview][06].
## See Also
-- [Anatomy of a command-based DSC Resource][02] to learn about authoring a resource in your
+- [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][03]
+- [Command line reference for the 'dsc' command][08]
+- [DSC JSON Schema reference overview][06]
+- [WinGet Configuration][09]
-[00]: https://github.com/powershell/psdesiredstateconfiguration
-[01]: https://github.com/PowerShell/DSC/releases/latest
-[02]: resources/concepts/anatomy.md
-[03]: reference/cli/dsc.md
+[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/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/index.md
similarity index 85%
rename from dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/cli/completer/index.md
index 60e3a48..b86ae1e 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/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,27 +78,32 @@ 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/
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md
index 3611688..57546c0 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc config export' command
-ms.date: 03/06/2024
+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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md
index ee78b0e..3694d36 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc config get' command
-ms.date: 06/24/2024
+ms.date: 03/25/2025
ms.topic: reference
title: dsc config get
---
@@ -13,48 +13,51 @@ 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
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Windows only
type: Microsoft.DSC/Assertion
properties:
- $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: os
type: Microsoft/OSInfo
@@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/index.md
similarity index 70%
rename from dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/cli/config/index.md
index 6b97de6..ceb9475 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc config' command
-ms.date: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md
index 307137e..196597c 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc config set' command
-ms.date: 06/24/2024
+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,24 +38,26 @@ 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.
```yaml
# example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Windows only
type: Microsoft.DSC/Assertion
properties:
- $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: os
type: Microsoft/OSInfo
@@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md
index 9d5df35..ca84dc4 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc config test' command
-ms.date: 06/24/2024
+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,24 +37,27 @@ 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
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Windows only
type: Microsoft.DSC/Assertion
properties:
- $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: os
type: Microsoft/OSInfo
@@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/index.md
similarity index 67%
rename from dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md
rename to dsc/docs-conceptual/dsc-3.0/reference/cli/index.md
index 126ff8a..061bab8 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc' command
-ms.date: 06/24/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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md
index 3ddb751..ab6da0d 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource delete' command
-ms.date: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md
index f399dd9..9779779 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource export' command
-ms.date: 03/06/2024
+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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md
index c5c18da..17e6ea7 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource get' command
-ms.date: 03/06/2024
+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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/index.md
similarity index 84%
rename from dsc/docs-conceptual/dsc-3.0/reference/cli/resource/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/cli/resource/index.md
index 2a871d8..eb660d4 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md
index c289574..8fd6244 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource list' command
-ms.date: 06/24/2024
+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,25 @@ 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
+
+DSC maintains a cache of discovered adapted resources for performance optimization. The location of
+the cache depends on the operating system, as shown in the following table.
+
+| Operating system | Cache path |
+|:----------------:|:------------------------------------------------------|
+| Linux | `~/.dsc/AdaptedResourcesLookupTable.json` |
+| macOS | `~/.dsc/AdaptedResourcesLookupTable.json` |
+| Windows | `%LOCALAPPDATA%\dsc\AdaptedResourcesLookupTable.json` |
## Examples
@@ -45,28 +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.
-Test/Delete Resource 0.1.0 g----d--
-Test/Echo Resource 0.1.0 gs--t---
-Test/Exist Resource 0.1.0 gsx-----
-Test/ExitCode Resource 0.1.0 g-------
-Test/Sleep Resource 0.1.0 gs--t---
-Test/TestGroup Adapter 0.1.0 g-------
-Test/Trace Resource 0.1.0 gs--t---
-Test/WhatIf Resource 0.1.0 gs-w----
+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
@@ -79,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
@@ -94,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
@@ -113,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
@@ -130,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.
@@ -147,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:
@@ -194,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.
@@ -224,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
@@ -239,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.
@@ -267,80 +228,109 @@ 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:
-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).
+- `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:
+
+- 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,
displayed in the listed order:
- **Type** - The fully qualified type name of the resource.
-- **Kind** - Whether the resource is an `Adapter`, `Group`, or typical `Resource`. For more
- information, see [DSC Resource kind schema reference][03].
+- **Kind** - Whether the resource is an `adapter`, `group`, `importer`, or typical `Resource`. For
+ 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.
+ indicating it has the `get`, `set`, and `delete` capabilities.
- **RequireAdapter** - The fully qualified type name of the adapter resource that DSC uses to
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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md
index 1073b1c..261d209 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md
index 215244c..17f2fb9 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource set' command
-ms.date: 03/06/2024
+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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md
index 6832651..0ebdab6 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'dsc resource test' command
-ms.date: 03/06/2024
+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/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md
deleted file mode 100644
index 343cd5c..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md
+++ /dev/null
@@ -1,225 +0,0 @@
----
-description: Command line reference for the 'dsc schema' command
-ms.date: 06/24/2024
-ms.topic: reference
-title: dsc schema
----
-
-# dsc schema
-
-## Synopsis
-
-Gets the JSON schema for a DSC type.
-
-## Syntax
-
-```sh
-dsc schema [Options] --type
-```
-
-## Description
-
-The `schema` command returns the JSON schema for a specific DSC type. These schemas can be used to
-validate the return data from the application or to generate compatible type definitions for an
-integrating tool.
-
-The application uses these schemas to validate data internally when it's received or represent the
-output for one of the application's commands.
-
-## Examples
-
-### Example 1 - Retrieve the schema for the dsc resource get command result
-
-```sh
-dsc schema --type get-result
-```
-
-```yaml
-$schema: http://json-schema.org/draft-07/schema#
-title: GetResult
-anyOf:
-- $ref: '#/definitions/ResourceGetResponse'
-- type: array
- items:
- $ref: '#/definitions/ResourceGetResult'
-definitions:
- ResourceGetResponse:
- type: object
- required:
- - actualState
- properties:
- actualState:
- description: The state of the resource as it was returned by the Get method.
- additionalProperties: false
- ResourceGetResult:
- type: object
- required:
- - name
- - result
- - type
- properties:
- metadata:
- anyOf:
- - $ref: '#/definitions/Metadata'
- - type: 'null'
- name:
- type: string
- type:
- type: string
- result:
- $ref: '#/definitions/GetResult'
- additionalProperties: false
- Metadata:
- type: object
- properties:
- Microsoft.DSC:
- anyOf:
- - $ref: '#/definitions/MicrosoftDscMetadata'
- - type: 'null'
- MicrosoftDscMetadata:
- type: object
- properties:
- version:
- description: Version of DSC
- type:
- - string
- - 'null'
- operation:
- description: The operation being performed
- anyOf:
- - $ref: '#/definitions/Operation'
- - type: 'null'
- executionType:
- description: The type of execution
- anyOf:
- - $ref: '#/definitions/ExecutionKind'
- - type: 'null'
- startDatetime:
- description: The start time of the configuration operation
- type:
- - string
- - 'null'
- endDatetime:
- description: The end time of the configuration operation
- type:
- - string
- - 'null'
- duration:
- description: The duration of the configuration operation
- type:
- - string
- - 'null'
- securityContext:
- description: The security context of the configuration operation, can be specified to be required
- anyOf:
- - $ref: '#/definitions/SecurityContextKind'
- - type: 'null'
- context:
- description: Identifies if the operation is part of a configuration
- anyOf:
- - $ref: '#/definitions/ContextKind'
- - type: 'null'
- Operation:
- type: string
- enum:
- - Get
- - Set
- - Test
- - Export
- ExecutionKind:
- type: string
- enum:
- - Actual
- - WhatIf
- SecurityContextKind:
- type: string
- enum:
- - Current
- - Elevated
- - Restricted
- ContextKind:
- type: string
- enum:
- - Configuration
- - Resource
- GetResult:
- anyOf:
- - $ref: '#/definitions/ResourceGetResponse'
- - type: array
- items:
- $ref: '#/definitions/ResourceGetResult'
-```
-
-## Options
-
-### -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
- document is invalid, DSC raises an error.
-- `configuration-get-result` ([reference documentation][07]) - Represents the output from the
- `dsc config get` command.
-- `configuration-set-result` ([reference documentation][08]) - Represents the output from the
- `dsc config set` command.
-- `configuration-test-result` ([reference documentation][09]) - Represents the output from the
- `dsc config test` command.
-
-```yaml
-Type: String
-Mandatory: true
-ValidValues: [
- dsc-resource,
- resource-manifest,
- get-result,
- set-result,
- test-result,
- configuration,
- configuration-get-result,
- configuration-set-result,
- configuration-test-result
- ]
-```
-
-### -f, --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.
-
-```yaml
-Type: String
-Mandatory: false
-DefaultValue: yaml
-ValidValues: [json, pretty-json, yaml]
-```
-
-### -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]: ../../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
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/index.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/index.md
new file mode 100644
index 0000000..ed79f8c
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/index.md
@@ -0,0 +1,293 @@
+---
+description: Command line reference for the 'dsc schema' command
+ms.date: 03/25/2025
+ms.topic: reference
+title: dsc schema
+---
+
+# dsc schema
+
+## Synopsis
+
+Gets the JSON schema for a DSC type.
+
+## Syntax
+
+```sh
+dsc schema [Options] --type
+```
+
+## Description
+
+The `schema` command returns the JSON schema for a specific DSC type. These schemas can be used to
+validate the return data from the application or to generate compatible type definitions for an
+integrating tool.
+
+The application uses these schemas to validate data internally when it's received or represent the
+output for one of the application's commands.
+
+> [!NOTE]
+> Currently, the schemas returned by the `dsc schema` command and those published to GitHub are
+> not the same. The published schemas more fully describe and validate the data than the schemas
+> emitted by the command. The DSC team is working to canonicalize the schemas returned from the
+> command.
+>
+> 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 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.
+
+## Examples
+
+### Example 1 - Retrieve the schema for the dsc resource get command result
+
+
+
+```sh
+dsc schema --type get-result
+```
+
+```yaml
+$schema: http://json-schema.org/draft-07/schema#
+title: GetResult
+anyOf:
+- $ref: '#/definitions/ResourceGetResponse'
+- type: array
+ items:
+ $ref: '#/definitions/ResourceGetResult'
+definitions:
+ ResourceGetResponse:
+ type: object
+ required:
+ - actualState
+ properties:
+ actualState:
+ description: The state of the resource as it was returned by the Get method.
+ additionalProperties: false
+ ResourceGetResult:
+ type: object
+ required:
+ - name
+ - result
+ - type
+ properties:
+ metadata:
+ anyOf:
+ - $ref: '#/definitions/Metadata'
+ - type: 'null'
+ name:
+ type: string
+ type:
+ type: string
+ result:
+ $ref: '#/definitions/GetResult'
+ additionalProperties: false
+ Metadata:
+ type: object
+ properties:
+ Microsoft.DSC:
+ anyOf:
+ - $ref: '#/definitions/MicrosoftDscMetadata'
+ - type: 'null'
+ MicrosoftDscMetadata:
+ type: object
+ properties:
+ version:
+ description: Version of DSC
+ type:
+ - string
+ - 'null'
+ operation:
+ description: The operation being performed
+ anyOf:
+ - $ref: '#/definitions/Operation'
+ - type: 'null'
+ executionType:
+ description: The type of execution
+ anyOf:
+ - $ref: '#/definitions/ExecutionKind'
+ - type: 'null'
+ startDatetime:
+ description: The start time of the configuration operation
+ type:
+ - string
+ - 'null'
+ endDatetime:
+ description: The end time of the configuration operation
+ type:
+ - string
+ - 'null'
+ duration:
+ description: The duration of the configuration operation
+ type:
+ - string
+ - 'null'
+ securityContext:
+ description: The security context of the configuration operation, can be specified to be required
+ anyOf:
+ - $ref: '#/definitions/SecurityContextKind'
+ - type: 'null'
+ context:
+ description: Identifies if the operation is part of a configuration
+ anyOf:
+ - $ref: '#/definitions/ContextKind'
+ - type: 'null'
+ Operation:
+ type: string
+ enum:
+ - Get
+ - Set
+ - Test
+ - Export
+ ExecutionKind:
+ type: string
+ enum:
+ - Actual
+ - WhatIf
+ SecurityContextKind:
+ type: string
+ enum:
+ - Current
+ - Elevated
+ - Restricted
+ ContextKind:
+ type: string
+ enum:
+ - Configuration
+ - Resource
+ GetResult:
+ anyOf:
+ - $ref: '#/definitions/ResourceGetResponse'
+ - type: array
+ items:
+ $ref: '#/definitions/ResourceGetResult'
+```
+
+## Options
+
+### -t, --type
+
+
+
+
+This option is mandatory for the `schema` command. The value for this option determines which
+schema the application returns:
+
+- `configuration` ([reference documentation][01]) - Validates a DSC Configuration document. If the
+ document is invalid, DSC raises an error.
+- `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][06]) - Represents the output from the
+ `dsc config set` command.
+- `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
+Mandatory: true
+ValidValues: [
+ 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
+```
+
+### -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][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
+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 other options and arguments.
+
+```yaml
+Type : boolean
+Mandatory : false
+LongSyntax : --help
+ShortSyntax : -h
+```
+
+## 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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/osinfo.config.dsc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/osinfo.config.dsc.yaml
deleted file mode 100644
index 171b492..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/osinfo.config.dsc.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-resources:
- - name: Operating System Assertion
- type: DSC/AssertionGroup
- properties:
- $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
- resources:
- - name: Is64BitOS
- type: Microsoft/OSInfo
- properties:
- bitness: '64'
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-in-a-configuration.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-in-a-configuration.md
deleted file mode 100644
index 3d4ddb8..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-in-a-configuration.md
+++ /dev/null
@@ -1,572 +0,0 @@
----
-description: >
- Use the Microsoft/OSInfo resource to Use the Microsoft/OSInfo resource to validate operating
- system in a DSC Configuration Document.
-ms.date: 08/08/2022
-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
-> DSCv3. Don't use it in production.
-
-## Definition
-
-The configuration document defines a resource group called `Operating System Assertion` with an
-instance of the `Microsoft/OSInfo` resource.
-
-The resource group uses the `DSC/AssertionGroup` resource to ensure that the test method is called
-for every instance in the group, regardless of the actual configuration operation being applied.
-When DSC processes the resource group, it calls the test operation for the nested instances instead
-of the get and 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, pass the contents of the
-document to the `dsc config get` command.
-
-# [Linux](#tab/linux)
-
-```bash
-configuration=$(cat ./osinfo.config.dsc.yaml)
-echo configuration | dsc config get
-```
-
-# [macOS](#tab/macos)
-
-```zsh
-configuration=$(cat ./osinfo.config.dsc.yaml)
-echo configuration | dsc config get
-```
-
-# [Windows](#tab/windows)
-
-```powershell
-$Configuration = Get-Content -Path ./osinfo.config.dsc.yaml -Raw
-$Configuration | dsc config get
-```
-
----
-
-The output depends on whether the operating system is 32-bit or 64-bit.
-
-# [32-bit Linux](#tab/32bit/linux)
-
-Applied to 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
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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: Linux
- version: '20.04'
- codename: focal
- bitness: '32'
- architecture: i386
- inDesiredState: false
- differingProperties:
- - bitness
- messages: []
- hadErrors: false
-messages: []
-hadErrors: false
-```
-
-# [64-bit Linux](#tab/64bit/linux)
-
-Applied to a 64-bit Linux operating system, the get result shows that the `Is64BitOS` instance is
-in the desired state.
-
-```yaml
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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: Linux
- version: '20.04'
- codename: focal
- bitness: '64'
- architecture: x86_64
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
-messages: []
-hadErrors: false
-```
-
-# [32-bit macOS](#tab/32bit/macos)
-
-Applied to 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
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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: MacOS
- version: 13.5.0
- bitness: '32'
- architecture: arm
- inDesiredState: false
- differingProperties:
- - bitness
- messages: []
- hadErrors: false
-messages: []
-hadErrors: false
-```
-
-# [64-bit macOS](#tab/64bit/macos)
-
-Applied to a 64-bit macOS operating system, the get result shows that the `Is64BitOS` instance is
-in the desired state.
-
-```yaml
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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: MacOS
- version: 13.5.0
- bitness: '64'
- architecture: arm64
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
-messages: []
-hadErrors: false
-```
-
-# [32-bit Windows](#tab/32bit/windows)
-
-Applied to 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
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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
-messages: []
-hadErrors: false
-```
-
-# [64-bit Windows](#tab/64bit/windows)
-
-Applied to a 64-bit Windows operating system, the get result shows that the `Is64BitOS` instance is
-in the desired state.
-
-```yaml
-results:
-- name: Operating System Assertion
- type: DSC/AssertionGroup
- result:
- actualState:
- 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: '64'
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
-messages: []
-hadErrors: false
-```
-
----
-
-## Enforcing the desired state
-
-To enforce the desired state of the instances in the configuration document, pass the contents of
-the document to the `dsc config set` command.
-
-# [Linux](#tab/linux)
-
-```bash
-echo configuration | dsc config set
-```
-
-# [macOS](#tab/macos)
-
-```zsh
-echo configuration | dsc config set
-```
-
-# [Windows](#tab/windows)
-
-```powershell
-$Configuration | dsc config set
-```
-
----
-
-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 `DSC/AssertionGroup` resource group
-never changes system state and the `Microsoft/OSInfo` resource doesn't implement the set operation.
-
-# [32-bit Linux](#tab/32bit/linux)
-
-```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: Linux
- version: '20.04'
- codename: focal
- bitness: '32'
- architecture: i386
- 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: Linux
- version: '20.04'
- codename: focal
- bitness: '32'
- architecture: i386
- inDesiredState: false
- differingProperties:
- - bitness
- messages: []
- hadErrors: false
- changedProperties: []
-messages: []
-hadErrors: false
-```
-
-# [64-bit Linux](#tab/64bit/linux)
-
-```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: Linux
- version: '20.04'
- codename: focal
- bitness: '64'
- architecture: x86_64
- inDesiredState: true
- differingProperties: []
- 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: Linux
- version: '20.04'
- codename: focal
- bitness: '64'
- architecture: x86_64
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
- changedProperties: []
-messages: []
-hadErrors: false
-```
-
-# [32-bit macOS](#tab/32bit/macos)
-
-```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: MacOS
- version: 13.5.0
- bitness: '32'
- architecture: arm
- 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: MacOS
- version: 13.5.0
- bitness: '32'
- architecture: arm
- inDesiredState: false
- differingProperties:
- - bitness
- messages: []
- hadErrors: false
- changedProperties: []
-messages: []
-hadErrors: false
-```
-
-# [64-bit macOS](#tab/64bit/macos)
-
-```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: MacOS
- version: 13.5.0
- bitness: '64'
- architecture: arm64
- inDesiredState: true
- differingProperties: []
- 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: MacOS
- version: 13.5.0
- bitness: '64'
- architecture: arm64
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
- 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
-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: '64'
- inDesiredState: true
- differingProperties: []
- 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: '64'
- inDesiredState: true
- differingProperties: []
- messages: []
- hadErrors: false
- changedProperties: []
-messages: []
-hadErrors: false
-```
-
----
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/overview.md
deleted file mode 100644
index 8d54d98..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/overview.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-description: >-
- Reference documentation for the osinfo command and the Microsoft/OSInfo DSC Resource provided by
- the command.
-ms.date: 08/18/2023
-ms.topic: reference
-title: The osinfo command and Microsoft/OSInfo DSC Resource
----
-
-# The osinfo command and Microsoft/OSInfo DSC Resource
-
-DSCv3 includes an example command, `registry`, for managing keys and values in the Windows
-registry. The command is also a [command-based DSC Resource][01].
-
-> [!IMPORTANT]
-> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with
-> DSCv3. Don't use it in production.
-
-You can use `osinfo` to:
-
-- Get information about the operating system.
-- Invoke the `Microsoft/OSInfo` resource with DSC to validate operating system information.
-- Define instances of the `Microsoft/OSInfo` resource in DSC Configuration Documents.
-
-For more information about using `osinfo` as a command, see [osinfo][02]. For more information
-about using `osinfo` with DSC, see [Microsoft/OSInfo][03].
-
-
-[01]: ../../../resources/concepts/anatomy.md
-[02]: cli/osinfo.md
-[03]: resource.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/resource.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/resource.md
deleted file mode 100644
index 48cdebf..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/resource.md
+++ /dev/null
@@ -1,164 +0,0 @@
----
-description: Microsoft/OSInfo resource reference documentation
-ms.date: 08/18/2023
-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
-> DSCv3. Don't use it in production.
-
-## Metadata
-
-```yaml
-Version: 0.1.0
-Tags: [os, linux, windows, macos]
-```
-
-## 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 depends 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` |
-
-## Requirements
-
-None.
-
-## Examples
-
-- [Validate operating system information with dsc resource][02]
-- [Validate operating system information in a configuration][03]
-
-## Instance properties
-
-The following properties are optional. They define the desired state for an instance of the
-resource.
-
-### architecture
-
-Defines the processor architecture as reported by `uname -m` on the operating system. The resource
-doesn't return this property for Windows machines.
-
-```yaml
-Type: string
-Required: false
-```
-
-### bitness
-
-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`.
-
-```yaml
-Type: string
-Required: false
-ValidValues: ['32', '64', unknown]
-```
-
-### codename
-
-Defines the codename for the operating system as returned from `lsb_release --codename`. The
-resource only returns this property for Linux machines.
-
-```yaml
-Type: string
-Required: false
-```
-
-### edition
-
-Defines the operating system edition, like `Windows 11` or `Windows Server 2016`. The resource only
-returns this property for Windows machines.
-
-```yaml
-Type: string
-Required: false
-```
-
-### family
-
-Defines whether the operating system is Linux, macOS, or Windows.
-
-```yaml
-Type: string
-Required: false
-ValidValues: [Linux, MacOS, Windows]
-```
-
-### version
-
-Defines the version of the operating system as a string.
-
-```yaml
-Type: string
-Required: false
-```
-
-## Read-only properties
-
-Don't include the following properties in an instance definition. If they're included in an
-instance definition, the resource ignores them. The resource returns a value for these properties.
-
-### $id
-
-Returns the unique ID for the OSInfo instance data type.
-
-```yaml
-Type: string
-ConstantValue: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
-```
-
-## Exit Codes
-
-The resource uses the following exit codes to report success and errors:
-
-- `0` - Success
-- `1` - Error
-
-## See also
-
-- [Command line reference for the osinfo command][04]
-
-
-[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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/get.md
deleted file mode 100644
index 2f95773..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/get.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-description: Command line reference for the 'registry config get' command
-ms.date: 08/22/2023
-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] --key-path
-```
-
-## 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 from
-stdin.
-
-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
-$InputInstance = @{
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
-} | ConvertTo-Json
-
-$InputInstance | registry config get
-```
-
-```Output
-{"$id":"https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json","keyPath":"HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion"}
-```
-
-When the specified key doesn't exist, the `keyPath` property is an empty string.
-
-```powershell
-$InputInstance = @{
- keyPath = 'HKCU\Example\Nested\Key'
-} | ConvertTo-Json
-
-$InputInstance | registry config get
-```
-
-```Output
-{"$id":"https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json","keyPath":""}
-```
-
-### 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
-$InputInstance = @{
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
- valueName = 'SystemRoot'
-} | ConvertTo-Json
-
-$InputInstance | registry config get | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion
-valueName : SystemRoot
-valueData : @{String=C:\WINDOWS}
-```
-
-## 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
-```
-
-
-[01]: ../../resource.md#keypath
-[02]: ../../resource.md#valuename
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/set.md
deleted file mode 100644
index df19ee9..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/set.md
+++ /dev/null
@@ -1,189 +0,0 @@
----
-description: Command line reference for the 'registry config set' command
-ms.date: 08/22/2023
-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 set [Options] --key-path
-```
-
-## 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 from
-stdin.
-
-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.
-
-For more information about the available properties for configuring registry keys and values, see
-[Microsoft.Windows/Registry][03].
-
-## Examples
-
-### Example 1 - Ensure a registry key exists
-
-Because the input instance defines the `_ensure` property as `Present`,the command creates the
-`HKCU\Example\Key` if it doesn't exist.
-
-```powershell
-$InputInstance = @{
- _ensure = 'Present'
- keyPath = 'HKCU\Example\Key'
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-$InputInstance | registry config set | ConvertFrom-Json | Format-List
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath :
-_inDesiredState : False
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath :
-_inDesiredState : True
-```
-
-### Example 2 - Ensure a registry key doesn't exist
-
-Because the input instance defines the `_ensure` property as `Absent`,the command deletes the
-`HKCU\Example\Key` if it exists.
-
-```powershell
-$InputInstance = @{
- _ensure = 'Absent'
- keyPath = 'HKCU\Example\Key'
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-$InputInstance | registry config set | ConvertFrom-Json | Format-List
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-_inDesiredState : False
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath :
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath :
-_inDesiredState : True
-```
-
-### Example 3 - Ensure a registry value exists
-
-The instance combines the values of the `keyPath`, `valueName`, and `valueData` properties to
-ensure that the `Example\Key` 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 = @{
- _ensure = 'Present'
- keyPath = 'HKCU\Example\Key'
- valueName = 'ExampleValue'
- valueData = @{
- String = 'SomeValue'
- }
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-$InputInstance | registry config set | ConvertFrom-Json | Format-List
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath :
-_inDesiredState : False
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-valueName : ExampleValue
-valueData : @{String=SomeValue}
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-valueName : ExampleValue
-valueData : @{String=SomeValue}
-_inDesiredState : True
-```
-
-### Example 4 - Ensure a registry value has specific data
-
-When setting a registry value that already exists, the `_clobber` property indicates that the
-command should override the existing value data if it isn't the desired data.
-
-```powershell
-$InputInstance = @{
- _ensure = 'Present'
- _clobber = $true
- keyPath = 'HKCU\Example\Key'
- valueName = 'ExampleValue'
- valueData = @{
- String = 'NewValue'
- }
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-$InputInstance | registry config set | ConvertFrom-Json | Format-List
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-_inDesiredState : False
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-valueName : ExampleValue
-valueData : @{String=NewValue}
-
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKCU\Example\Key
-valueName : ExampleValue
-valueData : @{String=NewValue}
-_inDesiredState : True
-```
-
-## 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
-```
-
-
-[01]: ../../resource.md#keypath
-[02]: ../../resource.md#valuename
-[03]: ../../resource.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/test.md
deleted file mode 100644
index 6340976..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/test.md
+++ /dev/null
@@ -1,137 +0,0 @@
----
-description: Command line reference for the 'registry config test' command
-ms.date: 08/22/2023
-ms.topic: reference
-title: registry config test
----
-
-# registry config test
-
-## Synopsis
-
-Validate 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 test [Options] --key-path
-```
-
-## Description
-
-The `test` command validates whether a registry key or value is in the desired state. It expects
-input as a JSON instance of the `Microsoft.Windows/Registry` resource from stdin. It uses the
-properties of the input resource as the desired state of the registry key or value.
-
-The command returns an instance of the resource with the [_inDesiredState][01] set to a boolean
-value indicating whether the registry key or value is in the desired state. The other properties
-for the returned instance represent the current state of the instance.
-
-The input instance must define the [keyPath][02] property. It uses the `keyPath` value to determine
-which registry key to validate. If the input instance includes the [valueName][03] property, the
-command validates the current state of that value instead of the registry key.
-
-For more information about the available properties for configuring registry keys and values, see
-[Microsoft.Windows/Registry][04].
-
-## Examples
-
-### Example 1 - Test whether a registry key exists
-
-The command validates that the registry key exists.
-
-```powershell
-$InputInstance = @{
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
-} | ConvertTo-Json
-
-$InputInstance | registry config test
-```
-
-```Output
-{"$id":"https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json","keyPath":"","_inDesiredState":true}
-```
-
-With the `_ensure` property explicitly set to `Absent`, the command validates that the registry key
-doesn't exist.
-
-```powershell
-$InputInstance = @{
- _ensure = 'Absent'
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion
-_inDesiredState : False
-```
-
-### Example 2 - Test a registry value
-
-The command validates whether the `SystemRoot` value exists. It doesn't validate the value's data.
-
-```powershell
-$InputInstance = @{
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
- valueName = 'SystemRoot'
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion
-valueName : SystemRoot
-valueData : @{String=C:\WINDOWS}
-_inDesiredState : True
-```
-
-With the `valueData` property defined for the input instance, the command validates that the value
-data is in the desired state.
-
-```powershell
-$InputInstance = @{
- keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
- valueName = 'SystemRoot'
- valueData = @{
- String = 'D:\_windows'
- }
-} | ConvertTo-Json
-
-$InputInstance | registry config test | ConvertFrom-Json | Format-List
-```
-
-```Output
-$id : https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-keyPath : HKLM\Software\Microsoft\Windows NT\CurrentVersion
-valueName : SystemRoot
-valueData : @{String=C:\WINDOWS}
-_inDesiredState : False
-```
-
-## 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
-```
-
-
-[01]: ../../resource.md#_indesiredstate
-[02]: ../../resource.md#keypath
-[03]: ../../resource.md#valuename
-[04]: ../../resource.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/test/command.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/test/command.md
deleted file mode 100644
index c22e058..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/test/command.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-description: Command line reference for the 'registry test' command
-ms.date: 08/22/2023
-ms.topic: reference
-title: registry test
----
-
-# registry test
-
-## Synopsis
-
-Validate registry matches input JSON.
-
-> [!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 test [Options]
-```
-
-## Description
-
-The `test` command isn't implemented yet. It returns the string `Test`.
-
-## 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
-```
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Add-RegistryKey.ps1 b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Add-RegistryKey.ps1
deleted file mode 100644
index 53b5991..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Add-RegistryKey.ps1
+++ /dev/null
@@ -1,21 +0,0 @@
-[CmdletBinding()]
-param()
-
-begin {
- $Resource = dsc resource list Microsoft.Windows/Registry
- $InstanceProperties = @{
- _ensure = 'Present'
- keyPath = 'HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey'
- } | ConvertTo-Json
-}
-
-process {
- $TestResult = $InstanceProperties | dsc resource test --resource $Resource |
- ConvertFrom-Json
-
- if ($TestResult.actualState._inDesiredState) {
- $InstanceProperties | dsc resource get --resource $Resource
- } else {
- $InstanceProperties | dsc resource set --resource $Resource
- }
-}
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryKey.ps1 b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryKey.ps1
deleted file mode 100644
index eb4ce3b..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryKey.ps1
+++ /dev/null
@@ -1,21 +0,0 @@
-[CmdletBinding()]
-param()
-
-begin {
- $Resource = dsc resource list Microsoft.Windows/Registry
- $InstanceProperties = @{
- _ensure = 'Absent'
- keyPath = 'HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey'
- } | ConvertTo-Json
-}
-
-process {
- $TestResult = $InstanceProperties | dsc resource test --resource $Resource |
- ConvertFrom-Json
-
- if ($TestResult.actualState._inDesiredState) {
- $InstanceProperties | dsc resource get --resource $Resource
- } else {
- $InstanceProperties | dsc resource set --resource $Resource
- }
-}
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryValue.ps1 b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryValue.ps1
deleted file mode 100644
index da0fdf5..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Remove-RegistryValue.ps1
+++ /dev/null
@@ -1,23 +0,0 @@
-[CmdletBinding()]
-param()
-
-begin {
- $Resource = dsc resource list Microsoft.Windows/Registry
- $InstanceProperties = @{
- _ensure = 'Absent'
- keyPath = 'HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey'
- } | ConvertTo-Json
-}
-
-process {
- $TestResult = $InstanceProperties | dsc resource test --resource $Resource |
- ConvertFrom-Json
-
- if ($TestResult.actualState._inDesiredState) {
- write-warning "config get"
- $InstanceProperties | dsc resource get --resource $Resource
- } else {
- write-warning "config set"
- $InstanceProperties | dsc resource set --resource $Resource
- }
-}
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Set-RegistryValue.ps1 b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Set-RegistryValue.ps1
deleted file mode 100644
index 0793343..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Set-RegistryValue.ps1
+++ /dev/null
@@ -1,28 +0,0 @@
-[CmdletBinding()]
-param()
-
-begin {
- $Resource = dsc resource list Microsoft.Windows/Registry
- $InstanceProperties = @{
- _ensure = 'Present'
- _clobber = $true
- keyPath = 'HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey'
- valueName = 'MyValue'
- valueData = @{
- Binary = @(0x00)
- }
- } | ConvertTo-Json
-}
-
-process {
- $TestResult = $InstanceProperties | dsc resource test --resource $Resource |
- ConvertFrom-Json
-
- if ($TestResult.actualState._inDesiredState) {
- write-warning "config get"
- $InstanceProperties | dsc resource get --resource $Resource
- } else {
- write-warning "config set"
- $InstanceProperties | dsc resource set --resource $Resource
- }
-}
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Update-RegistryValue.ps1 b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Update-RegistryValue.ps1
deleted file mode 100644
index d2653f7..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/Update-RegistryValue.ps1
+++ /dev/null
@@ -1,28 +0,0 @@
-[CmdletBinding()]
-param()
-
-begin {
- $Resource = dsc resource list Microsoft.Windows/Registry
- $InstanceProperties = @{
- _ensure = 'Present'
- _clobber = $true
- keyPath = 'HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey'
- valueName = 'MyValue'
- valueData = @{
- String = 'New Value'
- }
- } | ConvertTo-Json
-}
-
-process {
- $TestResult = $InstanceProperties | dsc resource test --resource $Resource |
- ConvertFrom-Json
-
- if ($TestResult.actualState._inDesiredState) {
- write-warning "config get"
- $InstanceProperties | dsc resource get --resource $Resource
- } else {
- write-warning "config set"
- $InstanceProperties | dsc resource set --resource $Resource
- }
-}
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/configure-registry-keys-and-values.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/configure-registry-keys-and-values.md
deleted file mode 100644
index e46898e..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/configure-registry-keys-and-values.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-description: >
- Use the Microsoft.Windows/Registry resource to configure a set of registry keys and values in
- a DSC Configuration Document.
-ms.date: 08/08/2022
-ms.topic: reference
-title: Configure keys and values with Microsoft.Windows/Registry
----
-
-# Configure keys and values with Microsoft.Windows/Registry
-
-This example shows how you can use the `Microsoft.Windows/Registry` resource to manage several
-registry keys and values in a DSC Configuration Document.
-
-> [!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.
-
-## Definition
-
-The configuration document defines three instances of the resource:
-
-- The instance named `Tailspin Key` ensures that the key `tailspin` exists in the current user
- hive.
-- The instance named `Tailspin - Update automatically` ensures that the `updates` sub-key exists
- under the `tailspin` key and has the `automatic` value set to the string `enable`.
-
-
-
-:::code language="yaml" source="registry.config.dsc.yaml" range="1,15":::
-
-## Enforcing state
-
-### First apply
-
-The first time the configuration applies to the machine, it creates the registry keys and value.
-
-```powershell
-$Configuration = Get-Content -Path ./registry.config.dsc.yaml
-$Configuration | dsc config set
-```
-
-```yaml
-results:
-- name: Tailspin Key
- type: Microsoft.Windows/Registry
- result:
- beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
- afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin
- changedProperties:
- - keyPath
-- name: Tailspin - Update automatically
- type: Microsoft.Windows/Registry
- result:
- beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
- afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin\updates
- valueName: automatic
- valueData:
- String: enable
- changedProperties:
- - keyPath
- - valueName
- - valueData
-messages: []
-hadErrors: false
-```
-
-The operation changed the `keyPath` property for the `Tailspin Key` instance. It changed the
-`keyPath`, `valueName`, and `valueData` properties for the `Tailspin - Update automatically`
-instance.
-
-### Second apply
-
-The first time the configuration applies to the machine, it makes no changes. The instances are
-already in the desired state.
-
-```powershell
-$Configuration | dsc config set
-```
-
-```yaml
-results:
-- name: Tailspin Key
- type: Microsoft.Windows/Registry
- result:
- beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin
- afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin
- changedProperties: []
-- name: Tailspin - Update automatically
- type: Microsoft.Windows/Registry
- result:
- beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin\updates
- valueName: automatic
- valueData:
- String: enable
- afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\tailspin\updates
- valueName: automatic
- valueData:
- String: enable
- changedProperties: []
-messages: []
-hadErrors: false
-```
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-key.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-key.md
deleted file mode 100644
index 2393891..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-key.md
+++ /dev/null
@@ -1,89 +0,0 @@
----
-description: >
- Manage whether a registry key exists with the Microsoft.Windows/Registry DSC Resource.
-ms.date: 08/08/2022
-ms.topic: reference
-title: Manage a registry key with Microsoft.Windows/Registry
----
-
-# Manage a registry key with Microsoft.Windows/Registry
-
-## Description
-
-This example shows how you can use the `Microsoft.Windows/Registry` resource to manage whether a
-registry key exists. These examples manage the
-`SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey` in the current user hive.
-
-> [!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.
-
-## Adding the key
-
-This script shows how you can use the resource with the `dsc resource` commands to ensure the
-`MyNewKey` registry key exists.
-
-With `_ensure` set to `Present`, the resource adds the `MyNewKey` registry key if it doesn't exist.
-
-:::code source="Add-RegistryKey.ps1":::
-
-### Set result
-
-When the resource creates the key with `dsc resource set`, it returns the following output:
-
-```yaml
-beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
-afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey
-changedProperties:
-- keyPath
-```
-
-### Get result
-
-When the resource is already in the desired state and is retrieved with `dsc resource get`, it
-returns the following output:
-
-```yaml
-actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey
-```
-
-## Removing the key
-
-This script shows how you can use the resource with the `dsc resource` commands to ensure the
-`MyNewKey` registry key doesn't exist.
-
-With `_ensure` set to `Absent`, the resource removes the `MyNewKey` registry key if it exists.
-
-:::code source="Remove-RegistryKey.ps1":::
-
-### Set result
-
-When the resource creates the key with `dsc resource set`, it returns the following output:
-
-```yaml
-beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey
-afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
-changedProperties:
-- keyPath
-```
-
-### Get result
-
-When the resource is already in the desired state and is retrieved with `dsc resource get`, it
-returns the following output:
-
-```yaml
-actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
-```
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-value.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-value.md
deleted file mode 100644
index a23cb79..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/manage-a-registry-value.md
+++ /dev/null
@@ -1,141 +0,0 @@
----
-description: >
- Manage the value of a registry key with the Microsoft.Windows/Registry DSC Resource.
-ms.date: 08/08/2022
-ms.topic: reference
-title: Manage a registry key value with Microsoft.Windows/Registry
----
-
-# Manage a registry key value with Microsoft.Windows/Registry
-
-## Description
-
-This example shows how you can use the `Microsoft.Windows/Registry` resource to manage whether a
-registry key exists. These examples manage the
-`SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey` in the current user hive.
-
-> [!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.
-
-## Adding the key and value
-
-This script shows how you can use the resource with the `dsc resource` commands to ensure the
-`MyKey` registry key exists with the `MyValue` value set to binary data `0x00`.
-
-With `_ensure` set to `Present`, the resource adds the registry key and value if they don't exist.
-
-:::code source="Set-RegistryValue.ps1":::
-
-### Set result
-
-When the resource creates the key with `dsc resource set`, it returns the following output:
-
-```yaml
-beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
-afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
- valueName: MyValue
- valueData:
- Binary:
- - 0
-changedProperties:
-- keyPath
-- valueName
-- valueData
-```
-
-### Get result
-
-When the resource is already in the desired state and is retrieved with `dsc resource get`, it
-returns the following output:
-
-```yaml
-actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
- valueName: MyValue
- valueData:
- Binary:
- - 0
-```
-
-## Updating the value
-
-This script shows how you can update an existing registry value to a new value and data type. It
-sets `MyValue` for the `MyKey` registry key to the string `New Value`.
-
-:::code source="Update-RegistryValue.ps1":::
-
-### Set result
-
-When the resource updates the value with `dsc resource set`, it returns the following output:
-
-```yaml
-beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
- valueName: MyValue
- valueData:
- Binary:
- - 0
-afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
- valueName: MyValue
- valueData:
- String: New Value
-changedProperties:
-- valueData
-```
-
-### Get result
-
-```yaml
-actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
- valueName: MyValue
- valueData:
- String: New Value
-```
-
-## Removing the key and value
-
-This script shows how you can use the resource with the `dsc resource` commands to ensure the
-`MyKey` registry key doesn't exist.
-
-With `_ensure` set to `Absent`, the resource removes the `MyKey` registry key if it exists. It also
-deletes any values the key had.
-
-:::code source="Remove-RegistryValue.ps1":::
-
-### Set result
-
-When the resource removes the key and value with `dsc resource set`, it returns the following
-output:
-
-```yaml
-beforeState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: HKCU\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyKey
-afterState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: ''
-changedProperties:
-- keyPath
-```
-
-### Get result
-
-When the resource is already in the desired state and is retrieved with `dsc resource get`, it
-returns the following output:
-
-```yaml
-actualState:
- $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
- keyPath: '
-```
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/registry.config.dsc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/registry.config.dsc.yaml
deleted file mode 100644
index 862af72..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/examples/registry.config.dsc.yaml
+++ /dev/null
@@ -1,23 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-resources:
- - name: Tailspin Key
- type: Microsoft.Windows/Registry
- properties:
- keyPath: HKCU\tailspin
- - name: Tailspin - Update automatically
- type: Microsoft.Windows/Registry
- properties:
- keyPath: HKCU\tailspin\updates
- valueName: automatic
- valueData:
- String: enable
-
- # Commented out due to a bug in the resource
- # - name: Tailspin - Update every 30 days
- # type: Microsoft.Windows/Registry
- # properties:
- # keyPath: HKCU\tailspin\updates
- # valueName: frequency
- # valueData:
- # DWord: 30
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/overview.md
deleted file mode 100644
index 513fe95..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/overview.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-description: >-
- Reference documentation for the registry command and the Microsoft.Windows/Registry DSC Resource
- provided by the command.
-ms.date: 08/18/2023
-ms.topic: reference
-title: The registry command and Microsoft.Windows/Registry DSC Resource
----
-
-# The registry command and Microsoft.Windows/Registry DSC Resource
-
-DSCv3 includes an example command, `registry`, for managing keys and values in the Windows
-registry. The command is also a [command-based DSC Resource][01].
-
-> [!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.
-
-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 command, see [registry][02]. For more information
-about using `registry` with DSC, see [Microsoft.Windows/Registry][03].
-
-
-[01]: ../../../../resources/concepts/anatomy.md
-[02]: cli/registry.md
-[03]: resource.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/resource.md b/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/resource.md
deleted file mode 100644
index 1e0c4b6..0000000
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/resource.md
+++ /dev/null
@@ -1,268 +0,0 @@
----
-description: Microsoft.Windows/Registry resource reference documentation
-ms.date: 08/18/2023
-ms.topic: reference
-title: Microsoft.Windows/Registry
----
-
-# Microsoft.Windows/Registry
-
-## Synopsis
-
-Registry configuration provider for the 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.
-
-## Metadata
-
-```yaml
-Version: 0.1.0
-Tags: [Windows, NT]
-```
-
-## Instance definition syntax
-
-```yaml
-resources:
- - name:
- type: Microsoft.Windows/Registry
- properties:
- # Required properties
- keyPath: string
- # Instance properties
- _ensure:
- valueData:
- valueName:
- # Write-only properties
- _clobber:
-```
-
-## 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.
-
-## 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].
-
-## Examples
-
-- [Manage a registry key][02]
-- [Manage a registry value][03]
-- [Configure a set of registry keys and values][04]
-
-## Required properties
-
-The following properties are required for specifying an instance of the resource:
-
-- [keyPath](#keypath)
-
-### keyPath
-
-Defines the path to the registry key for the instance. 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
-Required: true
-```
-
-## Instance properties
-
-The following properties are optional. They define the desired state for an instance of the
-resource.
-
-### _ensure
-
-Defines whether the registry key or value should exist. The default value is `Present`.
-
-When `_ensure` is `Present`, the instance should exist. If it doesn't exist, the resource creates
-the instance during the set operation.
-
-When `_ensure` is `Absent`, the instance shouldn't exist. If it does exist, the resource removes
-the instance during the set operation.
-
-```yaml
-Type: string
-Required: false
-Default: Present
-ValidValues: [Present, Absent]
-```
-
-### valueData
-
-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.
-
-For more information on registry value data types, see [Registry value types][05].
-
-```yaml
-Type: object
-Required: false
-```
-
-#### String valueData
-
-Defines the registry value data as a null-terminated UTF-16 string. The resource handles
-terminating the string.
-
-```yaml
-PropertyName: String
-ValueType: string
-```
-
-#### ExpandString valueData
-
-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.
-
-```yaml
-PropertyName: ExpandString
-ValueType: string
-```
-
-#### MultiString valueData
-
-Defines the registry value data as a sequence of null-terminated UTF-16 strings. The resource
-handles terminating the strings.
-
-```yaml
-PropertyName: MultiString
-ValueType: array
-ValueItemsMustBeUnique: false
-ValueItemsType: string
-```
-
-#### Binary valueData
-
-Defines the registry value data as binary data in any form. The value must be an array
-of 8-bit unsigned integers.
-
-```yaml
-PropertyName: Binary
-ValueType: array
-ValueItemsMustBeUnique: false
-ValueItemsType: integer
-ValueItemsMinimum: 0
-ValueItemsMaximum: 255
-```
-
-#### DWord valueData
-
-Defines the registry value data as a 32-bit unsigned integer.
-
-```yaml
-PropertyName: DWord
-ValueType: integer
-ValueMinimum: 0
-ValueMaximum: 4294967295
-```
-
-#### QWord valueData
-
-Defines the registry value data as a 64-bit unsigned integer.
-
-```yaml
-PropertyName: QWord
-ValueType: integer
-ValueMinimum: 0
-ValueMaximum: 18446744073709551615
-```
-
-### valueName
-
-Defines the name of the value to manage for the registry key. This property is required when
-specifying the `valueData` property.
-
-```yaml
-Type: string
-Required: false
-```
-
-## Write-only properties
-
-The following properties are optional. When included in an instance definition, they change how the
-resource processes the instance. The resource never returns a value for these properties from an
-operation.
-
-### _clobber
-
-Indicates whether the registry value should be overwritten if it already exists.
-
-> [!NOTE]
-> The resource instance schema defines this property but it isn't implemented yet.
-
-```yaml
-Type: boolean
-Required: false
-```
-
-## Read-only properties
-
-Don't include the following properties in an instance definition. If they're included in an
-instance definition, the resource ignores them. The resource returns a value for these properties.
-
-### $id
-
-Returns the unique ID for the registry instance data type.
-
-```yaml
-Type: string
-ConstantValue: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-```
-
-### _inDesiredState
-
-When the resource is invoked for the test method, the `_inDesiredState` property indicates whether
-the current state of the instance is the same as the desired state. If the value is `true`, the
-instance is in the desired state. If the value is `false`, the instance isn't in the desired state.
-
-For all other operations, the resource returns this property set to `null`.
-
-```yaml
-Type: [boolean, 'null']
-```
-
-## Exit Codes
-
-The resource uses the following exit codes to report success and errors:
-
-- `0` - Success
-- `1` - Invalid parameter
-- `2` - Invalid input
-- `3` - Registry error
-- `4` - JSON serialization failed
-
-## See also
-
-- [Command line reference for the registry command][06]
-- [About the Registry][07]
-
-
-[01]: /windows/win32/sysinfo/registry-key-security-and-access-rights
-[02]: examples/manage-a-registry-key.md
-[03]: examples/manage-a-registry-value.md
-[04]: examples/configure-registry-keys-and-values.md
-[05]: /windows/win32/sysinfo/registry-value-types
-[06]: cli/registry.md
-[07]: /windows/win32/sysinfo/about-the-registry
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml
new file mode 100644
index 0000000..4ab8249
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/validate-in-a-configuration.md
new file mode 100644
index 0000000..e696911
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-with-dsc-resource.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md
similarity index 70%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-with-dsc-resource.md
rename to dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md
index a118d42..b229a31 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/examples/validate-with-dsc-resource.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md
@@ -2,7 +2,7 @@
description: >
Validate operating system information with the Microsoft/OSInfo DSC Resource
and the dsc resource commands.
-ms.date: 08/08/2022
+ms.date: 03/25/2025
ms.topic: reference
title: Validate operating system information with dsc resource
---
@@ -16,19 +16,18 @@ 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
-> DSCv3. Don't use it in production.
+> DSC. Don't use it in production.
## Getting the operating system information
-The `dsc resource get` 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.
+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
-resource=$(dsc resource list Microsoft/OSInfo)
-dsc resource get -r "${resource}"
+dsc resource get -r Microsoft/OSInfo
```
```yaml
@@ -45,7 +44,7 @@ actualState:
```zsh
resource=$(dsc resource list Microsoft/OSInfo)
-dsc resource get -r "${resource}"
+dsc resource get -r Microsoft/OSInfo
```
```yaml
@@ -60,8 +59,7 @@ actualState:
# [Windows](#tab/windows)
```powershell
-$Resource = dsc resource list Microsoft/OSInfo
-dsc resource get -r $Resource
+dsc resource get --resource Microsoft/OSInfo
```
```yaml
@@ -77,22 +75,23 @@ actualState:
## Testing the operating system information
-DSC can use the resource to validate the operating system information. When using the
-`dsc resource test` command, input JSON representing the desired state of the instance is required.
-The JSON must define at least one instance property to validate.
+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][01]. It relies on the synthetic testing feature
+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`.
+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}"
+invalid_instance='{"family": "Linux"}'
+echo $invalid_instance | dsc resource test -r "${resource}" -f -
```
```yaml
@@ -113,11 +112,12 @@ differingProperties:
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.
+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 "${resource}"
+echo $valid_instance | dsc resource test -r Microsoft/OSInfo -i $valid_instance
```
```yaml
@@ -137,11 +137,12 @@ differingProperties: []
# [macOS](#tab/macos)
-This test checks whether the `family` property for the instance is `linux`.
+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 "${resource}"
+echo $invalid_instance | dsc resource test -r Microsoft/OSInfo -f -
```
```yaml
@@ -161,11 +162,12 @@ differingProperties:
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.
+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" }'
-echo $valid_instance | dsc resource test -r "${resource}"
+dsc resource test -r Microsoft/OSInfo -i $valid_instance
```
```yaml
@@ -184,11 +186,12 @@ differingProperties: []
# [Windows](#tab/windows)
-This test checks whether the `family` property for the instance is `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 -r $Resource
+$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON
+$invalidInstance | dsc resource test --resource Microsoft/OSInfo --file -
```
```yaml
@@ -208,15 +211,16 @@ differingProperties:
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.
+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 = @{
+$validInstance = @{
family = 'Windows'
bitness = '64'
} | ConvertTo-JSON
-$ValidInstance | dsc resource test -r $Resource
+dsc resource test --resource Microsoft/OSInfo --input $validInstance
```
```yaml
@@ -235,5 +239,7 @@ differingProperties: []
---
-
-[01]: ../../../../concepts/resources.md#test-operations
+
+[01]: ../../../../cli/resource/get.md
+[02]: ../../../../cli/resource/test.md
+[03]: ../../../../../concepts/resources/overview.md#test-operations
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/index.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/OSInfo/index.md
new file mode 100644
index 0000000..9e72cd4
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md
new file mode 100644
index 0000000..2915220
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md
new file mode 100644
index 0000000..9ef4386
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md
new file mode 100644
index 0000000..da9a4de
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/registry.cleanup.config.dsc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/registry.cleanup.config.dsc.yaml
new file mode 100644
index 0000000..1a7b821
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/registry.config.dsc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/examples/registry.config.dsc.yaml
new file mode 100644
index 0000000..66a1ef6
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/index.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/Microsoft/Windows/Registry/index.md
new file mode 100644
index 0000000..ee107aa
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/resources/builtin.md b/dsc/docs-conceptual/dsc-3.0/reference/resources/builtin.md
new file mode 100644
index 0000000..7d989c5
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/reference/resources/builtin.md
@@ -0,0 +1,75 @@
+---
+description: >-
+ Lists the builtin DSC resources and links to the reference documentation for those resources.
+ms.date: 03/25/2025
+title: Builtin DSC resources reference
+---
+
+# Builtin DSC resources reference
+
+Each release of DSC includes builtin resources that you can use immediately after you install DSC.
+This document lists the available resources and links to the reference documentation for each.
+
+> [!NOTE]
+> The team hasn't documented every builtin resource yet. As they add reference documentation for
+> these resources, the team will update this article to link to the documentation for those
+> resources.
+
+## All builtin resources
+
+- [Microsoft/OSInfo][01] - Returns information about the operating system.
+- `Microsoft.DSC/Assertion`
+- `Microsoft.DSC/Group`
+- `Microsoft.DSC/Include`
+- `Microsoft.DSC/PowerShell`
+- `Microsoft.DSC.Debug/Echo`
+- `Microsoft.DSC.Transitional/RunCommandOnSet`
+- `Microsoft.Windows/RebootPending`
+- [Microsoft.Windows/Registry][09] - Manage Windows Registry keys and values.
+- `Microsoft.Windows/WindowsPowerShell`
+- `Microsoft.Windows/WMI`
+
+## Builtin assertion resources
+
+You can use the following builtin resources to query the current state of a machine but not to
+change the state of the machine directly:
+
+- [Microsoft/OSInfo][01] - Returns information about the operating system.
+- `Microsoft.DSC/Assertion`
+- `Microsoft.Windows/RebootPending`
+
+## Builtin adapter resources
+
+You can use the following builtin resources to handle resources that don't have a DSC resource
+manifest:
+
+- `Microsoft.DSC/PowerShell`
+- `Microsoft.Windows/WindowsPowerShell`
+- `Microsoft.Windows/WMI`
+
+## Builtin configurable resources
+
+The following builtin resources to change the state of a machine directly:
+
+- `Microsoft.DSC.Transitional/RunCommandOnSet`
+- [Microsoft.Windows/Registry][09] - Manage Windows Registry keys and values.
+
+## Builtin debugging resources
+
+You can use the following builtin resources when debugging or exploring DSC. They don't affect
+the state of the machine.
+
+- `Microsoft.DSC.Debug/Echo`
+
+## Builtin group resources
+
+You can use the following builtin resources to change how DSC processes a group of nested resource
+instances:
+
+- `Microsoft.DSC/Assertion`
+- `Microsoft.DSC/Group`
+- `Microsoft.DSC/Include`
+
+
+[01]: ./Microsoft/OSInfo/index.md
+[09]: ./Microsoft/Windows/Registry/index.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md
index 5ed2199..758257f 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md
@@ -83,7 +83,7 @@ For every version of the schema, there are three valid urls:
retrieve this schema.
This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still
- validate the document when it uses this schema, other tools may error or behave in unexpected
+ validate the document when it uses this schema, other tools might error or behave in unexpected
ways.
- `.../bundled/config/document.vscode.json`
@@ -93,7 +93,7 @@ For every version of the schema, there are three valid urls:
don't include.
This schema uses keywords that are only recognized by VS Code. While DSC can still validate the
- document when it uses this schema, other tools may error or behave in unexpected ways.
+ document when it uses this schema, other tools might error or behave in unexpected ways.
```yaml
Type: string
@@ -130,7 +130,7 @@ defined as key-value pair. The key for each pair defines the name of the paramet
each pair must be an object that defines the `type` keyword to indicate how DSC should process the
parameter.
-Parameters may be overridden at run-time, enabling re-use of the same configuration document for
+You can override parameters at run-time, enabling re-use of the same configuration document for
different contexts.
For more information about defining parameters in a configuration, see
@@ -165,8 +165,9 @@ Required: false
### resources
-The `resources` property defines a list of DSC Resource instances that the configuration manages.
-Every instance in the list must be unique, but instances may share the same DSC Resource type.
+The `resources` property defines a list of DSC resource instances that the configuration document
+manages. Every instance in the list must be unique, but instances might share the same DSC resource
+type.
For more information about defining a valid resource instance in a configuration, see
[DSC Configuration document resource schema][05].
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md
index 6f91bc3..20fbbf2 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md
@@ -82,4 +82,4 @@ The `envvar()` function returns the value of the environment variable specified
Type: string
```
-[01]: ../../../cli/config/command.md#environment-variables
+[01]: ../../../cli/config/index.md#environment-variables
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md
index cc886da..a0814d0 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md
@@ -48,12 +48,12 @@ resources:
```
First, get the current state of the configuration without overriding the parameters with the
-[--parameters][02] or [`--parameters_file`][03] options. The output shows the default value for the
+[--parameters][02] or [`--parameters-file`][03] options. The output shows the default value for the
`message` parameter.
```bash
config_file=parameters.example.1.dsc.config.yaml
-cat $config_file | dsc config get
+cat $config_file | dsc config get --file -
```
```yaml
@@ -71,7 +71,7 @@ Next, override the `message` parameter with the `--parameters` option.
```bash
params='{"parameters": {"message": "Hi, override."}}'
-cat $config_file | dsc config --parameters $params get
+cat $config_file | dsc config --parameters $params get --file -
```
```yaml
@@ -110,5 +110,5 @@ Type: [string, int, bool, object, array]
[01]: ../parameter.md
-[02]: ../../../cli/config/command.md#-p---parameters
-[03]: ../../../cli/config/command.md#-f---parameters_file
+[02]: ../../../cli/config/index.md#--parameters
+[03]: ../../../cli/config/index.md#--parameters-file
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md
index d6d19a8..09f31de 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md
@@ -87,8 +87,8 @@ hadErrors: false
The `reference()` function expects the resource ID of the instance to resolve as a reference. Use
the [resourceId][01] function to build the resource ID for the instance instead of constructing the
resource ID manually. The function verifies that the resource instance exists, while specifying
-only the string manually may lead to a harder to diagnose error if the referenced instance name is
-incorrect.
+only the string manually might lead to a harder to diagnose error if the referenced instance name
+is incorrect.
```yaml
Type: string
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md
index 0e25e2a..d927568 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md
@@ -29,7 +29,7 @@ Parameters are defined as key-value pairs in the `parameters` property of a conf
The key is the parameter's name, which is used to reference the parameter in the [resources][01]
property of the configuration document. The value is an object that defines the parameter.
-Every parameter defines its data type. Parameters may also define a default value, validation
+Every parameter defines its data type. Parameters can also define a default value, validation
checks, a description of their purpose, and arbitrary metadata.
To reference parameters in resource instances, use the [parameters() configuration function][02].
@@ -42,7 +42,7 @@ To reference parameters in resource instances, use the [parameters() configurati
### description
-Parameters may define a short explanation of their purpose and usage with the `description`
+Parameters can define a short explanation of their purpose and usage with the `description`
property. To define a longer explanation in YAML, use the folded block syntax or literal block
syntax.
@@ -68,8 +68,8 @@ data type for every passed parameter before executing a configuration operation.
The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the
values. If a secure data type parameter is used for a resource instance property that doesn't
-expect a secure value, the resource may still log or record the value. If the resource has
-independent logging or recording that isn't handled by DSC, the value may be stored insecurely.
+expect a secure value, the resource might still log or record the value. If the resource has
+independent logging or recording that isn't handled by DSC, the value might be stored insecurely.
Use secure strings for passwords and secrets.
@@ -84,7 +84,7 @@ ValidValues: [string, securestring, int, bool, object, secureobject, array]
### defaultValue
-Parameters may define a default value with the `defaultValue` property. If the parameter isn't
+Parameters can define a default value with the `defaultValue` property. If the parameter isn't
passed at runtime, DSC uses the default value for the parameter. If the parameter isn't passed at
runtime and no default value is defined, DSC raises an error. The value must be valid for the
parameter's `type`.
@@ -96,7 +96,7 @@ ValidJSONTypes: [string, integer, object, array, boolean]
### allowedValues
-Parameters may limit the set of valid values for the parameter by defining the `allowedValues`
+Parameters can limit the set of valid values for the parameter by defining the `allowedValues`
property. DSC validates parameters passed at runtime and defined as `defaultValue` against this
list of values. If any of the values is invalid, DSC raises an error.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md
index bf4a17a..7f0f534 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md
@@ -69,7 +69,7 @@ Pattern: ^\w+(\.\w+){0,2}\/\w+$
### properties
The `properties` of a resource instance define its desired state. The value of this property must
-be an object. For assertion resources, the value may be an empty object (`{}`). DSC uses the
+be an object. For assertion resources, the value can be an empty object (`{}`). DSC uses the
DSC Resource's instance schema to validate the defined properties.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md
index fc24aea..5468be6 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md
@@ -117,7 +117,7 @@ parameters:
## Integers
-Integer values are numbers without a fractional part. Integer values may be limited by integrating
+Integer values are numbers without a fractional part. Integer values can be limited by integrating
tools or the DSC Resources they're used with. DSC itself supports integer values between
`-9223372036854775808` and `9223372036854775807`.
@@ -235,8 +235,8 @@ parameters:
Secure strings use the same format as strings and secure objects use the same format as objects.
The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the
values. If a secure data type parameter is used for a resource instance property that doesn't
-expect a secure value, the resource may still log or record the value. If the resource has
-independent logging or recording that isn't handled by DSC, the value may be stored insecurely.
+expect a secure value, the resource might still log or record the value. If the resource has
+independent logging or recording that isn't handled by DSC, the value might be stored insecurely.
Use secure strings for passwords and secrets. Never define a default value for secure string or
secure object parameters.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md
index a60b068..b4622e2 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md
@@ -40,7 +40,7 @@ When defining a group resource, always explicitly define the `kind` property in
### Adapter resources
An adapter resource makes non-command-based resources available to DSC. They always have a
-`resources` property that takes an array of nested resource instances. Adapters may provide
+`resources` property that takes an array of nested resource instances. Adapters can provide
additional control over how the adapted resources are processed.
An adapter resource must always define the [adapter][01] and [validate][02] properties in the
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md
index 2191ba2..c5f4bcd 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md
@@ -251,7 +251,7 @@ Required: true
[11]: ../../resource/properties/exist.md
[12]: ../../resource/manifest/set.md#handlesexist
[13]: ../../resource/manifest/delete.md
-[14]: ../../../cli/config/set.md#-w---what-if
+[14]: ../../../cli/config/set.md#--what-if
[15]: ../../resource/manifest/whatif.md
[16]: ../../resource/manifest/test.md
[17]: ../../../cli/resource/delete.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md
new file mode 100644
index 0000000..076f667
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md
index 56f803e..743dfde 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md
@@ -61,7 +61,7 @@ For every version of the schema, there are three valid urls:
retrieve this schema.
This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still
- validate the document when it uses this schema, other tools may error or behave in unexpected
+ validate the document when it uses this schema, other tools might error or behave in unexpected
ways.
- `.../bundled/resource/manifest.vscode.json`
@@ -71,7 +71,7 @@ For every version of the schema, there are three valid urls:
don't include.
This schema uses keywords that are only recognized by VS Code. While DSC can still validate the
- document when it uses this schema, other tools may error or behave in unexpected ways.
+ document when it uses this schema, other tools might error or behave in unexpected ways.
```yaml
Type: string
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md
index 1150d82..e5c30a3 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md
@@ -88,7 +88,7 @@ property's name. The value is a subschema that validates the property.
Resources can define any properties they need for managing instances. DSC defines shared schemas
for well-known properties. Some well-known properties enable a DSC Resource to use built-in
processing. The well-known properties always start with an underscore (`_`) and DSC Resources that
-use these properties may not override or extend them. If a resource specifies a well-known property
+use these properties can't override or extend them. If a resource specifies a well-known property
in the embedded schema, the schema _must_ define the property as a reference.
- [_exist](#_exist)
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md
index ed5054e..3d9b4a8 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md
@@ -274,7 +274,7 @@ ValidValues: [state, stateAndDiff]
[01]: ../../../cli/config/set.md
-[02]: ../../../cli/config/set.md#-w---what-if
+[02]: ../../../cli/config/set.md#--what-if
[03]: ./set.md
[04]: ../properties/exist.md
[05]: ./root.md#schema-1
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md
index 3e56791..bad7816 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md
@@ -37,7 +37,7 @@ behavior contract:
1. When the get operation queries for an instance that doesn't exist, the returned JSON always
defines the `_exist` property as `false`.
- The resource _may_ omit the `_exist` property from the result JSON when the instance exists.
+ The resource _can_ omit the `_exist` property from the result JSON when the instance exists.
To add this property to a resource's instance schema, define the property with the following
snippet:
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md
index 4741537..3d2ad1b 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md
@@ -11,7 +11,7 @@ title: DSC well-known properties
DSC has support for several well-known properties. Some well-known properties enable a DSC Resource
to use built-in processing. The well-known properties always start with an underscore (`_`) and DSC
-Resources that use these properties may not override or extend them.
+Resources that use these properties can't override or extend them.
## _exist
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md
index 313144d..49c0fe2 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md
@@ -33,7 +33,7 @@ behavior based on the property's value in an instance's desired state:
- When `_purge` is `false` or not specified, the resource ignores unmanaged entries.
When a resource defines this property, it should always document which property or properties
-`_purge` affects. A resource may define `_purge` as a subproperty for a complex property.
+`_purge` affects. A resource can define `_purge` as a subproperty for a complex property.
This property is write-only. A resource that uses the `_purge` property should never return
`_purge` in the instance's output state. A resource must not define `_purge` as a mandatory
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md
new file mode 100644
index 0000000..f0fae11
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md
@@ -0,0 +1,652 @@
+---
+description: Reference for how DSC schemas are versioned and published and the URIs used to retrieve them.
+ms.date: 03/25/2025
+ms.topic: reference
+title: DSC JSON Schema URIs
+---
+
+# DSC JSON Schema URIs
+
+This document describes how the JSON Schemas are versioned and published for the Microsoft Desired
+State Configuration (DSC) platform.
+
+DSC uses JSON schemas extensively to describe and validate the data that it takes as input and
+returns as output. To ensure compatibility and simplify the user experience, DSC schemas are
+published in multiple versions and forms.
+
+The URIs for DSC schemas use the following syntax:
+
+```syntax
+///.
+```
+
+## Schema URI prefixes
+
+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 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][01] and aligns the version of the CLI, the platform, and the JSON
+schemas. A nonprerelease semantic version includes three segments:
+
+```syntax
+..
+```
+
+- When the next release of DSC contains only fixes, not improvements or breaking changes, the
+ `patch` segment increments by one.
+- When the next release of DSC contains any improvements and doesn't include any breaking changes,
+ the `minor` segment increments by one.
+- When the next release of DSC contains any breaking changes, the `major` segment of the version
+ increments by one.
+
+### Version folders
+
+For every release of DSC, the schemas are published to three versioned folders:
+
+- `v..` - The full semantic version folder. This folder is unique to each
+ release.
+- `v.` - The minor version folder for the current major version. The schemas in this
+ folder are always for the latest patch release of that minor version.
+- `v` - The major version folder. The schemas in this folder are always for the latest
+ release of that major version.
+
+To illustrate the versioning, the following table shows which folders the schemas for each release
+publish to. Entries in the table with an asterisk suffix (`*`) indicate that the entry is the
+latest schema for that version folder.
+
+| Release | Major version folder | Minor version folder | Full version folder |
+|:-------:|:--------------------:|:--------------------:|:-------------------:|
+| `3.0.0` | `v3` | `v3.0` | `v3.0.0*` |
+| `3.0.1` | `v3` | `v3.0*` | `v3.0.1*` |
+| `3.1.0` | `v3` | `v3.1` | `v3.1.0*` |
+| `3.1.1` | `v3*` | `v3.1*` | `v3.1.1*` |
+
+### Pinning to a version folder
+
+Publishing the schemas under multiple version folders enables you to choose which version you want
+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 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. 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
+nonbreaking release. You can use those schemas until you want or need to migrate to a new major
+version of DSC.
+
+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
+
+The schemas for DSC are always published in their canonical form, where the schema lives at its own
+URI. Schemas for top-level items, like configuration documents, resource manifests, and the output
+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][02] unless otherwise
+noted, regardless of their form.
+
+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. 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 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 (nonbundled) | _None_ | `.json` |
+| Canonically bundled | `bundled` | `.json` |
+| Enhanced autoring | `bundled` | `.vscode.json` |
+
+### 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][03], those references are site-relative. This format
+enables you to select only the schemas for the data types you want to use.
+
+> [!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][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][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
+canonical URI to a referenced schema. The value for each key is the schema object hosted at that
+URI. Each of the schemas bundled in the `$defs` keyword always defines both the `$id` keyword and
+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 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 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.
+
+## Bundled schema URIs list
+
+This section enumerates every schema published in the canonically bundled form for DSC and the URIs
+recognized for each schema.
+
+
+
+### 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.
+
+| Version folder | ID |
+|:---------------|:--------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` |
+
+The following list of tables defines the recognized URIs for the configuration document schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/config/document.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-----------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.vscode.json` |
+
+### Resource manifest schema
+
+The following table defines the value of the `$id` keyword for each published version of the
+resource manifest 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` |
+
+The following list of tables defines the recognized URIs for the resource manifest schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.vscode.json` |
+
+### Output schema for dsc config get command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc config get` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/get.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/get.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/get.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/get.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/get.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/get.vscode.json` |
+
+### Output schema for dsc config set command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc config set` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/set.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/set.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/set.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/set.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/set.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/set.vscode.json` |
+
+### Output schema for dsc config test command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc config test` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/test.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/test.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/test.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/test.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/test.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/test.vscode.json` |
+
+### Output schema for dsc resource get command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc resource get` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/get.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/get.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/get.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/get.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/get.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/get.vscode.json` |
+
+### Output schema for dsc resource list command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc resource list` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/list.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/list.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/list.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/list.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/list.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/list.vscode.json` |
+
+### Output schema for dsc resource schema command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc resource schema` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/schema.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/schema.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/schema.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/schema.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/schema.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/schema.vscode.json` |
+
+### Output schema for dsc resource set command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc resource set` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/set.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/set.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/set.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/set.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/set.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/set.vscode.json` |
+
+### Output schema for dsc resource test command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc resource test` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/test.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/test.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/test.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/test.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/test.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/test.vscode.json` |
+
+### Output schema for dsc schema command
+
+The following table defines the value of the `$id` keyword for each published version of the output
+schema for the `dsc schema` command. 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 |
+|:---------------|:----------------------------------------------------------------------------------------------|
+| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` |
+| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` |
+| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` |
+
+The following list of tables defines the recognized URIs for the output schema:
+
+- Short URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:--------------------------------------------------------------------------|
+ | 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` |
+ | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/schema.vscode.json` |
+ | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/schema.vscode.json` |
+ | Enhanced authoring | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/schema.vscode.json` |
+
+- GitHub URIs by version and form:
+
+ | Form | Version | Recognized URI |
+ |:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------|
+ | 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/dsc/docs-conceptual/dsc-3.0/reference/tools/builtin.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/builtin.md
new file mode 100644
index 0000000..7f9f5b4
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/cli/osinfo.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/osinfo.md
similarity index 87%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/cli/osinfo.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/osinfo.md
index 0dec9ec..9d5cc53 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/osinfo/cli/osinfo.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/osinfo.md
@@ -1,11 +1,11 @@
---
description: Command line reference for the 'osinfo' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
-title: osinfo
+title: osinfo command reference
---
-# osinfo
+# osinfo command reference
## Synopsis
@@ -13,7 +13,7 @@ Returns information about the operating system.
> [!IMPORTANT]
> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with
-> DSCv3. Don't use it in production.
+> DSC. Don't use it in production.
## Syntax
@@ -24,10 +24,11 @@ osinfo
## Description
The `osinfo` command returns information about the operating system as a single line of compressed
-JSON without any whitespace.
+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, see [Microsoft/OSInfo][01].
+Resource. For more information about those properties and using the resource, see
+[Microsoft/OSInfo][01].
## Examples
@@ -94,7 +95,5 @@ The following code block shows the output with newlines and indentation for read
}
```
----
-
-[01]: ../resource.md
+[01]: ../resources/Microsoft/OSInfo/index.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/delete.md
new file mode 100644
index 0000000..b060717
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/get.md
new file mode 100644
index 0000000..510e00f
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/index.md
similarity index 85%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/index.md
index 9e1f91a..ef59f83 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/config/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry config' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry config
---
@@ -41,10 +41,10 @@ The `get` command returns the current state of a registry key or value. For more
The `set` command enforces the desired state for a registry key or value. For more information, see
[set][03].
-### test
+### delete
-The `test` command validates wether a registry key or value is in the desired state. For more
-information, see [test][04].
+The `delete` command validates wether a registry key or value is in the desired state. For more
+information, see [delete][04].
### help
@@ -66,6 +66,9 @@ information. For example, `registry config --help` or `registry config set --hel
### -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.
@@ -76,6 +79,9 @@ 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.
@@ -85,7 +91,7 @@ Mandatory: false
```
-[01]: ../../resource.md
-[02]: get.md
-[03]: set.md
-[04]: test.md
+[01]: ../../../resources/Microsoft/Windows/Registry/index.md
+[02]: ./get.md
+[03]: ./set.md
+[04]: ./delete.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/config/set.md
new file mode 100644
index 0000000..389190d
--- /dev/null
+++ b/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/find/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/find/index.md
similarity index 91%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/find/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/find/index.md
index bd191b9..e5952ed 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/find/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/find/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry find' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry find
---
@@ -29,6 +29,9 @@ The `find` command isn't implemented yet. It returns a string that echoes the sp
### -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 (`\`).
@@ -49,6 +52,9 @@ Mandatory: true
### -f, --find
+
+
+
The string to search for in the registry key and value names.
```yaml
@@ -58,6 +64,9 @@ Mandatory: true
### -r, --recurse
+
+
+
Indicates whether the command should recursively find subkeys and values. By default, the command
isn't recursive.
@@ -68,6 +77,8 @@ Mandatory: false
### --keys_only
+
+
Indicates whether the command should limit results to registry keys. By default, the command
returns matching registry keys and values.
@@ -78,6 +89,8 @@ Mandatory: false
### --values_only
+
+
Indicates whether the command should limit results to registry values. By default, the command
returns matching registry keys and values.
@@ -88,6 +101,9 @@ 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.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/registry.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/index.md
similarity index 65%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/registry.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/index.md
index d1632cd..c1d8196 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/registry.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry
---
@@ -21,36 +21,47 @@ Manage state of Windows registry
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][01].
+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][02].
-
-### test
-
-The `test` command isn't implemented yet. It returns the string `Test`. For more information, see
-[test][03].
+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][04].
+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][05].
+For more information, see [find][06].
### config
-The `config` command manages registry keys and values as instances of a [DSC Resource][06]. You can
+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
@@ -84,6 +95,9 @@ example, `registry config --help` or `registry config set --help`.
### -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.
@@ -94,6 +108,9 @@ 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.
@@ -102,12 +119,12 @@ Type: Boolean
Mandatory: false
```
-
-[01]: query/command.md
-[02]: set/command.md
-[03]: test/command.md
-[04]: remove/command.md
-[05]: find/command.md
-[06]: ../../../../../concepts/resources.md
-[07]: config/command.md
-[08]: schema/command.md
+
+[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/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/query/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/query/index.md
similarity index 92%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/query/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/query/index.md
index faf96d1..b1f931c 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/query/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/query/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry query' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry query
---
@@ -29,6 +29,8 @@ The `query` command isn't implemented yet. It returns a string that echoes the s
### Example 1 - Echo the options
+
+
The options are returned as a string on a single line.
```powershell
@@ -43,6 +45,9 @@ Get key_path: HKCU\SYSTEM, value_name: None, recurse: true
### -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 (`\`).
@@ -63,6 +68,9 @@ Mandatory: true
### -v, --value-name
+
+
+
Defines the name of the value to query for in the specified registry key path.
```yaml
@@ -72,6 +80,9 @@ Mandatory: false
### -r, --recurse
+
+
+
Indicates whether the command should recursively query subkeys. By default, the command isn't
recursive.
@@ -82,6 +93,9 @@ 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.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/remove/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/remove/index.md
similarity index 62%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/remove/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/remove/index.md
index 327fe9f..ad655a7 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/remove/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/remove/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry remove' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry remove
---
@@ -23,26 +23,47 @@ registry remove [Options] --key-path
## Description
-The `remove` command isn't implemented yet. It returns a string that echoes the specified options.
+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 - Echo the options
+### Example 1 - Remove a registry value
-The options are returned as a string on a single line.
+
+
+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 --recurse
+registry remove --key-path HKCU\Example\Key --recurse
```
```Output
-Remove key_path: HKCU\example, value_name: None, recurse: true
+{"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 (`\`).
@@ -63,6 +84,9 @@ Mandatory: true
### -v, --value-name
+
+
+
Defines the name of the value to remove for in the specified registry key path.
```yaml
@@ -72,6 +96,9 @@ Mandatory: false
### -r, --recurse
+
+
+
Indicates whether the command should recursively remove subkeys. By default, the command isn't
recursive.
@@ -82,6 +109,9 @@ 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.
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/schema/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/schema/index.md
similarity index 89%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/schema/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/schema/index.md
index 57af06e..6e8062e 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/schema/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/schema/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry schema' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry schema
---
@@ -36,6 +36,8 @@ For more information about defining an instance of the `Microsoft.Windows/Regist
### Example 1 - Get the compressed schema
+
+
The output is a single line containing the JSON schema without any unquoted whitespace.
```powershell
@@ -44,6 +46,8 @@ 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.
@@ -55,6 +59,9 @@ registry schema --pretty
### -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.
@@ -66,6 +73,9 @@ 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.
@@ -75,4 +85,4 @@ Mandatory: false
```
-[01]: ../../resource.md
+[01]: ../../../resources/Microsoft/Windows/Registry/index.md
diff --git a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/set/command.md b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/set/index.md
similarity index 93%
rename from dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/set/command.md
rename to dsc/docs-conceptual/dsc-3.0/reference/tools/registry/set/index.md
index 81dd31f..3b469bf 100644
--- a/dsc/docs-conceptual/dsc-3.0/reference/microsoft/windows/registry/cli/set/command.md
+++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/registry/set/index.md
@@ -1,6 +1,6 @@
---
description: Command line reference for the 'registry set' command
-ms.date: 08/22/2023
+ms.date: 03/25/2025
ms.topic: reference
title: registry set
---
@@ -29,6 +29,8 @@ The `set` command isn't implemented yet. It returns a string that echoes the spe
### Example 1 - Echo the options
+
+
The options are returned as a string on a single line.
```powershell
@@ -43,6 +45,9 @@ Set key_path: HKCU\example, value: hello
### -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 (`\`).
@@ -63,6 +68,9 @@ Mandatory: true
### -v, --value
+
+
+
Defines the name of the value to set for in the specified registry key path.
```yaml
@@ -72,6 +80,9 @@ 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.
diff --git a/dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md b/dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md
deleted file mode 100644
index dab4b64..0000000
--- a/dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-description: >-
- Describes the components of a command-based DSC Resource, how DSC uses them, and what's required
- of them.
-ms.date: 08/04/2023
-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.
-
-Command-based DSC Resources are defined with at least two files:
-
-1. A DSC Resource manifest that tells DSC how to interact with the resource.
-1. One or more executable files and their dependencies to manage instances of the resource.
-
-## DSC Resource manifests
-
-DSC Resource manifests are defined as JSON files. For DSC to recognize a JSON file as a manifest,
-the file must meet the following criteria:
-
-1. The file must be discoverable in the `PATH` environment variable.
-1. The filename must end with `.dsc.resource.json`.
-
-When DSC searches the local system for available command-based DSC Resources, it searches every
-folder in the `PATH` for files that use the DSC Resource manifest naming convention. DSC then
-parses each of those discovered files and validates them against the
-[DSC Resource Manifest JSON schema][01].
-
-If the JSON file validates against the schema, DSC can use the DSC Resource.
-
-At a minimum, the manifest must define:
-
-- The version of the DSC Resource Manifest JSON schema it's compatible with.
-- The fully qualified name of the resource, like `Microsoft.Windows/Registry`. The fully qualified
- name syntax is `[.][.]/`. The group and area components of the fully
- qualified name enable organizing resources into namespaces.
-- How DSC can call the command to get the current state of a resource instance.
-- A way to validate an instance. This can be one of the following:
- - A JSON schema that describes an instance
- - A command DSC must call to get the schema at runtime
- - A command to validate nested DSC Resources. This last option only applies to DSC Group
- Resources and DSC Provider Resources.
-
-The manifest may optionally define:
-
-- How DSC can call the command to test whether an instance is in the desired
- state.
-- How DSC can call the command to set an instance to the desired state.
-- The meaning of the non-zero exit codes returned by the command.
-- How DSC can call the command to manage other DSC Resources, when the resource is a DSC Group
- Resource or a DSC Provider Resource.
-- Metadata about the resource, like its author and a short description.
-
-If the manifest doesn't define how to test an instance of the resource, DSC performs a synthetic
-test for resource instances. DSC's synthetic test always gets the actual state of an instance and
-does a strict case-sensitive comparison of the instance's properties to the desired state. The
-synthetic test ignores any properties prefixed with an underscore (`_`) or dollar sign (`$`). If
-any of the properties aren't exactly the same as the defined desired state, DSC reports the
-instance as being non-compliant.
-
-If the manifest doesn't define how to set an instance of the DSC Resource, DSC can't use the
-resource to enforce desired state.
-
-The manifest doesn't need to specify the same executable file for every operation. The definition
-for each operation is independent.
-
-
-
-## DSC Resource executables
-
-Command-based DSC Resources always require an executable file for DSC to run. The DSC Resource
-Manifest doesn't need to be bundled with the executable. The executable can be any executable file,
-such as a binary application or a shell script. A resource may use different executables for
-different operations.
-
-For DSC to use an executable, it must be discoverable in the `PATH` environment variable. DSC calls
-the executable once per operation, using the exit code returned by the executable to determine if
-the command was successful. DSC treats exit code `0` as a success and all other exit codes as an
-error.
-
-
-
-### Inputs
-
-DSC sends input to command-based DSC Resources as either a JSON data blob over stdin or as a set of
-argument flags and values. Input handling is defined per-operation in the DSC Resource Manifest.
-
-When DSC sends the input as JSON over stdin, the data blob is the JSON representation of an
-instance's desired state. This is the most robust option for a resource, as it enables the resource
-to support complex properties with nested objects.
-
-When DSC sends the input as arguments, it generates a pair of arguments for each of the specified
-properties. The first argument is the name of the property prefixed with `--`, such as
-`--duration`. The second argument is the property's value. The ordering of the argument pairs isn't
-guaranteed. This input method doesn't support complex properties.
-
-### Outputs
-
-The executable for a command-based DSC Resource must return JSON data to stdout when called by DSC.
-The output encoding must be UTF-8. When the resource returns the state of an instance, DSC
-validates the JSON data against the resource's instance schema.
-
-For DSC Provider Resources, DSC expects the executable to pass through the instance states for the
-resources it manages as either a single JSON array or as a series of [JSON Lines][04].
-
-Command-based DSC Resources can report logging information to DSC by emitting JSON Lines to stderr.
-Each log entry must be a JSON object that includes two keys:
-
-1. The `message` key defines the human-readable string for the log entry.
-1. The `level` key defines whether the message represents an `Error`, a `Warning`, or `Information`.
-
-DSC collects messages from resources and displays them in the results for a configuration
-operation. When DSC invokes a resource directly outside of a configuration, it doesn't collect the
-messages. Instead, they're just emitted to stderr.
-
-
-
-## Related Content
-
-
-- [Write your first DSC Resource overview][06]
-- [DSC Resource Manifest schema reference][01]
-
-[01]: ../../reference/schemas/resource/manifest/root.md
-
-
-[04]: https://jsonlines.org/
-
-[06]: ../tutorials/first-resource/overview.md
diff --git a/dsc/docs-conceptual/dsc-3.0/resources/samples/overview.md b/dsc/docs-conceptual/dsc-3.0/resources/samples/overview.md
deleted file mode 100644
index 8b1fd9f..0000000
--- a/dsc/docs-conceptual/dsc-3.0/resources/samples/overview.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: >-
- Explains how the DSC samples are organized, where they're hosted, and what they cover.
-ms.date: 08/04/2023
-title: DSC Resource samples overview
----
-
-# DSC samples overview
-
-The samples are hosted in the [DSC Samples repository][03]. Some samples are related to a tutorial
-hosted in the [DSC Samples repository site][02].
-
-We welcome contributions to the samples repository. For more information, see
-[Contributing to the DSC Samples][04].
-
-## See also
-
-- [Write your first DSC Resource overview][05]
-
-[02]: https://powershell.github.io/DSC-Samples
-[03]: https://github.com/PowerShell/DSC-Samples
-[04]: https://powershell.github.io/DSC-Samples/contributing
-[05]: first-resource/overview.md
diff --git a/dsc/docs-conceptual/dsc-3.0/resources/tutorials/first-resource/overview.md b/dsc/docs-conceptual/dsc-3.0/resources/tutorials/first-resource/overview.md
deleted file mode 100644
index 59fe464..0000000
--- a/dsc/docs-conceptual/dsc-3.0/resources/tutorials/first-resource/overview.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-description: >-
- Explains the How to write your first DSC Resource samples at a high level.
-ms.date: 08/04/2023
-title: Write your first DSC Resource samples overview
----
-
-# Write your first DSC Resource samples overview
-
-Each of the samples in this section are the completed DSC Resource from one of the implementations
-of the [Write your first DSC Resource][01] tutorial.
-
-The resources manage the fictional [TSToy application][02]'s configuration files. While the
-TSToy application isn't a real production application, managing configuration files is a common
-use-case for resources.
-
-The sample resources support:
-
-- Passing input to the resource command with command line arguments or JSON over stdin.
-- Getting the current state of the TSToy application's configuration files without DSC.
-- Enforcing the state of the configuration files without DSC.
-- Invoking the **Get**, **Test**, and **Set** operations with DSC.
-- Declaring instances of the resource in a DSC Configuration document.
-
-The sample code is hosted in the [DSC Samples repository][03]. For more information about the
-specification for the sample code's implementation, see
-[Write your first DSC Resource Specification][04].
-
-We welcome contributions to the samples repository. For more information, see
-[Contributing to the DSC Samples][05].
-
-[01]: ../../tutorials/first-resource/overview.md
-[02]: https://powershell.github.io/DSC-Samples/tstoy/about
-[03]: https://github.com/PowerShell/DSC-Samples
-[04]: https://powershell.github.io/DSC-Samples/contributing/tutorials/resource-specs/first-resource/
-[05]: https://powershell.github.io/DSC-Samples/contributing
diff --git a/dsc/docs-conceptual/dsc-3.0/toc.yml b/dsc/docs-conceptual/dsc-3.0/toc.yml
index a3d9680..c48d8f1 100644
--- a/dsc/docs-conceptual/dsc-3.0/toc.yml
+++ b/dsc/docs-conceptual/dsc-3.0/toc.yml
@@ -1,265 +1,269 @@
items:
- name: Microsoft DSC 3.0
href: overview.md
- - name: Glossary
- href: glossary.md
- name: Changelog
href: changelog.md
- name: Getting started
items:
- - name: Get started managing state with DSCv3
- href: getting-started/getting-started.md
+ - name: Managing state with DSC
+ href: get-started/index.md
- name: Concepts
items:
- - name: Configuration Documents
- href: concepts/configurations.md
- - name: Resources
- href: concepts/resources.md
+ - name: DSC configuration documents
+ items:
+ - name: Overview
+ href: concepts/configuration-documents/overview.md
+ - name: DSC resources
+ items:
+ - name: Overview
+ href: concepts/resources/overview.md
+ - name: Resource instances
+ href: concepts/resources/instances.md
+ - name: Resource operations
+ href: concepts/resources/operations.md
+ - name: Resource properties
+ href: concepts/resources/properties.md
+ - name: Resource capabilities
+ href: concepts/resources/capabilities.md
+ - name: Resource kinds
+ href: concepts/resources/kinds.md
+ - name: Anatomy of a command resource
+ href: concepts/resources/anatomy.md
- name: Enhanced authoring
href: concepts/enhanced-authoring.md
- name: Output accessibility
href: concepts/output-accessibility.md
- - name: Resources
+ - name: Tutorials
items:
- - name: Concepts
+ - name: Resource authoring
items:
- - name: Anatomy of a command-based DSC Resource
- href: resources/concepts/anatomy.md
- - name: Tutorials
+ - name: Overview
+ href: tutorials/resources/authoring/overview.md
+ - name: Write your first DSC resource
+ items:
+ - name: Overview
+ href: tutorials/resources/authoring/first-resource/overview.md
+ - name: In Go
+ href: https://powershell.github.io/DSC-Samples/tutorials/first-resource/go/
+ - name: DSC reference
+ items:
+ - name: dsc CLI
items:
- - name: Overview
- href: resources/tutorials/overview.md
- - name: Write your first DSC Resource
+ - name: dsc
+ href: reference/cli/index.md
+ - name: dsc completer
+ href: reference/cli/completer/index.md
+ - name: dsc config subcommands
items:
- - name: Overview
- href: resources/tutorials/first-resource/overview.md
- - name: In Go
- href: https://powershell.github.io/DSC-Samples/tutorials/first-resource/go/
- - name: Samples
- items:
- - name: Overview
- href: resources/samples/overview.md
- - name: First DSC Resource
+ - name: dsc config
+ href: reference/cli/config/index.md
+ - name: dsc config export
+ href: reference/cli/config/export.md
+ - name: dsc config get
+ href: reference/cli/config/get.md
+ - name: dsc config set
+ href: reference/cli/config/set.md
+ - name: dsc config test
+ href: reference/cli/config/test.md
+ - name: dsc resource subcommands
items:
- - name: Overview
- href: resources/samples/first-resource/overview.md
- - name: Go
- href: https://github.com/PowerShell/DSC-Samples/tree/main/samples/go/resources/first
- - name: dsc command line reference
- items:
- - name: dsc command
- href: reference/cli/dsc.md
- - name: dsc completer command
- href: reference/cli/completer/command.md
- - name: dsc config command
+ - name: dsc resource
+ href: reference/cli/resource/index.md
+ - name: dsc resource delete
+ href: reference/cli/resource/delete.md
+ - name: dsc resource export
+ href: reference/cli/resource/export.md
+ - name: dsc resource get
+ href: reference/cli/resource/get.md
+ - name: dsc resource list
+ href: reference/cli/resource/list.md
+ - name: dsc resource schema
+ href: reference/cli/resource/schema.md
+ - name: dsc resource set
+ href: reference/cli/resource/set.md
+ - name: dsc resource test
+ href: reference/cli/resource/test.md
+ - name: dsc schema
+ href: reference/cli/schema/index.md
+ - name: DSC JSON Schemas
items:
- - name: dsc config
- href: reference/cli/config/command.md
- - name: dsc config export
- href: reference/cli/config/export.md
- - name: dsc config get
- href: reference/cli/config/get.md
- - name: dsc config set
- href: reference/cli/config/set.md
- - name: dsc config test
- href: reference/cli/config/test.md
- - name: dsc resource command
- items:
- - name: dsc resource
- href: reference/cli/resource/command.md
- - name: dsc resource delete
- href: reference/cli/resource/delete.md
- - name: dsc resource export
- href: reference/cli/resource/export.md
- - name: dsc resource get
- href: reference/cli/resource/get.md
- - name: dsc resource list
- href: reference/cli/resource/list.md
- - name: dsc resource schema
- href: reference/cli/resource/schema.md
- - name: dsc resource set
- href: reference/cli/resource/set.md
- - name: dsc resource test
- href: reference/cli/resource/test.md
- - name: dsc schema command
- href: reference/cli/schema/command.md
- - name: Schema reference
- items:
- - name: Configuration
- items:
- - name: Documents
- href: reference/schemas/config/document.md
- - name: Document metadata
- href: reference/schemas/config/metadata.md
- - name: Document parameters
- href: reference/schemas/config/parameter.md
- - name: Resource instances
- href: reference/schemas/config/resource.md
- - name: Functions
+ - name: dsc command outputs
items:
- - name: Overview
- href: reference/schemas/config/functions/overview.md
- - name: add
- href: reference/schemas/config/functions/add.md
- - name: base64
- href: reference/schemas/config/functions/base64.md
- - name: concat
- href: reference/schemas/config/functions/concat.md
- - name: createArray
- href: reference/schemas/config/functions/createArray.md
- - name: div
- href: reference/schemas/config/functions/div.md
- - name: envvar
- href: reference/schemas/config/functions/envvar.md
- - name: int
- href: reference/schemas/config/functions/int.md
- - name: max
- href: reference/schemas/config/functions/max.md
- - name: min
- href: reference/schemas/config/functions/min.md
- - name: mod
- href: reference/schemas/config/functions/mod.md
- - name: mul
- href: reference/schemas/config/functions/mul.md
- - name: parameters
- href: reference/schemas/config/functions/parameters.md
- - name: reference
- href: reference/schemas/config/functions/reference.md
- - name: resourceId
- href: reference/schemas/config/functions/resourceId.md
- - name: sub
- href: reference/schemas/config/functions/sub.md
- - name: Resource
- items:
- - name: Manifests
+ - name: dsc config command outputs
+ items:
+ - name: dsc config get output
+ href: reference/schemas/outputs/config/get.md
+ - name: dsc config set output
+ href: reference/schemas/outputs/config/set.md
+ - name: dsc config test output
+ href: reference/schemas/outputs/config/test.md
+ - name: dsc resource command outputs
+ items:
+ - name: dsc resource get output
+ href: reference/schemas/outputs/resource/get.md
+ - name: dsc resource list output
+ href: reference/schemas/outputs/resource/list.md
+ - name: dsc resource set output
+ href: reference/schemas/outputs/resource/set.md
+ - name: dsc resource test output
+ href: reference/schemas/outputs/resource/test.md
+ - name: Configuration
items:
- - name: Root
- href: reference/schemas/resource/manifest/root.md
- - name: Adapter property
- href: reference/schemas/resource/manifest/adapter.md
- - name: Delete property
- href: reference/schemas/resource/manifest/delete.md
- - name: Export property
- href: reference/schemas/resource/manifest/export.md
- - name: Get property
- href: reference/schemas/resource/manifest/get.md
- - name: Set property
- href: reference/schemas/resource/manifest/set.md
- - name: Test property
- href: reference/schemas/resource/manifest/test.md
- - name: Validate property
- href: reference/schemas/resource/manifest/validate.md
- - name: Schema
+ - name: Documents
+ href: reference/schemas/config/document.md
+ - name: Document metadata
+ href: reference/schemas/config/metadata.md
+ - name: Document parameters
+ href: reference/schemas/config/parameter.md
+ - name: Resource instances
+ href: reference/schemas/config/resource.md
+ - name: Functions
items:
- - name: Property
- href: reference/schemas/resource/manifest/schema/property.md
- - name: Embedded schemas
- href: reference/schemas/resource/manifest/schema/embedded.md
- - name: Well-known properties
+ - name: Overview
+ href: reference/schemas/config/functions/overview.md
+ - name: add
+ href: reference/schemas/config/functions/add.md
+ - name: base64
+ href: reference/schemas/config/functions/base64.md
+ - name: concat
+ href: reference/schemas/config/functions/concat.md
+ - name: createArray
+ href: reference/schemas/config/functions/createArray.md
+ - name: div
+ href: reference/schemas/config/functions/div.md
+ - name: envvar
+ href: reference/schemas/config/functions/envvar.md
+ - name: int
+ href: reference/schemas/config/functions/int.md
+ - name: max
+ href: reference/schemas/config/functions/max.md
+ - name: min
+ href: reference/schemas/config/functions/min.md
+ - name: mod
+ href: reference/schemas/config/functions/mod.md
+ - name: mul
+ href: reference/schemas/config/functions/mul.md
+ - name: parameters
+ href: reference/schemas/config/functions/parameters.md
+ - name: reference
+ href: reference/schemas/config/functions/reference.md
+ - name: resourceId
+ href: reference/schemas/config/functions/resourceId.md
+ - name: sub
+ href: reference/schemas/config/functions/sub.md
+ - name: Resource
items:
- - name: Overview
- href: reference/schemas/resource/properties/overview.md
- - name: _ensure
- href: reference/schemas/resource/properties/ensure.md
- - name: _exist
- href: reference/schemas/resource/properties/exist.md
- - name: _inDesiredState
- href: reference/schemas/resource/properties/inDesiredState.md
- - name: _purge
- href: reference/schemas/resource/properties/purge.md
- - name: _rebootRequested
- href: reference/schemas/resource/properties/rebootRequested.md
- - name: Metadata
- items:
- - name: Microsoft.DSC properties
- href: reference/schemas/metadata/Microsoft.DSC/properties.md
- - name: Outputs
- items:
- - name: dsc config command outputs
+ - name: Manifests
+ items:
+ - name: Root
+ href: reference/schemas/resource/manifest/root.md
+ - name: Adapter property
+ href: reference/schemas/resource/manifest/adapter.md
+ - name: Delete property
+ href: reference/schemas/resource/manifest/delete.md
+ - name: Export property
+ href: reference/schemas/resource/manifest/export.md
+ - name: Get property
+ href: reference/schemas/resource/manifest/get.md
+ - name: Set property
+ href: reference/schemas/resource/manifest/set.md
+ - name: Test property
+ href: reference/schemas/resource/manifest/test.md
+ - name: Validate property
+ href: reference/schemas/resource/manifest/validate.md
+ - name: Schema
+ items:
+ - name: Property
+ href: reference/schemas/resource/manifest/schema/property.md
+ - name: Embedded schemas
+ href: reference/schemas/resource/manifest/schema/embedded.md
+ - name: Canonical resource properties
+ items:
+ - name: Overview
+ href: reference/schemas/resource/properties/overview.md
+ - name: _ensure
+ href: reference/schemas/resource/properties/ensure.md
+ - name: _exist
+ href: reference/schemas/resource/properties/exist.md
+ - name: _inDesiredState
+ href: reference/schemas/resource/properties/inDesiredState.md
+ - name: _purge
+ href: reference/schemas/resource/properties/purge.md
+ - name: _rebootRequested
+ href: reference/schemas/resource/properties/rebootRequested.md
+ - name: Metadata
items:
- - name: dsc config get output
- href: reference/schemas/outputs/config/get.md
- - name: dsc config set output
- href: reference/schemas/outputs/config/set.md
- - name: dsc config test output
- href: reference/schemas/outputs/config/test.md
- - name: dsc resource command outputs
+ - name: Microsoft.DSC properties
+ href: reference/schemas/metadata/Microsoft.DSC/properties.md
+ - name: Shared definitions
items:
- - name: dsc resource get output
- href: reference/schemas/outputs/resource/get.md
- - name: dsc resource list output
- href: reference/schemas/outputs/resource/list.md
- - name: dsc resource set output
- href: reference/schemas/outputs/resource/set.md
- - name: dsc resource test output
- href: reference/schemas/outputs/resource/test.md
- - name: Shared definitions
- items:
- - name: message
- href: reference/schemas/definitions/message.md
- - name: resourceKind
- href: reference/schemas/definitions/resourceKind.md
- - name: resourceType
- href: reference/schemas/definitions/resourceType.md
- - name: Parameter dataTypes
- href: reference/schemas/definitions/parameters/dataTypes.md
- - name: Resource reference
- items:
- - name: Command-based resources
+ - name: message
+ href: reference/schemas/definitions/message.md
+ - name: resourceKind
+ href: reference/schemas/definitions/resourceKind.md
+ - name: resourceType
+ href: reference/schemas/definitions/resourceType.md
+ - name: Parameter dataTypes
+ href: reference/schemas/definitions/parameters/dataTypes.md
+ - name: DSC resources
items:
- - name: Microsoft/OSInfo
+ - name: Builtin resources
items:
- name: Overview
- href: reference/microsoft/osinfo/overview.md
- - name: DSC Resource
- href: reference/microsoft/osinfo/resource.md
- - name: DSC Examples
+ href: reference/resources/builtin.md
+ - name: Microsoft/OSInfo
items:
- - name: Validate with dsc resource
- href: reference/microsoft/osinfo/examples/validate-with-dsc-resource.md
- - name: Validate in a configuration
- href: reference/microsoft/osinfo/examples/validate-in-a-configuration.md
- - name: Command line reference
+ - name: DSC Resource
+ href: reference/resources/Microsoft/OSInfo/index.md
+ - name: Examples
+ items:
+ - name: Validate OS with dsc resource commands
+ href: reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md
+ - name: Validate OS in a configuration
+ href: reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md
+ - name: Microsoft.Windows/Registry
items:
- - name: osinfo command
- href: reference/microsoft/osinfo/cli/osinfo.md
- - name: Microsoft.Windows/Registry
+ - name: DSC Resource
+ href: reference/resources/Microsoft/Windows/Registry/index.md
+ - name: Examples
+ items:
+ - name: Manage a key
+ href: reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md
+ - name: Manage a value
+ href: reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md
+ - name: Configure keys and values
+ href: reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md
+ - name: DSC tools
+ items:
+ - name: Builtin commands
items:
- name: Overview
- href: reference/microsoft/windows/registry/overview.md
- - name: DSC Resource
- href: reference/microsoft/windows/registry/resource.md
- - name: DSC Examples
+ href: reference/tools/builtin.md
+ - name: osinfo
+ href: reference/tools/osinfo.md
+ - name: registry commandline
items:
- - name: Manage a registry key
- href: reference/microsoft/windows/registry/examples/manage-a-registry-key.md
- - name: Manage a registry value
- href: reference/microsoft/windows/registry/examples/manage-a-registry-value.md
- - name: Configure registry keys and values
- href: reference/microsoft/windows/registry/examples/configure-registry-keys-and-values.md
- - name: Command line reference
- items:
- - name: registry command
- href: reference/microsoft/windows/registry/cli/registry.md
- - name: registry config command
+ - name: registry
+ href: reference/tools/registry/index.md
+ - name: registry query
+ href: reference/tools/registry/query/index.md
+ - name: registry set
+ href: reference/tools/registry/set/index.md
+ - name: registry remove
+ href: reference/tools/registry/remove/index.md
+ - name: registry find
+ href: reference/tools/registry/find/index.md
+ - name: registry config subcommands
items:
- name: registry config
- href: reference/microsoft/windows/registry/cli/config/command.md
+ href: reference/tools/registry/config/index.md
- name: registry config get
- href: reference/microsoft/windows/registry/cli/config/get.md
+ href: reference/tools/registry/config/get.md
- name: registry config set
- href: reference/microsoft/windows/registry/cli/config/set.md
- - name: registry config test
- href: reference/microsoft/windows/registry/cli/config/test.md
- - name: registry find command
- href: reference/microsoft/windows/registry/cli/find/command.md
- - name: registry query command
- href: reference/microsoft/windows/registry/cli/query/command.md
- - name: registry remove command
- href: reference/microsoft/windows/registry/cli/remove/command.md
- - name: registry schema command
- href: reference/microsoft/windows/registry/cli/schema/command.md
- - name: registry set command
- href: reference/microsoft/windows/registry/cli/set/command.md
- - name: registry test command
- href: reference/microsoft/windows/registry/cli/test/command.md
+ href: reference/tools/registry/config/set.md
+ - name: registry config delete
+ href: reference/tools/registry/config/delete.md
+ - name: registry schema
+ href: reference/tools/registry/schema/index.md
+ - name: Glossary
+ href: glossary.md
\ No newline at end of file
diff --git a/dsc/docs-conceptual/dsc-3.0/resources/samples/first-resource/overview.md b/dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/first-resource/overview.md
similarity index 83%
rename from dsc/docs-conceptual/dsc-3.0/resources/samples/first-resource/overview.md
rename to dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/first-resource/overview.md
index 9a8cb0d..159952e 100644
--- a/dsc/docs-conceptual/dsc-3.0/resources/samples/first-resource/overview.md
+++ b/dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/first-resource/overview.md
@@ -1,7 +1,7 @@
---
description: >-
Explains the How to write your first DSC Resource tutorials at a high level.
-ms.date: 08/04/2023
+ms.date: 03/25/2025
title: Write your first DSC Resource tutorial overview
---
@@ -15,10 +15,10 @@ use-case for DSC Resources.
In these tutorials, you learn how to:
-- Create a DSC Resource in your preferred programming language.
+- Create a DSC resource in your preferred programming language.
- Define the properties of the resource.
-- Implement get and set commands for the resource.
-- Write a manifest for the resource.
+- Implement the **Get** and **Set** operations for the resource as subcommands.
+- Write a resource manifest.
- Manually test the resource.
The tutorials are hosted in the [DSC Samples repository site][02]. The sample code for the end of
@@ -27,6 +27,7 @@ each tutorial is hosted in the [DSC Samples repository][03].
We welcome contributions to the samples repository. For more information, see
[Contributing to the DSC Samples][04].
+
[01]: https://powershell.github.io/DSC-Samples/tstoy/about
[02]: https://powershell.github.io/DSC-Samples
[03]: https://github.com/PowerShell/DSC-Samples
diff --git a/dsc/docs-conceptual/dsc-3.0/resources/tutorials/overview.md b/dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/overview.md
similarity index 86%
rename from dsc/docs-conceptual/dsc-3.0/resources/tutorials/overview.md
rename to dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/overview.md
index f17b33e..d778d97 100644
--- a/dsc/docs-conceptual/dsc-3.0/resources/tutorials/overview.md
+++ b/dsc/docs-conceptual/dsc-3.0/tutorials/resources/authoring/overview.md
@@ -1,18 +1,18 @@
---
description: >-
Explains how the DSC tutorials are organized, where they're hosted, and what they cover.
-ms.date: 08/04/2023
+ms.date: 03/25/2025
title: DSC Resource tutorials overview
---
# DSC Resource tutorials overview
-Each of the tutorials in this section covers a different aspect of implementing a DSC Resource.
+Each of the tutorials in this section covers a different aspect of implementing a DSC resource.
Each tutorial is implemented in at least one programming language. The tutorial implementations
-teach the same concepts and the DSC Resource they create has the same functionality across the
+teach the same concepts and the DSC resource they create has the same functionality across the
language implementations.
-The DSC Resources manage the fictional [TSToy application][01]'s configuration files. While the
+The DSC resources manage the fictional [TSToy application][01]'s configuration files. While the
TSToy application isn't a real production application, managing configuration files is a common
use-case for DSC Resources.