From 8d82717dfa59caeb74c3692b1a8bbc4eb15624ee Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sun, 22 Jun 2025 05:44:21 +0200 Subject: [PATCH 1/5] Add reference documentation for Microsoft.DSC.Debug/Echo --- .../Debug/echo/examples/basic-echo-example.md | 94 ++++++++++ .../Microsoft/DSC/Debug/echo/index.md | 166 ++++++++++++++++++ .../Microsoft/Windows/Registry/index.md | 2 +- 3 files changed, 261 insertions(+), 1 deletion(-) create mode 100644 docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md new file mode 100644 index 000000000..7661eb630 --- /dev/null +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md @@ -0,0 +1,94 @@ +--- +description: Demonstrates basic usage of the Microsoft.DSC.Debug/Echo resource +ms.date: 06/22/2025 +ms.topic: reference +title: Basic echo example +--- + +This example demonstrates how to use the `Microsoft.DSC.Debug/Echo` to test the output returned by DSC. + +## Test the output returned by DSC + +The following snippet shows how you can use the resource with the [dsc resource test][01] command to test if the +system is in the desired state. + +```powershell +$instance = @{ + output = 'Hello World!' +} | ConvertTo-Json + +dsc resource test --resource Microsoft.DSC.Debug/Echo --input $instance +``` + +```yaml +desiredState: + output: Hello World! +actualState: + output: Hello World! +inDesiredState: true +differingProperties: [] +``` + +> [!NOTE] +> The `Microsoft.DSC.Debug/Echo` resource always returns `inDesiredState: true` because it's a +> test resource designed to echo back values. +> It doesn't actually check or enforce anything on the system - it simply returns whatever value you +> provide as output. + +## Using the get capability + +The `Microsoft.DSC.Debug/Echo` resource's `get` capability returns the current value in the output property: + +```powershell +$instance = @{ + output = 'Hello World!' +} | ConvertTo-Json + +dsc resource get --resource Microsoft.DSC.Debug/Echo --input $instance +``` + +The resource will return the same output value: + +```json +{"actualState":{"output":"Hello World!"}} +``` + +## Using the set capability + +The `Microsoft.DSC.Debug/Echo` resource's `set` capability simply accepts a value and echoes +it back without modifying anything: + +```powershell +$instance = @{ + output = @{ + name = "ExampleSetting" + value = 123 + enabled = $true + } +} | ConvertTo-Json + +dsc resource set --resource Microsoft.DSC.Debug/Echo --input $instance +``` + +This will report success and echo the complex object: + +```yaml +beforeState: + output: + value: 123 + enabled: true + name: ExampleSetting +afterState: + output: + value: 123 + enabled: true + name: ExampleSetting +changedProperties: [] +``` + +> [!NOTE] +> Even though you're using the `set` capability, no actual changes are made to the system. + +## See also + +- [Microsoft.DSC.Debug/Echo resource](../index.md) diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md index e69de29bb..71cf42cab 100644 --- a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md @@ -0,0 +1,166 @@ +--- +description: Microsoft.DSC.Debug/Echo resource reference documentation +ms.date: 06/22/2025 +ms.topic: reference +title: Microsoft.DSC.Debug/Echo +--- + +# Microsoft.DSC.Debug/Echo + +## Synopsis + +A debug resource for testing and troubleshooting DSC (Desired State Configuration) behavior. + +## Metadata + +```yaml +Version : 1.0.0 +Kind : resource +Tags : [Windows, MacOS, Linux] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.DSC.Debug/Echo + properties: + # Required properties + output: anyOf # array, boolean, integer, string +``` + +## Description + +The `Microsoft.DSC.Debug/Echo` resource is a debugging utility that echoes back the configuration +data passed to it. This resource is particularly useful for: + +- Testing DSC configuration syntax and structure +- Debugging parameter passing between resources +- Verifying that DSC is processing configurations as expected +- Understanding how DSC transforms and handles configuration data + +> [!NOTE] +> This resource is installed with DSC itself on any systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## 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. +- `test` - You can use the resource to check if the actual state matches the desired state + for an instance. + +For more information about resource capabilities, see +[DSC resource capabilities][01]. + +> [!NOTE] +> Calling any capability on this resource does not affect the system; +> it only echoes the value in the output. + +## Examples + +1. [Basic echo example](./examples/basic-echo-example.md) - Shows how to use the Echo resource + for basic string and complex data output. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following property is always + required when defining an instance of the resource. An instance that doesn't define this + property is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][02] + + - [output](#output) - The value to be echoed back by the resource. + +- **Key properties:** The following property uniquely identifies an + instance. If two instances of a resource have the same value for this property, the instances are + conflicting. For more information about key properties, see the "Key resource properties" section in [DSC resource properties][03]. + + - [output](#output) (required) - The value to be echoed back by the resource. + +### output + +
Expand for output property metadata + +```yaml +Type : anyOf (string, array, boolean, integer) +IsRequired : true +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the value to be echoed back by the resource. The `output` property can be any of the following types: + +| Type | Description | +|---------|---------------------------------------------| +| string | A string value | +| array | An array of values | +| boolean | A boolean value (`true` or `false`) | +| integer | An integer value | + +## 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 +non validating keywords are omitted. + +```json +{ + "type": "object", + "required": [ + "output" + ], + "properties": { + "output": { + "$ref": "#/definitions/Output" + } + }, + "additionalProperties": false, + "definitions": { + "Output": { + "anyOf": [ + { + "type": "array", + "items": true + }, + { + "type": "boolean" + }, + { + "type": "integer", + "format": "int64" + }, + true, + true, + { + "type": "string" + }, + { + "type": "string" + } + ] + } + } +} +``` + +## See also + +- [Microsoft/OSInfo resource][04] +- [DSC resource capabilities][01] + + +[01]: ../../../../../concepts/resources/capabilities.md +[02]: ../../../../../concepts/resources/properties.md#required-resource-properties +[03]: ../../../../../concepts/resources/properties.md#key-resource-properties +[04]: ../../osinfo/index.md diff --git a/docs/reference/resources/Microsoft/Windows/Registry/index.md b/docs/reference/resources/Microsoft/Windows/Registry/index.md index ee107aa17..092aa6974 100644 --- a/docs/reference/resources/Microsoft/Windows/Registry/index.md +++ b/docs/reference/resources/Microsoft/Windows/Registry/index.md @@ -343,7 +343,7 @@ operation without the `--what-if` flag. 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. +non validating keywords are omitted. ```json { From 02cc9ef6a616b17cadf8db48cf015c6adb65b0a0 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sun, 22 Jun 2025 05:45:12 +0200 Subject: [PATCH 2/5] Add link reference --- .../Microsoft/DSC/Debug/echo/examples/basic-echo-example.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md index 7661eb630..e216724be 100644 --- a/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md @@ -92,3 +92,6 @@ changedProperties: [] ## See also - [Microsoft.DSC.Debug/Echo resource](../index.md) + + +[01]: ../../../../../cli/resource/test.md From ecf65b7c1f59202d70b9b36f21c7a8325b7845f0 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sun, 22 Jun 2025 05:46:05 +0200 Subject: [PATCH 3/5] Typo --- docs/reference/resources/Microsoft/DSC/Debug/echo/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md index 71cf42cab..5383f87d2 100644 --- a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md @@ -9,7 +9,7 @@ title: Microsoft.DSC.Debug/Echo ## Synopsis -A debug resource for testing and troubleshooting DSC (Desired State Configuration) behavior. +A debug resource for testing and troubleshooting Microsoft DSC (Desired State Configuration) behavior. ## Metadata From 3f2e6d24b6200f3ad0ab267ccce54c3fe4150432 Mon Sep 17 00:00:00 2001 From: Gijs Reijn Date: Thu, 26 Jun 2025 05:24:22 +0200 Subject: [PATCH 4/5] Fix remarks --- .../Microsoft/DSC/Debug/echo/index.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md index 5383f87d2..0c4fbac62 100644 --- a/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/index.md @@ -28,7 +28,7 @@ resources: type: Microsoft.DSC.Debug/Echo properties: # Required properties - output: anyOf # array, boolean, integer, string + output: anyOf # array, boolean, integer, object, string ``` ## Description @@ -36,10 +36,10 @@ resources: The `Microsoft.DSC.Debug/Echo` resource is a debugging utility that echoes back the configuration data passed to it. This resource is particularly useful for: -- Testing DSC configuration syntax and structure -- Debugging parameter passing between resources -- Verifying that DSC is processing configurations as expected -- Understanding how DSC transforms and handles configuration data +- Testing DSC configuration syntax and structure. +- Debugging parameter passing between resources. +- Verifying that DSC is processing configurations as expected. +- Understanding how DSC transforms and handles configuration data. > [!NOTE] > This resource is installed with DSC itself on any systems. @@ -60,8 +60,8 @@ For more information about resource capabilities, see [DSC resource capabilities][01]. > [!NOTE] -> Calling any capability on this resource does not affect the system; -> it only echoes the value in the output. +> Invoking any operation on this resource doesn't affect the system. +> This resource only echoes the value in the output. ## Examples @@ -90,7 +90,7 @@ The following list describes the properties for the resource.
Expand for output property metadata ```yaml -Type : anyOf (string, array, boolean, integer) +Type : anyOf (array, boolean, integer, object, string) IsRequired : true IsKey : true IsReadOnly : false @@ -101,12 +101,13 @@ IsWriteOnly : false Defines the value to be echoed back by the resource. The `output` property can be any of the following types: -| Type | Description | -|---------|---------------------------------------------| -| string | A string value | -| array | An array of values | -| boolean | A boolean value (`true` or `false`) | -| integer | An integer value | +| Type | Description | +|:-------:|:---------------------------------------------| +| array | An array of values. | +| boolean | A boolean value (`true` or `false`). | +| integer | An integer value. | +| object | A JSON object of key-value pairs. | +| string | A string value. | ## Instance validating schema @@ -143,7 +144,7 @@ non validating keywords are omitted. true, true, { - "type": "string" + "type": "object" }, { "type": "string" From 230077011485051cc3ff554e34eea2485a74d323 Mon Sep 17 00:00:00 2001 From: Gijs Reijn Date: Fri, 27 Jun 2025 07:35:38 +0200 Subject: [PATCH 5/5] Update example to be YAML --- .../Microsoft/DSC/Debug/echo/examples/basic-echo-example.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md index e216724be..fbdba3e38 100644 --- a/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md +++ b/docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md @@ -49,8 +49,9 @@ dsc resource get --resource Microsoft.DSC.Debug/Echo --input $instance The resource will return the same output value: -```json -{"actualState":{"output":"Hello World!"}} +```yaml +actualState: + output: Hello World! ``` ## Using the set capability