Skip to content

Commit 17a7db9

Browse files
GijsreynGijsreyn
committed
Initial reference documentation for RunCommandOnSet
1 parent b54ed45 commit 17a7db9

File tree

4 files changed

+337
-1
lines changed

4 files changed

+337
-1
lines changed

‎docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/examples/run-a-simple-command.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
description: >
3+
Example showing how you can invoke the Microsoft.DSC.Transitional/RunCommandOnSet resource with DSC to run a simple command.
4+
5+
ms.date: 06/30/2025
6+
ms.topic: reference
7+
title: Run a simple command
8+
---
9+
10+
# Run a simple command
11+
12+
This example shows how you can use the `Microsoft.DSC.Transitional/RunCommandOnSet` resource to
13+
execute a simple command during the set operation.
14+
15+
## Test whether the command would run
16+
17+
The following snippet shows how you can use the resource with the [dsc resource test][01] command to check whether the command would run.
18+
19+
> [!NOTE]
20+
> The `dsc resource test` command performs a synthetic test on this resource. `Microsoft.DSC.Transitional/RunCommandOnSet` doesn't have
21+
> the `test` capability defined in the [resource manifest][02]
22+
23+
```powershell
24+
$instance = @{
25+
executable = "echo"
26+
arguments = @("Configuration applied successfully")
27+
} | ConvertTo-Json
28+
29+
dsc resource test --resource Microsoft.DSC.Transitional/RunCommandOnSet --input $instance
30+
```
31+
32+
When testing the resource, DSC returns a result indicating the desired state:
33+
34+
```yaml
35+
desiredState:
36+
arguments:
37+
- Configuration applied successfully
38+
executable: echo
39+
actualState:
40+
executable: echo
41+
arguments:
42+
- Configuration applied successfully
43+
inDesiredState: true
44+
differingProperties: []
45+
```
46+
47+
The `inDesiredState` field of the result object is set to `true`, indicating that the command would be executed during a set operation.
48+
49+
## Run the command
50+
51+
To execute the command, use the [dsc resource set][03] command.
52+
53+
```powershell
54+
$instance = @{
55+
executable = "C:\Windows\system32\cmd.exe"
56+
arguments = @(
57+
'/C',
58+
'echo Hello world'
59+
)
60+
} | ConvertTo-Json
61+
dsc resource set --resource Microsoft.DSC.Transitional/RunCommandOnSet --input $instance
62+
```
63+
64+
When the resource runs the command, DSC returns a result similar to:
65+
66+
```yaml
67+
beforeState:
68+
executable: cmd
69+
arguments:
70+
- /C
71+
- echo
72+
- Hello world
73+
afterState:
74+
executable: cmd
75+
arguments:
76+
- /C
77+
- echo
78+
- Hello world
79+
changedProperties: []
80+
```
81+
82+
> [!NOTE]
83+
> The output from the command executed by the `runCommandOnSet` resource isn't displayed in the console.
84+
> If you want to capture the output, you should redirect it to a file.
85+
86+
<!-- Link reference definitions -->
87+
[01]: ../../../../../cli/resource/test.md
88+
[02]: ../../../../../../schemas/resource/manifest/test.md
89+
[03]: ../../../../../cli/resource/set.md

‎docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/examples/run-powershell-command.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
description: >
3+
Example showing how you can invoke the Microsoft.DSC.Transitional/RunCommandOnSet resource with DSC to
4+
run a PowerShell command.
5+
ms.date: 06/30/2025
6+
ms.topic: reference
7+
title: Run a PowerShell command
8+
---
9+
10+
# Run a PowerShell command
11+
12+
This example shows how you can use the `Microsoft.DSC.Transitional/RunCommandOnSet` resource to execute a PowerShell command during the set operation.
13+
14+
## Define the PowerShell command to run
15+
16+
The following snippet shows how you can define a PowerShell command to run during the DSC set operation:
17+
18+
```powershell
19+
$command = "Write-Output Hello | Out-File $env:TEMP\hello.txt"
20+
$instance = @{
21+
executable = "powershell.exe"
22+
arguments = @(
23+
"-Command",
24+
$command
25+
)
26+
} | ConvertTo-Json
27+
28+
dsc resource set --resource Microsoft.DSC.Transitional/RunCommandOnSet --input $instance
29+
```
30+
31+
To verify the results, run the following command:
32+
33+
```powershell
34+
Get-Content -Path $env:TEMP\hello.txt
35+
```
36+
37+
This should return:
38+
39+
```text
40+
Hello
41+
```
42+
43+
## Run the PowerShell command in a configuration document
44+
45+
You can also include this resource in a DSC configuration document:
46+
47+
```powershell
48+
$command = "if ((Get-Command -Name winget -CommandType Application -ErrorAction Ignore)) {winget install --id Microsoft.PowerShell.Preview}"
49+
$document = @"
50+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
51+
resources:
52+
- name: RunPowerShellCommand
53+
type: Microsoft.DSC.Transitional/RunCommandOnSet
54+
properties:
55+
executable: "powershell.exe"
56+
arguments:
57+
- "-Command"
58+
- $command
59+
exitCode: 0
60+
"@
61+
```
62+
63+
Apply the configuration document with the [dsc config set][00] command:
64+
65+
```powershell
66+
dsc config set --input $document
67+
```
68+
69+
To verify the result, you can run the `winget.exe` command:
70+
71+
```powershell
72+
winget list --id Microsoft.PowerShell
73+
```
74+
75+
<!-- Link reference definitions -->
76+
[00]: ../../../../../cli/config/set.md

‎docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/index.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
description: Microsoft.DSC.Transitional/RunCommandOnSet resource reference documentation
3+
ms.date: 06/30/2025
4+
ms.topic: reference
5+
title: Microsoft.DSC.Transitional/RunCommandOnSet
6+
---
7+
8+
# Microsoft.DSC.Transitional/RunCommandOnSet
9+
10+
## Synopsis
11+
12+
Execute a command during DSC set operations.
13+
14+
## Metadata
15+
16+
```yaml
17+
Version : 0.1.0
18+
Kind : resource
19+
Tags : [transitional, windows, linux, macos]
20+
Author : Microsoft
21+
```
22+
23+
## Instance definition syntax
24+
25+
```yaml
26+
resources:
27+
- name: <instance name>
28+
type: Microsoft.DSC.Transitional/RunCommandOnSet
29+
properties:
30+
# Required properties
31+
executable: string
32+
# Optional properties
33+
arguments: array
34+
exitCode: integer
35+
```
36+
37+
## Description
38+
39+
The `Microsoft.DSC.Transitional/RunCommandOnSet` resource enables you to run a specified executable command during the DSC
40+
set operation. This is useful for commands that need to run as part of your configuration, but haven't fully transitioned to
41+
a DSC resource.
42+
43+
The resource allows you to:
44+
45+
- Specify an executable to run
46+
- Pass arguments to the executable
47+
- Define a custom exit code to indicate success
48+
49+
## Capabilities
50+
51+
The resource has the following capabilities:
52+
53+
- `get` - You can use the resource to retrieve the actual state of an instance.
54+
- `set` - You can use the resource to enforce the desired state for an instance.
55+
56+
This resource uses the synthetic test functionality of DSC to determine whether an instance is in
57+
the desired state. For more information about resource capabilities, see
58+
[DSC resource capabilities][00].
59+
60+
## Examples
61+
62+
1. [Run a simple command][01] - Shows how to create and delete registry keys with the
63+
`dsc resource` commands.
64+
1. [Run a PowerShell command][02] - Shows how to create, modify, and delete registry values with the
65+
`dsc resource` commands.
66+
67+
## Properties
68+
69+
The following list describes the properties for the resource.
70+
71+
- **Required properties:** <a id="required-properties"></a> The following properties are always
72+
required when defining an instance of the resource. An instance that doesn't define each of these
73+
properties is invalid.
74+
75+
- [executable](#executable) - The executable to run on set.
76+
77+
- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
78+
They define the desired state for an instance of the resource.
79+
80+
- [arguments](#arguments) - The argument(s), if any, to pass to the executable that runs on get or set.
81+
- [exitCode](#exitcode) - The expected exit code to indicate success, if non-zero. Default is zero for success.
82+
83+
### executable
84+
85+
<details><summary>Expand for <code>executable</code> property metadata</summary>
86+
87+
```yaml
88+
Type : string
89+
IsRequired : true
90+
IsKey : false
91+
IsReadOnly : false
92+
IsWriteOnly : false
93+
```
94+
95+
</details>
96+
97+
Defines the executable program or command to run during the DSC Set operation.
98+
This can be any valid executable file or command accessible from the system PATH.
99+
100+
### arguments
101+
102+
<details><summary>Expand for <code>arguments</code> property metadata</summary>
103+
104+
```yaml
105+
Type : array
106+
ItemsType : string
107+
IsRequired : false
108+
IsKey : false
109+
IsReadOnly : false
110+
IsWriteOnly : false
111+
```
112+
113+
</details>
114+
115+
Defines the arguments to pass to the executable. Each element in the array represents a
116+
separate argument that will be passed to the executable.
117+
118+
### exitCode
119+
120+
<details><summary>Expand for <code>exitCode</code> property metadata</summary>
121+
122+
```yaml
123+
Type : integer
124+
IsRequired : false
125+
IsKey : false
126+
IsReadOnly : false
127+
IsWriteOnly : false
128+
DefaultValue : 0
129+
```
130+
131+
</details>
132+
133+
Defines the expected exit code to indicate success if not zero. By default, an exit code of 0 indicates
134+
successful execution. If your executable returns a different exit code to indicate success, specify that value here.
135+
136+
## Instance validating schema
137+
138+
The following snippet contains the JSON Schema that validates an instance of the resource.
139+
140+
```json
141+
{
142+
"type": "object",
143+
"required": [
144+
"executable"
145+
],
146+
"properties": {
147+
"arguments": {
148+
"title": "The argument(s), if any, to pass to the executable that runs on set",
149+
"type": "array"
150+
},
151+
"executable": {
152+
"title": "The executable to run on set",
153+
"type": "string"
154+
},
155+
"exitCode": {
156+
"title": "The expected exit code to indicate success, if non-zero. Default is zero for success.",
157+
"type": "integer"
158+
}
159+
},
160+
"additionalProperties": false
161+
}
162+
```
163+
164+
## See also
165+
166+
- [Microsoft.DSC.PowerShell](../../PowerShell/index.md)
167+
- [Microsoft.Windows.WindowsPowerShell](../../../../Microsoft/Windows/WindowsPowerShell/index.md)
168+
169+
[00]: ../../../../concepts/dsc/resource-capabilities.md
170+
[01]: ./examples/run-a-simple-command.md
171+
[02]: ./examples/run-powershell-command.md

‎runcommandonset/tests/runcommandonset.set.tests.ps1

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Describe 'tests for runcommandonset set' {
8080
It 'Input provided via configuration doc' {
8181
$command = "Write-Output Hello | Out-File " + $TestDrive + "/output.txt" + " -Append"
8282
$config_yaml = @"
83-
`$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
83+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
8484
resources:
8585
- name: set
8686
type: Microsoft.DSC.Transitional/RunCommandOnSet

0 commit comments

Comments
 (0)