Skip to content

Commit 53e246b

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #927 from Gijsreyn/reference-doc-runcommandonset
Add reference documentation for Microsoft.DSC.Transitional/RunCommandOnSet
2 parents efcb07c + 81c0e89 commit 53e246b

File tree

4 files changed

+311
-1
lines changed

4 files changed

+311
-1
lines changed

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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+
## Run the command
16+
17+
The following snippet shows how you can invoke the resource to execute a custom command with [dsc resource set][00].
18+
19+
```powershell
20+
$instance = @{
21+
executable = "C:\Windows\system32\cmd.exe"
22+
arguments = @(
23+
'/C',
24+
'echo Hello world'
25+
)
26+
} | ConvertTo-Json
27+
dsc resource set --resource Microsoft.DSC.Transitional/RunCommandOnSet --input $instance
28+
```
29+
30+
When the resource runs the command, DSC returns a result similar to:
31+
32+
```yaml
33+
beforeState:
34+
executable: cmd
35+
arguments:
36+
- /C
37+
- echo
38+
- Hello world
39+
afterState:
40+
executable: cmd
41+
arguments:
42+
- /C
43+
- echo
44+
- Hello world
45+
changedProperties: []
46+
```
47+
48+
> [!NOTE]
49+
> The output from the command executed by the `runCommandOnSet` resource isn't displayed in the console.
50+
> If you want to capture the output, you should redirect it to a file.
51+
52+
<!-- Link reference definitions -->
53+
[00]: ../../../../../cli/resource/set.md

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

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

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

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