Skip to content

Commit e19f087

Browse files
GijsreynGijsreyn
committed
Add reference documentation for Microsoft.DSC.Debug/Echo
1 parent 05f00db commit e19f087

File tree

3 files changed

+261
-1
lines changed

3 files changed

+261
-1
lines changed

‎docs/reference/resources/Microsoft/DSC/Debug/echo/examples/basic-echo-example.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
description: Demonstrates basic usage of the Microsoft.DSC.Debug/Echo resource
3+
ms.date: 06/22/2025
4+
ms.topic: reference
5+
title: Basic echo example
6+
---
7+
8+
This example demonstrates how to use the `Microsoft.DSC.Debug/Echo` to test the output returned by DSC.
9+
10+
## Test the output returned by DSC
11+
12+
The following snippet shows how you can use the resource with the [dsc resource test][01] command to test if the
13+
system is in the desired state.
14+
15+
```powershell
16+
$instance = @{
17+
output = 'Hello World!'
18+
} | ConvertTo-Json
19+
20+
dsc resource test --resource Microsoft.DSC.Debug/Echo --input $instance
21+
```
22+
23+
```yaml
24+
desiredState:
25+
output: Hello World!
26+
actualState:
27+
output: Hello World!
28+
inDesiredState: true
29+
differingProperties: []
30+
```
31+
32+
> [!NOTE]
33+
> The `Microsoft.DSC.Debug/Echo` resource always returns `inDesiredState: true` because it's a
34+
> test resource designed to echo back values.
35+
> It doesn't actually check or enforce anything on the system - it simply returns whatever value you
36+
> provide as output.
37+
38+
## Using the get capability
39+
40+
The `Microsoft.DSC.Debug/Echo` resource's `get` capability returns the current value in the output property:
41+
42+
```powershell
43+
$instance = @{
44+
output = 'Hello World!'
45+
} | ConvertTo-Json
46+
47+
dsc resource get --resource Microsoft.DSC.Debug/Echo --input $instance
48+
```
49+
50+
The resource will return the same output value:
51+
52+
```json
53+
{"actualState":{"output":"Hello World!"}}
54+
```
55+
56+
## Using the set capability
57+
58+
The `Microsoft.DSC.Debug/Echo` resource's `set` capability simply accepts a value and echoes
59+
it back without modifying anything:
60+
61+
```powershell
62+
$instance = @{
63+
output = @{
64+
name = "ExampleSetting"
65+
value = 123
66+
enabled = $true
67+
}
68+
} | ConvertTo-Json
69+
70+
dsc resource set --resource Microsoft.DSC.Debug/Echo --input $instance
71+
```
72+
73+
This will report success and echo the complex object:
74+
75+
```yaml
76+
beforeState:
77+
output:
78+
value: 123
79+
enabled: true
80+
name: ExampleSetting
81+
afterState:
82+
output:
83+
value: 123
84+
enabled: true
85+
name: ExampleSetting
86+
changedProperties: []
87+
```
88+
89+
> [!NOTE]
90+
> Even though you're using the `set` capability, no actual changes are made to the system.
91+
92+
## See also
93+
94+
- [Microsoft.DSC.Debug/Echo resource](../index.md)

‎docs/reference/resources/Microsoft/DSC/Debug/echo/index.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
description: Microsoft.DSC.Debug/Echo resource reference documentation
3+
ms.date: 06/22/2025
4+
ms.topic: reference
5+
title: Microsoft.DSC.Debug/Echo
6+
---
7+
8+
# Microsoft.DSC.Debug/Echo
9+
10+
## Synopsis
11+
12+
A debug resource for testing and troubleshooting DSC (Desired State Configuration) behavior.
13+
14+
## Metadata
15+
16+
```yaml
17+
Version : 1.0.0
18+
Kind : resource
19+
Tags : [Windows, MacOS, Linux]
20+
Author : Microsoft
21+
```
22+
23+
## Instance definition syntax
24+
25+
```yaml
26+
resources:
27+
- name: <instance name>
28+
type: Microsoft.DSC.Debug/Echo
29+
properties:
30+
# Required properties
31+
output: anyOf # array, boolean, integer, string
32+
```
33+
34+
## Description
35+
36+
The `Microsoft.DSC.Debug/Echo` resource is a debugging utility that echoes back the configuration
37+
data passed to it. This resource is particularly useful for:
38+
39+
- Testing DSC configuration syntax and structure
40+
- Debugging parameter passing between resources
41+
- Verifying that DSC is processing configurations as expected
42+
- Understanding how DSC transforms and handles configuration data
43+
44+
> [!NOTE]
45+
> This resource is installed with DSC itself on any systems.
46+
>
47+
> You can update this resource by updating DSC. When you update DSC, the updated version of this
48+
> resource is automatically available.
49+
50+
## Capabilities
51+
52+
The resource has the following capabilities:
53+
54+
- `get` - You can use the resource to retrieve the actual state of an instance.
55+
- `set` - You can use the resource to enforce the desired state for an instance.
56+
- `test` - You can use the resource to check if the actual state matches the desired state
57+
for an instance.
58+
59+
For more information about resource capabilities, see
60+
[DSC resource capabilities][01].
61+
62+
> [!NOTE]
63+
> Calling any capability on this resource does not affect the system;
64+
> it only echoes the value in the output.
65+
66+
## Examples
67+
68+
1. [Basic echo example](./examples/basic-echo-example.md) - Shows how to use the Echo resource
69+
for basic string and complex data output.
70+
71+
## Properties
72+
73+
The following list describes the properties for the resource.
74+
75+
- **Required properties:** <a id="required-properties"></a> The following property is always
76+
required when defining an instance of the resource. An instance that doesn't define this
77+
property is invalid. For more information, see the "Required resource properties" section in
78+
[DSC resource properties][02]
79+
80+
- [output](#output) - The value to be echoed back by the resource.
81+
82+
- **Key properties:** <a id="key-properties"></a> The following property uniquely identifies an
83+
instance. If two instances of a resource have the same value for this property, the instances are
84+
conflicting. For more information about key properties, see the "Key resource properties" section in [DSC resource properties][03].
85+
86+
- [output](#output) (required) - The value to be echoed back by the resource.
87+
88+
### output
89+
90+
<details><summary>Expand for <code>output</code> property metadata</summary>
91+
92+
```yaml
93+
Type : anyOf (string, array, boolean, integer)
94+
IsRequired : true
95+
IsKey : true
96+
IsReadOnly : false
97+
IsWriteOnly : false
98+
```
99+
100+
</details>
101+
102+
Defines the value to be echoed back by the resource. The `output` property can be any of the following types:
103+
104+
| Type | Description |
105+
|---------|---------------------------------------------|
106+
| string | A string value |
107+
| array | An array of values |
108+
| boolean | A boolean value (`true` or `false`) |
109+
| integer | An integer value |
110+
111+
## Instance validating schema
112+
113+
The following snippet contains the JSON Schema that validates an instance of the resource. The
114+
validating schema only includes schema keywords that affect how the instance is validated. All
115+
non validating keywords are omitted.
116+
117+
```json
118+
{
119+
"type": "object",
120+
"required": [
121+
"output"
122+
],
123+
"properties": {
124+
"output": {
125+
"$ref": "#/definitions/Output"
126+
}
127+
},
128+
"additionalProperties": false,
129+
"definitions": {
130+
"Output": {
131+
"anyOf": [
132+
{
133+
"type": "array",
134+
"items": true
135+
},
136+
{
137+
"type": "boolean"
138+
},
139+
{
140+
"type": "integer",
141+
"format": "int64"
142+
},
143+
true,
144+
true,
145+
{
146+
"type": "string"
147+
},
148+
{
149+
"type": "string"
150+
}
151+
]
152+
}
153+
}
154+
}
155+
```
156+
157+
## See also
158+
159+
- [Microsoft/OSInfo resource][04]
160+
- [DSC resource capabilities][01]
161+
162+
<!-- Link definitions -->
163+
[01]: ../../../../../concepts/resources/capabilities.md
164+
[02]: ../../../../../concepts/resources/properties.md#required-resource-properties
165+
[03]: ../../../../../concepts/resources/properties.md#key-resource-properties
166+
[04]: ../../osinfo/index.md

‎docs/reference/resources/Microsoft/Windows/Registry/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ operation without the `--what-if` flag.
343343

344344
The following snippet contains the JSON Schema that validates an instance of the resource. The
345345
validating schema only includes schema keywords that affect how the instance is validated. All
346-
nonvalidating keywords are omitted.
346+
non validating keywords are omitted.
347347

348348
```json
349349
{

0 commit comments

Comments
 (0)