From 9a61250b8b7453ba92011fe962a0b9eb231c7b5c Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 7 Aug 2023 13:14:14 -0500 Subject: [PATCH] (MAINT) Sync reference docs This change syncs the reference documentation in the repository with the reference documentation published to the official docs site. This enables us to keep the reference documentation in the repository as the source of truth for the schemas and CLI. When there is a release or a fix to the documentation, the docs team will sync the docs as-needed. This should keep the friction lower for the engineering team, so they can adjust (or ping the docs team to adjust) reference documentation in the repository instead of tracking documentation across multiple repos. Primarily, the updates in this sync include: - Adding the required metadata - Fixing broken links - Fixing incorrect syntax --- docs/reference/cli/config/command.md | 9 +- docs/reference/cli/config/get.md | 7 + docs/reference/cli/config/set.md | 7 + docs/reference/cli/config/test.md | 7 + docs/reference/cli/dsc.md | 13 +- docs/reference/cli/resource/command.md | 9 +- docs/reference/cli/resource/get.md | 9 +- docs/reference/cli/resource/list.md | 9 +- docs/reference/cli/resource/schema.md | 7 + docs/reference/cli/resource/set.md | 7 + docs/reference/cli/resource/test.md | 7 + docs/reference/cli/schema/command.md | 27 ++-- docs/reference/schemas/config/document.md | 36 +++-- docs/reference/schemas/config/parameter.md | 9 +- docs/reference/schemas/config/resource.md | 19 ++- docs/reference/schemas/definitions/message.md | 7 + .../definitions/parameters/dataTypes.md | 7 + .../schemas/definitions/resourceType.md | 7 + docs/reference/schemas/outputs/config/get.md | 7 + docs/reference/schemas/outputs/config/set.md | 7 + docs/reference/schemas/outputs/config/test.md | 7 + .../reference/schemas/outputs/resource/get.md | 7 + .../schemas/outputs/resource/list.md | 7 + .../reference/schemas/outputs/resource/set.md | 7 + .../schemas/outputs/resource/test.md | 7 + .../schemas/resource/manifest/get.md | 9 +- .../schemas/resource/manifest/provider.md | 7 + .../schemas/resource/manifest/root.md | 9 +- .../resource/manifest/schema/embedded.md | 7 + .../resource/manifest/schema/property.md | 7 + .../schemas/resource/manifest/set.md | 7 + .../schemas/resource/manifest/test.md | 7 + .../schemas/resource/manifest/validate.md | 7 + .../schemas/resource/properties/ensure.md | 7 + .../resource/properties/inDesiredState.md | 7 + .../schemas/resource/properties/overview.md | 9 ++ .../schemas/resource/properties/purge.md | 7 + .../resource/properties/rebootRequested.md | 7 + docs/resources/concepts/anatomy.md | 137 ------------------ 39 files changed, 310 insertions(+), 176 deletions(-) delete mode 100644 docs/resources/concepts/anatomy.md diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/command.md index 0b8bbc07..3eb8656d 100644 --- a/docs/reference/cli/config/command.md +++ b/docs/reference/cli/config/command.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc config' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config +--- + # dsc config ## Synopsis @@ -45,7 +52,7 @@ 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](#-h---help) option on the command or subcommand to display the help information. For example, `dsc config --help` or `dsc config set --help`. ## Options diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md index 035b0f82..fe6130be 100644 --- a/docs/reference/cli/config/get.md +++ b/docs/reference/cli/config/get.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc config get' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config get +--- + # dsc config get ## Synopsis diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md index b47c87a4..223d1be6 100644 --- a/docs/reference/cli/config/set.md +++ b/docs/reference/cli/config/set.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc config set' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config set +--- + # dsc config set ## Synopsis diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md index e60838aa..6cd072c2 100644 --- a/docs/reference/cli/config/test.md +++ b/docs/reference/cli/config/test.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc config test' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config test +--- + # dsc config test ## Synopsis diff --git a/docs/reference/cli/dsc.md b/docs/reference/cli/dsc.md index 8adc9375..7e0dcc24 100644 --- a/docs/reference/cli/dsc.md +++ b/docs/reference/cli/dsc.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc +--- + # dsc ## Synopsis @@ -52,7 +59,7 @@ 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](#-h---help) option on a command to display the help information. For example, `dsc config --help` or `dsc config set --help`. ## Options @@ -95,6 +102,6 @@ Type: Boolean Mandatory: false ``` -[01]: config.md +[01]: config/command.md [02]: resource/command.md -[03]: schema.md +[03]: schema/command.md diff --git a/docs/reference/cli/resource/command.md b/docs/reference/cli/resource/command.md index 24bfc23a..aa9b8c88 100644 --- a/docs/reference/cli/resource/command.md +++ b/docs/reference/cli/resource/command.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource +--- + # dsc resource ## Synopsis @@ -57,7 +64,7 @@ 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](#-h---help) option on the command or subcommand to display the help information. For example, `dsc resource --help` or `dsc resource set --help`. ## Options diff --git a/docs/reference/cli/resource/get.md b/docs/reference/cli/resource/get.md index ba2c09b0..57b34ddd 100644 --- a/docs/reference/cli/resource/get.md +++ b/docs/reference/cli/resource/get.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource get' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource get +--- + # dsc resource get ## Synopsis @@ -130,4 +137,4 @@ This command returns JSON output that includes the actual state of the instance. information, see [dsc resource get result schema][02]. [01]: ../config/get.md -[02]: ../../schemas/outputs/resource/ +[02]: ../../schemas/outputs/resource/get.md diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 28addb98..92c553d6 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource list' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource list +--- + # dsc resource list ## Synopsis @@ -173,4 +180,4 @@ This command returns a JSON object for each resource that includes the resource' manifest settings, and other metadata. For more information, see [dsc resource list result schema][01]. -[01]: ../../schemas/output/resource/list.md +[01]: ../../schemas/outputs/resource/list.md diff --git a/docs/reference/cli/resource/schema.md b/docs/reference/cli/resource/schema.md index e287f044..9ae0e6ac 100644 --- a/docs/reference/cli/resource/schema.md +++ b/docs/reference/cli/resource/schema.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource schema' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource schema +--- + # dsc resource schema ## Synopsis diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md index 61137b6e..490dbc8c 100644 --- a/docs/reference/cli/resource/set.md +++ b/docs/reference/cli/resource/set.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource set' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource set +--- + # dsc resource set ## Synopsis diff --git a/docs/reference/cli/resource/test.md b/docs/reference/cli/resource/test.md index 381d05e4..0b309bc8 100644 --- a/docs/reference/cli/resource/test.md +++ b/docs/reference/cli/resource/test.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc resource test' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource test +--- + # dsc resource test ## Synopsis diff --git a/docs/reference/cli/schema/command.md b/docs/reference/cli/schema/command.md index 43c1090a..fa6ffcfb 100644 --- a/docs/reference/cli/schema/command.md +++ b/docs/reference/cli/schema/command.md @@ -1,3 +1,10 @@ +--- +description: Command line reference for the 'dsc schema' command +ms.date: 08/04/2023 +ms.topic: reference +title: dsc schema +--- + # dsc schema ## Synopsis @@ -7,7 +14,7 @@ Gets the JSON schema for a DSC type. ## Syntax ```sh -dsc [Options] --type +dsc schema [Options] --type ``` ## Description @@ -90,12 +97,12 @@ Type: Boolean Mandatory: false ``` -[01]: ../schemas/outputs/resource/list.md -[02]: ../schemas/resource/manifest.md -[03]: ../schemas/outputs/resource/get.md -[04]: ../schemas/outputs/resource/set.md -[05]: ../schemas/outputs/resource/test.md -[06]: ../schemas/configuration/document.md -[07]: ../schemas/outputs/config/get.md -[08]: ../schemas/outputs/config/set.md -[09]: ../schemas/outputs/config/test.md +[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/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 7905cde1..a0c4fe11 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a Desired State Configuration document. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Configuration document schema reference +--- + # DSC Configuration document schema reference ## Synopsis @@ -24,7 +31,7 @@ recommends drafting configuration documents in YAML. For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must end with `.dsc.config.json` or `.dsc.config.yaml`. -For more information, see [DSC Configurations overview][01] + The rest of this document describes the schema DSC uses to validation configuration documents. @@ -77,8 +84,10 @@ Parameters may be overridden at run-time, enabling re-use of the same configurat different contexts. For more information about defining parameters in a configuration, see -[DSC Configuration document parameter schema][02]. For more information about using parameters in a -configuration, see [DSC Configuration parameters][03] +[DSC Configuration document parameter schema][02]. + + ```yaml Type: object @@ -96,8 +105,8 @@ This can help reduce the amount of copied values and options for resources in th which makes the document easier to read and maintain. Unlike parameters, variables can only be defined in the configuration and can't be overridden at run-time. -For more information about using variables in a configuration, see -[DSC Configuration variables][04]. + ```yaml Type: object @@ -110,9 +119,10 @@ The `resources` property defines a list of DSC Resource instances that the confi Every instance in the list must be unique, but instances may 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]. For more information about how DSC uses resources -in a configuration, see [DSC Configuration resources][06] and -[DSC Configuration resource groups][07]. +[DSC Configuration document resource schema][05]. + + ```yaml Type: array @@ -121,10 +131,10 @@ Minimum Item Count: 1 Valid Item Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json ``` -[01]: ../../../configurations/overview.md + [02]: parameter.md -[03]: ../../../configurations/parameters.md -[04]: ../../../configurations/variables.md + + [05]: resource.md -[06]: ../../../configurations/resources.md -[07]: ../../../configurations/resource-groups.md + + diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index 178fc55b..e4145359 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a parameter in a Desired State Configuration document. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Configuration document parameter schema +--- + # DSC Configuration document parameter schema ## Synopsis @@ -181,5 +188,5 @@ Type: int Required: false ``` -[01]: resources.md +[01]: resource.md [02]: ../definitions/parameters/dataTypes.md diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index 0f3fb0b8..e4d36957 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/reference/schemas/config/resource.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a resource instance in a Desired State Configuration document. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Configuration document resource instance schema +--- + # DSC Configuration document resource instance schema ## Synopsis @@ -58,10 +65,10 @@ 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][02], the value may be an empty object (`{}`). DSC uses the +be an object. For assertion resources, the value may be an empty object (`{}`). DSC uses the DSC Resource's instance schema to validate the defined properties. -For more information about instance schemas in DSC, see [DSC Resource instance schemas][03]. + ```yaml Type: object @@ -86,7 +93,7 @@ and `` is the dependency's `name` property. Multiple instances can depend on the same instance, but every dependency for an instance must be unique in that instance's `dependsOn` property. -For more information, see [Configuration resource dependencies][04]. + ```yaml Type: array @@ -97,6 +104,6 @@ Valid Items Pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ ``` [01]: ../definitions/resourceType.md -[02]: ../../../resources/concepts/assertion-resources.md -[03]: ../../../resources/concepts/schemas.md -[04]: ../../../configurations/concepts/dependencies.md + + + diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md index c64c5d88..2c0a7332 100644 --- a/docs/reference/schemas/definitions/message.md +++ b/docs/reference/schemas/definitions/message.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a structured message returned from a 'dsc config' command. +ms.date: 08/04/2023 +ms.topic: reference +title: Structured message schema reference +--- + # Structured message schema reference ## Synopsis diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md index f8fcb981..696b30da 100644 --- a/docs/reference/schemas/definitions/parameters/dataTypes.md +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for valid parameter data types in a configuration document. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC configuration parameter data type schema reference +--- + # DSC configuration parameter data type schema reference ## Synopsis diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md index 72526d71..cae323ce 100644 --- a/docs/reference/schemas/definitions/resourceType.md +++ b/docs/reference/schemas/definitions/resourceType.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a resource instance type name +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource fully qualified type name schema reference +--- + # DSC Resource fully qualified type name schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md index bc78fee0..1f3d641e 100644 --- a/docs/reference/schemas/outputs/config/get.md +++ b/docs/reference/schemas/outputs/config/get.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc config get' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config get result schema reference +--- + # dsc config get result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md index 24dc5c34..b3a1ffcd 100644 --- a/docs/reference/schemas/outputs/config/set.md +++ b/docs/reference/schemas/outputs/config/set.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc config set' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config set result schema reference +--- + # dsc config set result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md index 61e8593c..438684c1 100644 --- a/docs/reference/schemas/outputs/config/test.md +++ b/docs/reference/schemas/outputs/config/test.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc config test' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc config test result schema reference +--- + # dsc config test result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md index 85eebee3..ae17428b 100644 --- a/docs/reference/schemas/outputs/resource/get.md +++ b/docs/reference/schemas/outputs/resource/get.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc resource get' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource get result schema reference +--- + # dsc resource get result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md index 8e06b517..b6ea27b2 100644 --- a/docs/reference/schemas/outputs/resource/list.md +++ b/docs/reference/schemas/outputs/resource/list.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc resource list' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource list result schema reference +--- + # dsc resource list result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md index 8dfab0f2..89146174 100644 --- a/docs/reference/schemas/outputs/resource/set.md +++ b/docs/reference/schemas/outputs/resource/set.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc resource set' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource set result schema reference +--- + # dsc resource set result schema reference ## Synopsis diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md index 8f4e2de4..cb3bd708 100644 --- a/docs/reference/schemas/outputs/resource/test.md +++ b/docs/reference/schemas/outputs/resource/test.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the data returned by the 'dsc resource test' command. +ms.date: 08/04/2023 +ms.topic: reference +title: dsc resource test result schema reference +--- + # dsc resource test result schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index 938837cb..d2fc4045 100644 --- a/docs/reference/schemas/resource/manifest/get.md +++ b/docs/reference/schemas/resource/manifest/get.md @@ -1,4 +1,11 @@ -# Command-based DSC Resource manifest schema reference +--- +description: JSON schema reference for the 'get' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest get property schema reference +--- + +# DSC Resource manifest get property schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md index cf0fbe1b..c4410ef0 100644 --- a/docs/reference/schemas/resource/manifest/provider.md +++ b/docs/reference/schemas/resource/manifest/provider.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the 'provider' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest provider property schema reference +--- + # DSC Resource manifest provider property schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index 113d9c09..7a21c659 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: Command-based DSC Resource manifest schema reference +--- + # Command-based DSC Resource manifest schema reference ## Synopsis @@ -205,4 +212,4 @@ Required: true [04]: test.md [05]: validate.md [06]: provider.md -[07]: schema.md +[07]: schema/property.md diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md index 5951d09d..ac691944 100644 --- a/docs/reference/schemas/resource/manifest/schema/embedded.md +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the embedded instance schema in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest embedded schema reference +--- + # DSC Resource manifest embedded schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 9eca4c2c..e84d9289 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the 'schema' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest schema property schema reference +--- + # DSC Resource manifest schema property reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index 30677f95..9af946e7 100644 --- a/docs/reference/schemas/resource/manifest/set.md +++ b/docs/reference/schemas/resource/manifest/set.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the 'set' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest set property schema reference +--- + # DSC Resource manifest set property schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index 185f4880..91234c46 100644 --- a/docs/reference/schemas/resource/manifest/test.md +++ b/docs/reference/schemas/resource/manifest/test.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the 'test' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest test property schema reference +--- + # DSC Resource manifest test property schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md index e5304da2..f112ed73 100644 --- a/docs/reference/schemas/resource/manifest/validate.md +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the 'validate' property in a DSC Resource manifest +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource manifest validate property schema reference +--- + # DSC Resource manifest validate property schema reference ## Synopsis diff --git a/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md index 3f373be1..282854bd 100644 --- a/docs/reference/schemas/resource/properties/ensure.md +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the '_ensure' well-known DSC Resource property. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource _ensure property schema +--- + # DSC Resource _ensure property schema ## Synopsis diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md index 98532aff..e339df96 100644 --- a/docs/reference/schemas/resource/properties/inDesiredState.md +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the '_inDesiredState' well-known DSC Resource property. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource _inDesiredState property schema +--- + # DSC Resource _inDesiredState property schema ## Synopsis diff --git a/docs/reference/schemas/resource/properties/overview.md b/docs/reference/schemas/resource/properties/overview.md index d8ba9b6e..2ceb7502 100644 --- a/docs/reference/schemas/resource/properties/overview.md +++ b/docs/reference/schemas/resource/properties/overview.md @@ -1,3 +1,12 @@ +--- +description: >- + Information about the list of well-known DSC Resource properties, including their purpose and how + to add them to a resource's manifest. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC well-known properties +--- + # DSC well-known properties DSC has support for several well-known properties. Some well-known properties enable a DSC Resource diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md index 1d367c68..549528ae 100644 --- a/docs/reference/schemas/resource/properties/purge.md +++ b/docs/reference/schemas/resource/properties/purge.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the '_purge' well-known DSC Resource property. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource _purge property schema +--- + # DSC Resource _purge property schema ## Synopsis diff --git a/docs/reference/schemas/resource/properties/rebootRequested.md b/docs/reference/schemas/resource/properties/rebootRequested.md index 0d180617..bb67e942 100644 --- a/docs/reference/schemas/resource/properties/rebootRequested.md +++ b/docs/reference/schemas/resource/properties/rebootRequested.md @@ -1,3 +1,10 @@ +--- +description: JSON schema reference for the '_rebootRequested' well-known DSC Resource property. +ms.date: 08/04/2023 +ms.topic: reference +title: DSC Resource _rebootRequested property schema +--- + # DSC Resource _rebootRequested property schema ## Synopsis diff --git a/docs/resources/concepts/anatomy.md b/docs/resources/concepts/anatomy.md deleted file mode 100644 index 467e3d43..00000000 --- a/docs/resources/concepts/anatomy.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -author: michaeltlombardi -title: Anatomy of a command-based DSC Resource -description: >- - Describes the components of a command-based DSC Resource, how DSC uses them, and what's required - of them. -ms.author: mlombardi -ms.topic: concept-article -ms.date: 2023-07-13 ---- - -# Anatomy of a command-based DSC Resource - -DSC Resources provide a standardized interface for managing the settings of a system. A resource -defines properties you can manage and implements the code needed to get an instance of the -resource. - -Command-based DSC Resources are defined with at least two files: - -1. A DSC Resource manifest that tells DSC how to interact with the resource. -1. One or more executable files and their dependencies to manage instances of the resource. - -## DSC Resource manifests - -DSC Resource manifests are defined as JSON files. For DSC to recognize a JSON file as a manifest, -the file must meet the following criteria: - -1. The file must be discoverable in the `PATH` environment variable. -1. The filename must end with `.dsc.resource.json`. - -When DSC searches the local system for available command-based DSC Resources, it searches every -folder in the `PATH` for files that use the DSC Resource manifest naming convention. DSC then -parses each of those discovered files and validates them against the -[DSC Resource Manifest JSON schema][01]. - -If the JSON file validates against the schema, DSC can use the DSC Resource. - -At a minimum, the manifest must define: - -- The version of the DSC Resource Manifest JSON schema it's compatible with. -- The fully qualified name of the resource, like `Microsoft.Windows/Registry`. The fully qualified - name syntax is `[.][.]/`. The group and area components of the fully - qualified name enable organizing resources into namespaces. -- How DSC can call the command to get the current state of a resource instance. -- A way to validate an instance. This can be one of the following: - - A JSON schema that describes an instance - - A command DSC must call to get the schema at runtime - - A command to validate nested DSC Resources. This last option only applies to DSC Group - Resources and DSC Provider Resources. - -The manifest may optionally define: - -- How DSC can call the command to test whether an instance is in the desired - state. -- How DSC can call the command to set an instance to the desired state. -- The meaning of the non-zero exit codes returned by the command. -- How DSC can call the command to manage other DSC Resources, when the resource is a DSC Group - Resource or a DSC Provider Resource. -- Metadata about the resource, like its author and a short description. - -If the manifest doesn't define how to test an instance of the resource, DSC performs a synthetic -test for resource instances. DSC's synthetic test always gets the actual state of an instance and -does a strict case-sensitive comparison of the instance's properties to the desired state. The -synthetic test ignores any properties prefixed with an underscore (`_`) or dollar sign (`$`). If -any of the properties aren't exactly the same as the defined desired state, DSC reports the -instance as being non-compliant. - -If the manifest doesn't define how to set an instance of the DSC Resource, DSC can't use the -resource to enforce desired state. - -The manifest doesn't need to specify the same executable file for every operation. The definition -for each operation is independent. - -For more information on authoring DSC Resource manifests, see -[Authoring a DSC Resource Manifest][02]. - -## DSC Resource executables - -Command-based DSC Resources always require an executable file for DSC to run. The DSC Resource -Manifest doesn't need to be bundled with the executable. The executable can be any executable file, -such as a binary application or a shell script. A resource may use different executables for -different operations. - -For DSC to use an executable, it must be discoverable in the `PATH` environment variable. DSC calls -the executable once per operation, using the exit code returned by the executable to determine if -the command was successful. DSC treats exit code `0` as a success and all other exit codes as an -error. For more information about error handling, see -[Handling errors in a command-based DSC Resource][03]. - -### Inputs - -DSC sends input to command-based DSC Resources as either a JSON data blob over stdin or as a set of -argument flags and values. Input handling is defined per-operation in the DSC Resource Manifest. - -When DSC sends the input as JSON over stdin, the data blob is the JSON representation of an -instance's desired state. This is the most robust option for a resource, as it enables the resource -to support complex properties with nested objects. - -When DSC sends the input as arguments, it generates a pair of arguments for each of the specified -properties. The first argument is the name of the property prefixed with `--`, such as -`--duration`. The second argument is the property's value. The ordering of the argument pairs isn't -guaranteed. This input method doesn't support complex properties. - -### Outputs - -The executable for a command-based DSC Resource must return JSON data to stdout when called by DSC. -The output encoding must be UTF-8. When the resource returns the state of an instance, DSC -validates the JSON data against the resource's instance schema. - -For DSC Provider Resources, DSC expects the executable to pass through the instance states for the -resources it manages as either a single JSON array or as a series of [JSON Lines][04]. - -Command-based DSC Resources can report logging information to DSC by emitting JSON Lines to stderr. -Each log entry must be a JSON object that includes two keys: - -1. The `message` key defines the human-readable string for the log entry. -1. The `level` key defines whether the message represents an `Error`, a `Warning`, or `Information`. - -DSC collects messages from resources and displays them in the results for a configuration -operation. When DSC invokes a resource directly outside of a configuration, it doesn't collect the -messages. Instead, they're just emitted to stderr. - -For more information about logging from command-based DSC Resources, see -[Logging messages from a command-based DSC Resource][05]. - -## Related Content - -- [Authoring a DSC Resource Manifest][02] -- [Write a command-based DSC Resource][06] -- [DSC Resource Manifest schema reference][01] - -[01]: ../../reference/schemas/resource/manifest/root.md -[02]: authoring-a-manifest.md -[03]: handling-errors.md -[04]: https://jsonlines.org/ -[05]: logging-messages.md -[06]: write-a-command-based-resource.md