Skip to content

Commit 5b9ce43

Browse files
SteveL-MSFTSteveL-MSFT
authoredJun 10, 2024··
Merge pull request #437 from michaeltlombardi/docs/main/document-latest-changes
(DOCS, SCHEMA) Update for latest unreleased changes
·
v3.1.0-preview.1v3.0.0-preview.8
2 parents acb01cd + 1fb1dbf commit 5b9ce43

File tree

23 files changed

+1455
-122
lines changed

23 files changed

+1455
-122
lines changed
 

‎CHANGELOG.md

+163
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,161 @@ changes since the last release, see the [diff on GitHub][unreleased].
7070
for the `v3.0.0.0-alpha.5` release. Leave the release links under the release section.
7171
-->
7272

73+
### Added
74+
75+
- Added the [`--what-if` (`-w`)][ur-aa] option to the [dsc config set][cmd-cset] command. When you
76+
call `dsc config set` with the `--what-if` option, DSC doesn't actually invoke the resources to
77+
enforce the desired state. Instead, it returns the expected output for the command, showing the
78+
before and after state for each resource instance.
79+
80+
The output for the `dsc config set` operation with the `--what-if` operation is the same as an
81+
[actual configuration set operation][ur-ab], except that the metadata field
82+
[executionType][ur-ac] is set to `WhatIf` instead of `Actual`.
83+
84+
In this release, the generated output is synthetic, based on the results of the resources' `test`
85+
operation. In the future, resources will be able to participate in what-if operations, reporting
86+
more specifically how they will change the system. For example, participating resources could
87+
indicate whether an actual set operation will require a reboot or whether the current user has
88+
the correct permissions to manage that resource instance.
89+
90+
<details><summary>Related work items</summary>
91+
92+
- Issues: [#70][#70]
93+
- PRs: [#400][#400]
94+
95+
</details>
96+
97+
- Added support for [importer resources][ur-ad]. These resources resolve external sources to a
98+
nested DSC Configuration document. The resolved instances are processed as nested resource
99+
instances.
100+
101+
This required some updates to the schemas, all backwards-compatible:
102+
103+
- Added a new [resourceKind][ur-ae] named `Import`.
104+
- Added the [resolve][ur-af] command to resource manifests.
105+
- Added the new [`Resolve`][ur-ag] capability, returned in the output for the
106+
[dsc resource list][cmd-rlist] command when DSC discovers an importer resource.
107+
108+
<details><summary>Related work items</summary>
109+
110+
- Issues: [#429][#429]
111+
- PRs: [#412][#412]
112+
113+
</details>
114+
115+
- Added the `Microsoft.DSC/Include` importer resource to resolve instances from an external
116+
configuration document. The resolved instances are processed as nested instances for the
117+
`Microsoft.DSC/Include` resource instance.
118+
119+
You can use this resource to write smaller configuration documents and compose them as needed.
120+
For example, you could define a security baseline and a web server configuration separately, then
121+
combine them for a given application:
122+
123+
```yaml
124+
$schema: &schema https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
125+
resources:
126+
# Group of included baseline configurations
127+
- name: Baselines
128+
type: Microsoft.DSC/Group
129+
properties:
130+
$schema: *schema
131+
resources:
132+
- name: Security Baseline
133+
type: Microsoft.DSC/Include
134+
properties:
135+
configurationFile: security_baseline.dsc.yaml
136+
parametersFile: security_baseline.parameters.yaml
137+
- name: Web Server Baseline
138+
type: Microsoft.DSC/Include
139+
properties:
140+
configurationFile: web_baseline.dsc.yaml
141+
parametersFile: web_baseline.parameters.yaml
142+
dependsOn:
143+
- "[resourceId('Microsoft.DSC/Include', 'Security Baseline')]"
144+
145+
# application configuration instances, all depend on the baselines
146+
- name: Application configuration
147+
type: MyApp/Settings
148+
properties:
149+
someSetting: someValue
150+
dependsOn:
151+
- "[resourceId('Microsoft.DSC/Group', 'Baselines')]"
152+
```
153+
154+
<details><summary>Related work items</summary>
155+
156+
- Issues: [#429][#429]
157+
- PRs: [#412][#412]
158+
159+
</details>
160+
161+
- Added caching for PowerShell Desired State Configuration (PSDSC) resources when using the
162+
`Microsoft.DSC/PowerShell` and `Microsoft.Windows/PowerShell` adapters. The adapters use the
163+
cache to speed up resource discovery. The performance improvement reduced the resource list time
164+
under tests from eight seconds to two seconds, and reduced invocation operation times by half.
165+
166+
The adapters cache the resources in the following locations, depending on your platform:
167+
168+
| Adapter | Platform | Path |
169+
| :----------------------------: | :------: | :---------------------------------------------- |
170+
| `Microsoft.DSC/PowerShell` | Linux | `$HOME/.dsc/PSAdapterCache.json` |
171+
| `Microsoft.DSC/PowerShell` | macOS | `$HOME/.dsc/PSAdapterCache.json` |
172+
| `Microsoft.DSC/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` |
173+
| `Microsoft.Windows/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` |
174+
175+
The adapters check whether the cache is stale on each run and refresh it if:
176+
177+
- The `PSModulePath` environmental variable is updated.
178+
- Any module is added or removed from the `PSModulePath`.
179+
- Any related files in a cached PSDSC resource module has been updated since the cache was
180+
written. The adapter watches the `LastWriteTime` of module files with the following extensions:
181+
`.ps1`, `.psd1`, `.psm1`, and `.mof`.
182+
183+
<details><summary>Related work items</summary>
184+
185+
- Issues: [#371][#371]
186+
- PRs: [#432][#432]
187+
188+
</details>
189+
190+
- Added the `DSC.PackageManagement/Apt` resource for managing software on systems that use the
191+
advanced package tool (APT). In this release, you can use the resource to:
192+
193+
- Install the latest version of a package.
194+
- Uninstall a package.
195+
- Get the current state of a package.
196+
- Export every installed package as a DSC resource instance.
197+
198+
<details><summary>Related work items</summary>
199+
200+
- Issues: _None_.
201+
- PRs: [#434][#434]
202+
203+
</details>
204+
205+
206+
### Fixed
207+
208+
- Fixed the JSON Schema for [exit codes][ur-fa] in the resource manifest to support negative
209+
integers. Prior to this release, the DSC engine supported negative exit codes but the JSON Schema
210+
forbid them.
211+
212+
<details><summary>Related work items</summary>
213+
214+
- Issues: [#407][#407]
215+
- PRs: [#410][#410]
216+
217+
</details>
218+
73219
<!-- Unreleased change links -->
220+
[ur-aa]: ./docs/reference/cli/config/set.md#-w---what-if
221+
[ur-ab]: ./docs/reference/schemas/outputs/config/set.md
222+
[ur-ac]: ./docs/reference/schemas/metadata/Microsoft.DSC/properties.md#executiontype
223+
[ur-ad]: ./docs/reference/schemas/definitions/resourceKind.md#importer-resources
224+
[ur-ae]: ./docs/reference/schemas/definitions/resourceKind.md
225+
[ur-af]: ./docs/reference/schemas/resource/manifest/resolve.md
226+
[ur-ag]: ./docs/reference/schemas/outputs/resource/list.md#capability-resolve
227+
[ur-fa]: ./docs/reference/schemas/resource/manifest/root.md#exitcodes
74228

75229
## [v3.0.0-preview.7][release-v3.0.0-preview.7] - 2024-04-22
76230

@@ -1318,6 +1472,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
13181472
[#362]: https://github.com/PowerShell/DSC/issues/362
13191473
[#364]: https://github.com/PowerShell/DSC/issues/364
13201474
[#368]: https://github.com/PowerShell/DSC/issues/368
1475+
[#371]: https://github.com/PowerShell/DSC/issues/371
13211476
[#373]: https://github.com/PowerShell/DSC/issues/373
13221477
[#375]: https://github.com/PowerShell/DSC/issues/375
13231478
[#376]: https://github.com/PowerShell/DSC/issues/376
@@ -1327,11 +1482,19 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
13271482
[#385]: https://github.com/PowerShell/DSC/issues/385
13281483
[#388]: https://github.com/PowerShell/DSC/issues/388
13291484
[#397]: https://github.com/PowerShell/DSC/issues/397
1485+
[#400]: https://github.com/PowerShell/DSC/issues/400
13301486
[#401]: https://github.com/PowerShell/DSC/issues/401
13311487
[#405]: https://github.com/PowerShell/DSC/issues/405
1488+
[#407]: https://github.com/PowerShell/DSC/issues/407
1489+
[#410]: https://github.com/PowerShell/DSC/issues/410
1490+
[#412]: https://github.com/PowerShell/DSC/issues/412
1491+
[#429]: https://github.com/PowerShell/DSC/issues/429
1492+
[#432]: https://github.com/PowerShell/DSC/issues/432
1493+
[#434]: https://github.com/PowerShell/DSC/issues/434
13321494
[#45]: https://github.com/PowerShell/DSC/issues/45
13331495
[#49]: https://github.com/PowerShell/DSC/issues/49
13341496
[#57]: https://github.com/PowerShell/DSC/issues/57
1497+
[#70]: https://github.com/PowerShell/DSC/issues/70
13351498
[#73]: https://github.com/PowerShell/DSC/issues/73
13361499
[#75]: https://github.com/PowerShell/DSC/issues/75
13371500
[#89]: https://github.com/PowerShell/DSC/issues/89

‎docs/reference/cli/config/set.md

+14
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,20 @@ Type: String
125125
Mandatory: false
126126
```
127127

128+
### -w, --what-if
129+
130+
When you specify this flag option, DSC doesn't actually change the system state with the `set`
131+
operation. Instead, it returns output indicating _how_ the operation will change system state when
132+
called without this option. Use this option to preview the changes DSC will make to a system.
133+
134+
The output for the command when you use this option is the same as without, except that the
135+
`ExecutionType` metadata field is set to `WhatIf` instead of `Actual`.
136+
137+
```yaml
138+
Type: Boolean
139+
Mandatory: false
140+
```
141+
128142
### -f, --format
129143

130144
The `--format` option controls the console output format for the command. If the command output is

‎docs/reference/cli/dsc.md

+5
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,11 @@ execution of the command.
162162
| `5` | The command failed because a resource definition or instance value was invalid against its JSON schema. |
163163
| `6` | The command was cancelled by a <kbd>Ctrl</kbd>+<kbd>C</kbd> interruption. |
164164

165+
## Notes
166+
167+
DSC expects input strings to use UTF-8 encoding. When you pass input from stdin or the path to a
168+
file, ensure that the input is encoded as UTF-8.
169+
165170
[01]: completer/command.md
166171
[02]: config/command.md
167172
[03]: resource/command.md

‎docs/reference/cli/resource/list.md

+63-58
Large diffs are not rendered by default.

‎docs/reference/schemas/definitions/resourceKind.md

+36-10
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Identifies whether a resource is an adapter resource, a group resource, or a nor
1717
SchemaDialect: https://json-schema.org/draft/2020-12/schema
1818
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json
1919
Type: string
20-
ValidValues: [Resource, Adapter, Group]
20+
ValidValues: [Resource, Adapter, Group, Import]
2121
```
2222
2323
## Description
@@ -27,6 +27,7 @@ DSC supports three kinds of command-based DSC Resources:
2727
- `Resource` - Indicates that the manifest isn't for a group or adapter resource.
2828
- `Group` - Indicates that the manifest is for a [group resource](#group-resources).
2929
- `Adapter` - Indicates that the manifest is for an [adapter resource](#adapter-resources).
30+
- `Import` - Indicates that the manifest is for an [importer resource](#importer-resources).
3031

3132
When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the
3233
`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as
@@ -54,16 +55,39 @@ modules. They don't define resource manifests.
5455
Group resources always operate on nested DSC Resource instances. Group resources can change how the
5556
nested instances are processed, like the `Microsoft.DSC/Assertion` group resource.
5657

58+
A group resource must always define the [kind][aa] property in the resource manifest.
59+
5760
Group resources can also be used to bundle sets of resources together for processing, like the
5861
`Microsoft.DSC/Group` resource. You can use the [dependsOn][03] property for a resource instance in
5962
a configuration to point to a group resource instead of enumerating each resource in the list.
6063

64+
### Importer resources
65+
66+
Importer resources resolve an external source to a set of nested DSC Resource instances. The
67+
properties of an importer resource define how to find and resolve the external source.
68+
69+
An importer resource must always define the [kind][aa] and [resolve][ab] properties in the resource
70+
manifest.
71+
72+
For example, the `Microsoft.DSC/Import` importer resource resolves instances from an external
73+
configuration document, enabling you to compose configurations from multiple files.
74+
6175
### Nested resource instances
6276

63-
The resource instances declared in both adapter and group resources are called _nested resource
64-
instances_. For nested instances, a resource instance is _adjacent_ if it's declared in the same
65-
group or adapter instance. A resource instance is _external_ to a nested instance if it's declared
66-
outside of the group or adapter instance, or nested inside an adjacent group or adapter instance.
77+
The resource instances declared in adapter and group resources or resolved by importer resources
78+
are called _nested resource instances_.
79+
80+
For nested instances, a resource instance is _adjacent_ if:
81+
82+
- It's declared in the same group or adapter instance.
83+
- It's resolved by the same importer instance.
84+
85+
A resource instance is _external_ to a nested instance if:
86+
87+
- It's declared outside of the group or adapter instance
88+
- It's resolved by a different importer instance
89+
- It's nested inside an adjacent group, adapter, or importer instance.
90+
6791
For top-level instances, other instances at the top-level are adjacent. All other instances are
6892
external.
6993

@@ -122,14 +146,14 @@ Nested resource instances have limitations for the [dependsOn][03] property and
122146
[reference()][04] configuration function.
123147

124148
1. You can only reference adjacent instances. You can't reference a nested instance from outside of
125-
the group or adapter that declares it. You can't use a reference to a resource outside of the
126-
group or adapter resource for a nested instance.
149+
the instance that declares or resolves it. You can't use a reference to a resource outside of the
150+
group, adapter, or importer resource for a nested instance.
127151
1. You can only use the `dependsOn` property for adjacent instances. You must add a dependency on
128-
the group or adapter instance, not a nested instance of the group or adapter. Nested instances
129-
can't depend on external instances.
152+
the group, adapter, or importer instance, not a nested instance. Nested instances can't depend
153+
on external instances.
130154

131155
The following examples show valid and invalid references and dependencies. The examples use the
132-
`Microsoft.DSC/Group` resource, but the functionality is the same for adapter resources.
156+
`Microsoft.DSC/Group` resource, but the functionality is the same for adapter and import resources.
133157

134158
#### Example 1 - Valid references and dependencies
135159

@@ -357,5 +381,7 @@ resources:
357381

358382
[01]: ../resource/manifest/adapter.md
359383
[02]: ../resource/manifest/validate.md
384+
[aa]: ../resource/manifest/root.md#kind
360385
[03]: ../config/resource.md#dependson
386+
[ab]: ../resource/manifest/resolve.md
361387
[04]: ../config/functions/reference.md

‎docs/reference/schemas/outputs/config/get.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ The metadata under this property describes the context of the overall operation:
5555
`Set`, `Test`, or `Export`.
5656
- [executionType][03] defines whether DSC actually applied an operation to the configuration or was
5757
run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export`
58-
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf`
58+
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if`
5959
argument.
6060
- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp
6161
following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like

‎docs/reference/schemas/outputs/config/set.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ The metadata under this property describes the context of the overall operation:
5656
`Set`, `Test`, or `Export`.
5757
- [executionType][03] defines whether DSC actually applied an operation to the configuration or was
5858
run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export`
59-
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf`
59+
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if`
6060
argument.
6161
- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp
6262
following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like

‎docs/reference/schemas/outputs/config/test.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ The metadata under this property describes the context of the overall operation:
5656
`Set`, `Test`, or `Export`.
5757
- [executionType][03] defines whether DSC actually applied an operation to the configuration or was
5858
run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export`
59-
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf`
59+
operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if`
6060
argument.
6161
- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp
6262
following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like

‎docs/reference/schemas/outputs/resource/list.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,10 @@ The following list describes the available capabilities for a resource:
124124
resource. A resource has this capability when it defines the [export][17] property in its resource
125125
manifest. Only resources with this capability are usable with the [dsc resource export][18] and
126126
[dsc config export][19] commands.
127+
- <a id="capability-resolve" /> `Resolve` - The resource supports resolving nested resource
128+
instances from an external source. A resource has this capability when it defines the
129+
[resolve][20] property in its resource manifest. This functionality is primarily used by
130+
[importer resources][21].
127131

128132
```yaml
129133
Type: array
@@ -211,7 +215,7 @@ Required: true
211215

212216
Represents the values defined in the resource's manifest. This value is `null` for resources that
213217
aren't command-based. For more information on the value for this property, see
214-
[Command-based DSC Resource manifest schema reference][20].
218+
[Command-based DSC Resource manifest schema reference][22].
215219

216220
```yaml
217221
Type: [object, 'null']
@@ -238,4 +242,6 @@ Required: true
238242
[17]: ../../resource/manifest/export.md
239243
[18]: ../../../cli/resource/export.md
240244
[19]: ../../../cli/config/export.md
241-
[20]: ../../resource/manifest/root.md
245+
[20]: ../../resource/manifest/resolve.md
246+
[21]: ../../definitions/resourceKind.md#importer-resources
247+
[22]: ../../resource/manifest/root.md

‎docs/reference/schemas/resource/manifest/resolve.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
description: JSON schema reference for the 'resolve' property in a DSC Resource manifest
3+
ms.date: 01/17/2024
4+
ms.topic: reference
5+
title: DSC Resource manifest resolve property schema reference
6+
---
7+
8+
# DSC Resource manifest resolve property schema reference
9+
10+
## Synopsis
11+
12+
Indicates how to call the resource to resolve a nested configuration document from an external
13+
source.
14+
15+
## Metadata
16+
17+
```yaml
18+
SchemaDialect: https://json-schema.org/draft/2020-12/schema
19+
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json
20+
Type: object
21+
```
22+
23+
## Description
24+
25+
Defines how DSC must call the DSC Resource to resolve an external source to nested DSC
26+
Configuration Document. Define this method for [importer resources][01] and set the [kind][02]
27+
property in the manifest root to `Import`.
28+
29+
DSC sends data to the command in three ways:
30+
31+
1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed
32+
JSON object without spaces or newlines between the object properties.
33+
1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment
34+
variable for each property in the input data object, using the name and value of the property.
35+
1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string
36+
representing the data as a compressed JSON object to the specified argument.
37+
38+
If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the
39+
input JSON to the resource. You can only define one JSON input argument for a command.
40+
41+
You must define the `input` property, one JSON input argument in the `args` property array, or
42+
both.
43+
44+
## Required properties
45+
46+
The `resolve` definition must include these properties:
47+
48+
- [executable](#executable)
49+
50+
## Properties
51+
52+
### executable
53+
54+
The `executable` property defines the name of the command to run. The value must be the name of a
55+
command discoverable in the system's `PATH` environment variable or the full path to the command. A
56+
file extension is only required when the command isn't recognizable by the operating system as an
57+
executable.
58+
59+
```yaml
60+
Type: string
61+
Required: true
62+
```
63+
64+
### args
65+
66+
The `args` property defines the list of arguments to pass to the command. The arguments can be any
67+
number of strings. If you want to pass the JSON object representing the property bag for the
68+
resource to an argument, you can define a single item in the array as a [JSON object], indicating the
69+
name of the argument with the `jsonInputArg` string property and whether the argument is mandatory
70+
for the command with the `mandatory` boolean property.
71+
72+
```yaml
73+
Type: array
74+
Required: false
75+
Default: []
76+
Type: [string, object(JSON Input Argument)]
77+
```
78+
79+
#### String arguments
80+
81+
Any item in the argument array can be a string representing a static argument to pass to the
82+
command, like `config` or `--format`.
83+
84+
```yaml
85+
Type: string
86+
```
87+
88+
#### JSON input argument
89+
90+
Defines an argument for the command that accepts the JSON input object as a string. DSC passes the
91+
JSON input to the named argument when available. A JSON input argument is defined as a JSON object
92+
with the following properties:
93+
94+
- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`.
95+
- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command,
96+
even when there's no JSON input for the command. In that case, DSC passes an empty string to the
97+
JSON input argument.
98+
99+
You can only define one JSON input argument per arguments array.
100+
101+
If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both
102+
ways:
103+
104+
- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for
105+
each property in the JSON input and passes the JSON input object as a string to the defined
106+
argument.
107+
- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin
108+
and as a string to the defined argument.
109+
- If you define a JSON input argument without defining the `input` property, DSC only passes the
110+
JSON input as a string to the defined argument.
111+
112+
If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the
113+
input JSON to the resource. This makes the manifest invalid. You must define the `input` property,
114+
a JSON input argument in the `args` property array, or both.
115+
116+
```yaml
117+
Type: object
118+
RequiredProperties: [jsonInputArg]
119+
```
120+
121+
### input
122+
123+
The `input` property defines how to pass input to the resource. If this property isn't defined and
124+
the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any
125+
input to the resource when invoking the `resolve` operation.
126+
127+
The value of this property must be one of the following strings:
128+
129+
- `env` - Indicates that the resource expects the properties of an instance to be specified as
130+
environment variables with the same names and casing.
131+
132+
This option only supports the following data types for instance properties:
133+
134+
- `boolean`
135+
- `integer`
136+
- `number`
137+
- `string`
138+
- `array` of `integer` values
139+
- `array` of `number` values
140+
- `array` of `string` values
141+
142+
For non-array values, DSC sets the environment variable to the specified value as-is. When the
143+
data type is an array of values, DSC sets the environment variable as a comma-delimited string.
144+
For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment
145+
variable as `"1,2,3"`.
146+
147+
If the resource needs to support complex properties with an `object` value or multi-type arrays,
148+
set this to `stdin` instead.
149+
- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`.
150+
The JSON must adhere to the instance schema for the resource.
151+
152+
```yaml
153+
Type: string
154+
Required: false
155+
ValidValues: [env, stdin]
156+
```
157+
158+
<!-- Link reference definitions -->
159+
[01]: ../../definitions/resourceKind.md#importer-resources
160+
[02]: ./root.md#kind

‎docs/reference/schemas/resource/manifest/root.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,7 @@ DSC interprets exit code `0` as a successful operation and any other exit code a
277277
```yaml
278278
Type: object
279279
Required: false
280-
PropertyNamePattern: ^[0-9]+#
280+
PropertyNamePattern: ^-?[0-9]+#
281281
PropertyValueType: string
282282
```
283283

‎schemas/2024/04/bundled/outputs/resource/list.json

+117-5
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@
2626
"SetHandlesExist",
2727
"Test",
2828
"Delete",
29-
"Export"
29+
"Export",
30+
"Resolve"
3031
]
3132
}
3233
},
@@ -125,7 +126,8 @@
125126
"enum": [
126127
"Resource",
127128
"Adapter",
128-
"Group"
129+
"Group",
130+
"Import"
129131
]
130132
},
131133
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json": {
@@ -146,8 +148,7 @@
146148
"required": [
147149
"$schema",
148150
"type",
149-
"version",
150-
"get"
151+
"version"
151152
],
152153
"properties": {
153154
"$schema": {
@@ -211,6 +212,9 @@
211212
"validate": {
212213
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json"
213214
},
215+
"resolve": {
216+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json"
217+
},
214218
"adapter": {
215219
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json"
216220
},
@@ -244,7 +248,48 @@
244248
"schema": {
245249
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json"
246250
}
247-
}
251+
},
252+
"allOf": [
253+
{
254+
"if": {
255+
"properties": {
256+
"kind": {
257+
"const": "Adapter"
258+
}
259+
},
260+
"required": [
261+
"kind"
262+
]
263+
},
264+
"then": {
265+
"required": [
266+
"adapter"
267+
]
268+
}
269+
},
270+
{
271+
"if": {
272+
"properties": {
273+
"kind": {
274+
"const": "Import"
275+
}
276+
},
277+
"required": [
278+
"kind"
279+
]
280+
},
281+
"then": {
282+
"required": [
283+
"resolve"
284+
]
285+
},
286+
"else": {
287+
"required": [
288+
"get"
289+
]
290+
}
291+
}
292+
]
248293
},
249294
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json": {
250295
"$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -669,6 +714,73 @@
669714
}
670715
]
671716
},
717+
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json": {
718+
"$schema": "https://json-schema.org/draft/2020-12/schema",
719+
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json",
720+
"title": "Resolve method",
721+
"description": "Defines how DSC must call the DSC Resource to resolve a nested configuration document from an external source. Define this method for importer resources where the resource kind is set to `Import`.",
722+
"type": "object",
723+
"required": [
724+
"executable"
725+
],
726+
"properties": {
727+
"executable": {
728+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
729+
},
730+
"args": {
731+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
732+
},
733+
"input": {
734+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
735+
}
736+
},
737+
"oneOf": [
738+
{
739+
"required": [
740+
"input"
741+
],
742+
"not": {
743+
"properties": {
744+
"args": {
745+
"contains": {
746+
"type": "object"
747+
}
748+
}
749+
}
750+
}
751+
},
752+
{
753+
"not": {
754+
"required": [
755+
"input"
756+
]
757+
},
758+
"properties": {
759+
"args": {
760+
"contains": {
761+
"type": "object"
762+
},
763+
"minContains": 1,
764+
"maxContains": 1
765+
}
766+
}
767+
},
768+
{
769+
"required": [
770+
"input"
771+
],
772+
"properties": {
773+
"args": {
774+
"contains": {
775+
"type": "object"
776+
},
777+
"minContains": 1,
778+
"maxContains": 1
779+
}
780+
}
781+
}
782+
]
783+
},
672784
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json": {
673785
"$schema": "https://json-schema.org/draft/2020-12/schema",
674786
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json",

‎schemas/2024/04/bundled/outputs/resource/list.vscode.json

+194-10
Large diffs are not rendered by default.

‎schemas/2024/04/bundled/resource/manifest.json

+114-3
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
"required": [
88
"$schema",
99
"type",
10-
"version",
11-
"get"
10+
"version"
1211
],
1312
"properties": {
1413
"$schema": {
@@ -72,6 +71,9 @@
7271
"validate": {
7372
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json"
7473
},
74+
"resolve": {
75+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json"
76+
},
7577
"adapter": {
7678
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json"
7779
},
@@ -106,6 +108,47 @@
106108
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json"
107109
}
108110
},
111+
"allOf": [
112+
{
113+
"if": {
114+
"properties": {
115+
"kind": {
116+
"const": "Adapter"
117+
}
118+
},
119+
"required": [
120+
"kind"
121+
]
122+
},
123+
"then": {
124+
"required": [
125+
"adapter"
126+
]
127+
}
128+
},
129+
{
130+
"if": {
131+
"properties": {
132+
"kind": {
133+
"const": "Import"
134+
}
135+
},
136+
"required": [
137+
"kind"
138+
]
139+
},
140+
"then": {
141+
"required": [
142+
"resolve"
143+
]
144+
},
145+
"else": {
146+
"required": [
147+
"get"
148+
]
149+
}
150+
}
151+
],
109152
"$defs": {
110153
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": {
111154
"$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -133,7 +176,8 @@
133176
"enum": [
134177
"Resource",
135178
"Adapter",
136-
"Group"
179+
"Group",
180+
"Import"
137181
]
138182
},
139183
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json": {
@@ -559,6 +603,73 @@
559603
}
560604
]
561605
},
606+
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json": {
607+
"$schema": "https://json-schema.org/draft/2020-12/schema",
608+
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json",
609+
"title": "Resolve method",
610+
"description": "Defines how DSC must call the DSC Resource to resolve a nested configuration document from an external source. Define this method for importer resources where the resource kind is set to `Import`.",
611+
"type": "object",
612+
"required": [
613+
"executable"
614+
],
615+
"properties": {
616+
"executable": {
617+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
618+
},
619+
"args": {
620+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
621+
},
622+
"input": {
623+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
624+
}
625+
},
626+
"oneOf": [
627+
{
628+
"required": [
629+
"input"
630+
],
631+
"not": {
632+
"properties": {
633+
"args": {
634+
"contains": {
635+
"type": "object"
636+
}
637+
}
638+
}
639+
}
640+
},
641+
{
642+
"not": {
643+
"required": [
644+
"input"
645+
]
646+
},
647+
"properties": {
648+
"args": {
649+
"contains": {
650+
"type": "object"
651+
},
652+
"minContains": 1,
653+
"maxContains": 1
654+
}
655+
}
656+
},
657+
{
658+
"required": [
659+
"input"
660+
],
661+
"properties": {
662+
"args": {
663+
"contains": {
664+
"type": "object"
665+
},
666+
"minContains": 1,
667+
"maxContains": 1
668+
}
669+
}
670+
}
671+
]
672+
},
562673
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json": {
563674
"$schema": "https://json-schema.org/draft/2020-12/schema",
564675
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json",

‎schemas/2024/04/bundled/resource/manifest.vscode.json

+191-8
Large diffs are not rendered by default.

‎schemas/2024/04/definitions/resourceKind.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
"enum": [
88
"Resource",
99
"Adapter",
10-
"Group"
10+
"Group",
11+
"Import"
1112
]
1213
}

‎schemas/2024/04/outputs/resource/list.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@
2626
"SetHandlesExist",
2727
"Test",
2828
"Delete",
29-
"Export"
29+
"Export",
30+
"Resolve"
3031
]
3132
}
3233
},

‎schemas/2024/04/resource/manifest.json

+46-3
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
"required": [
88
"$schema",
99
"type",
10-
"version",
11-
"get"
10+
"version"
1211
],
1312
"properties": {
1413
"$schema": {
@@ -72,6 +71,9 @@
7271
"validate": {
7372
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json"
7473
},
74+
"resolve": {
75+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json"
76+
},
7577
"adapter": {
7678
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json"
7779
},
@@ -105,5 +107,46 @@
105107
"schema": {
106108
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json"
107109
}
108-
}
110+
},
111+
"allOf": [
112+
{
113+
"if": {
114+
"properties": {
115+
"kind": {
116+
"const": "Adapter"
117+
}
118+
},
119+
"required": [
120+
"kind"
121+
]
122+
},
123+
"then": {
124+
"required": [
125+
"adapter"
126+
]
127+
}
128+
},
129+
{
130+
"if": {
131+
"properties": {
132+
"kind": {
133+
"const": "Import"
134+
}
135+
},
136+
"required": [
137+
"kind"
138+
]
139+
},
140+
"then": {
141+
"required": [
142+
"resolve"
143+
]
144+
},
145+
"else": {
146+
"required": [
147+
"get"
148+
]
149+
}
150+
}
151+
]
109152
}

‎schemas/2024/04/resource/manifest.resolve.json

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json",
4+
"title": "Resolve method",
5+
"description": "Defines how DSC must call the DSC Resource to resolve a nested configuration document from an external source. Define this method for importer resources where the resource kind is set to `Import`.",
6+
"type": "object",
7+
"required": [
8+
"executable"
9+
],
10+
"properties": {
11+
"executable": {
12+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
13+
},
14+
"args": {
15+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
16+
},
17+
"input": {
18+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
19+
}
20+
},
21+
"oneOf": [
22+
{
23+
"required": [
24+
"input"
25+
],
26+
"not": {
27+
"properties": {
28+
"args": {
29+
"contains": {
30+
"type": "object"
31+
}
32+
}
33+
}
34+
}
35+
},
36+
{
37+
"not": {
38+
"required": [
39+
"input"
40+
]
41+
},
42+
"properties": {
43+
"args": {
44+
"contains": {
45+
"type": "object"
46+
},
47+
"minContains": 1,
48+
"maxContains": 1
49+
}
50+
}
51+
},
52+
{
53+
"required": [
54+
"input"
55+
],
56+
"properties": {
57+
"args": {
58+
"contains": {
59+
"type": "object"
60+
},
61+
"minContains": 1,
62+
"maxContains": 1
63+
}
64+
}
65+
}
66+
]
67+
}

‎schemas/src/definitions/resourceKind.yaml

+7
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ enum:
1212
- Resource
1313
- Adapter
1414
- Group
15+
- Import
1516

1617
# VS Code only
1718

@@ -46,3 +47,9 @@ markdownEnumDescriptions:
4647
4748
Indicates that the manifest is for a group resource that processes an array of nested
4849
resource instances.
50+
- | # Import
51+
<!-- force a line break -->
52+
53+
Indicates that the manifest is for an import resource that resolves an external source to DSC
54+
resource instances. The resolved instances are processed as nested instances for the import
55+
resource.

‎schemas/src/outputs/resource/list.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ properties:
3737
- Test
3838
- Delete
3939
- Export
40+
- Resolve
4041
description:
4142
title: Resource Description
4243
description: >-

‎schemas/src/resource/manifest.resolve.yaml

+203
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
2+
$schema: https://json-schema.org/draft/2020-12/schema
3+
$id: <HOST>/<PREFIX>/<VERSION>/resource/manifest.resolve.yaml
4+
5+
title: Resolve method
6+
description: >-
7+
Defines how DSC must call the DSC Resource to resolve a nested configuration document from an
8+
external source. Define this method for importer resources where the resource kind is set to
9+
`Import`.
10+
11+
markdownDescription: | # VS Code only
12+
***
13+
[_Online Documentation_][01]
14+
***
15+
16+
Defines how DSC must call the DSC Resource to resolve an external source to nested DSC
17+
Configuration Document. Define this method for [importer resources][02] and set the [kind][03]
18+
property in the manifest root to `Import`.
19+
20+
DSC sends data to the command in three ways:
21+
22+
1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed
23+
JSON object without spaces or newlines between the object properties.
24+
1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment
25+
variable for each property in the input data object, using the name and value of the property.
26+
1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string
27+
representing the data as a compressed JSON object to the specified argument.
28+
29+
If you don't define the `input` property and don't define a JSON input argument, DSC can't pass
30+
the input JSON to the resource. You can only define one JSON input argument for a command.
31+
32+
You must define the `input` property, one JSON input argument in the `args` property array, or
33+
both.
34+
35+
[01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>
36+
[02]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceKind?<DOCS_VERSION_PIN>#importer-resources
37+
[03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/root?<DOCS_VERSION_PIN>#kind
38+
39+
type: object
40+
required:
41+
- executable
42+
properties:
43+
executable:
44+
$ref: /<PREFIX>/<VERSION>/definitions/commandExecutable.yaml
45+
markdownDescription: |
46+
***
47+
[_Online Documentation_][01]
48+
***
49+
50+
Defines the name of the command to run. The value must be the name of a command discoverable
51+
in the system's `PATH` environment variable or the full path to the command. A file extension
52+
is only required when the command isn't recognizable by the operating system as an
53+
executable.
54+
55+
[01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>#executable
56+
args:
57+
$ref: /<PREFIX>/<VERSION>/definitions/commandArgs.yaml
58+
markdownDescription: |
59+
***
60+
[_Online Documentation_][01]
61+
***
62+
63+
Defines an array of strings to pass as arguments to the command. DSC passes the arguments to
64+
the command in the order they're specified.
65+
66+
For example, the given the following definition:
67+
68+
```json
69+
{
70+
"executable": "myresource",
71+
"args": ["config", "resolve"]
72+
}
73+
```
74+
75+
DSC invokes the command for the resource as:
76+
77+
```bash
78+
myresource config resolve
79+
```
80+
81+
If you want to pass the JSON object representing the property bag for a resource instance to
82+
an argument, you can define a single item in the array as a JSON object. Indicate the name of
83+
the argument with the `jsonInputArg` string property and whether the argument is mandatory
84+
for the command with the `mandatory` boolean property.` When the `mandatory` property is
85+
defined as `true`, DSC passes an empty string to the argument when no JSON input is
86+
available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass
87+
the argument at all when no JSON input is available. The default value for the `mandatory`
88+
property is `false`.
89+
90+
For example, given the following definition:
91+
92+
```json
93+
{
94+
"executable": "myresource"
95+
"args": [
96+
"config",
97+
"resolve",
98+
{ "jsonInputArg": "--properties" }
99+
]
100+
}
101+
```
102+
103+
DSC invokes the command for the resource as:
104+
105+
```bash
106+
myresource config resolve --properties <JSON string of instance properties>
107+
```
108+
109+
[01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>#args
110+
input:
111+
$ref: /<PREFIX>/<VERSION>/definitions/inputKind.yaml
112+
markdownDescription: |
113+
***
114+
[_Online Documentation_][01]
115+
***
116+
117+
Defines how DSC should pass input to the command, either as environment variables or JSON
118+
over `stdin`. This property is optional when you define an object in the `args` list. If
119+
you define a JSON input argument and an `input`, DSC sends the JSON data both ways:
120+
121+
- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable
122+
for each property in the JSON input and passes the JSON input object as a string to the
123+
defined argument.
124+
- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over
125+
stdin and as a string to the defined argument.
126+
- If you define a JSON input argument without defining the `input` property, DSC only passes
127+
the JSON input as a string to the defined argument.
128+
129+
If you don't define the `input` property and don't define a JSON input argument, DSC can't
130+
pass the input JSON to the resource. This makes the manifest invalid. You must define the
131+
`input` property, a JSON input argument in the `args` property array, or both.
132+
133+
[01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>#input
134+
135+
# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand
136+
# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when
137+
# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to
138+
# support 2019-09 and later, we can simplify this to two schemas.
139+
#
140+
# We use long lines for error messages, which can't use Markdown.
141+
oneOf:
142+
- # Resolve command with explicit input kind - when `input` is defined and `args` is only strings.
143+
# This subschema never triggers an error in testing.
144+
required: [input]
145+
not:
146+
properties: { args: { contains: { type: object } } }
147+
- # Resolve command with JSON input argument - when `input` isn't defined and `args` doesn't include
148+
# a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more
149+
# than one.
150+
not: { required: [input] }
151+
properties:
152+
args:
153+
errorMessage: |-
154+
The `resolve` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.
155+
156+
You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:
157+
158+
<DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>
159+
contains: { type: object }
160+
minContains: 1
161+
maxContains: 1
162+
- # Resolve command with explicit input kind and JSON input argument - when `input` is defined and
163+
# args includes a JSON input argument. Only raises an error when `input` is defined and `args`
164+
# contains more than one JSON input argument.
165+
required: [input]
166+
properties:
167+
args:
168+
errorMessage: |-
169+
You can only specify one JSON input argument for the `resolve` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.
170+
171+
For more information, see:
172+
173+
<DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>
174+
contains: { type: object }
175+
minContains: 1
176+
maxContains: 1
177+
178+
defaultSnippets: # VS Code only
179+
- label: ' Define without arguments'
180+
markdownDescription: |
181+
Define the `resolve` command for the resource when no arguments are required and the JSON
182+
input is sent over stdin or as environment variables.
183+
body:
184+
input: ${1|stdin,env|}
185+
executable: ${2:executable_name}
186+
- label: ' Define with string arguments'
187+
markdownDescription: |-
188+
Define the `resolve` command for the resource when at least one argument is required and the
189+
JSON input is sent over stdin or as environment variables.
190+
body:
191+
input: ${1|stdin,env|}
192+
executable: ${2:executable_name}
193+
args:
194+
- ${3:--first-argument}
195+
- label: ' Define with a JSON input argument'
196+
markdownDescription: |-
197+
Define the `resolve` command for the resource where the JSON input is passed as a one-line
198+
JSON object string to the specified argument.
199+
body:
200+
executable: ${1:executable_name}
201+
args:
202+
- jsonInputArg: ${2:argument_name}
203+
mandatory: ^$3

‎schemas/src/resource/manifest.yaml

+58-17
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@ defaultSnippets:
3030
- Relies on DSC's synthetic testing to determine whether an instance is in the desired state
3131
- Defines an embedded JSON schema.
3232
body:
33-
$schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
34-
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
35-
version: '${3:0.1.0}'
36-
description: ${4:Synopsis for the resource's purpose}
33+
${escape_dollar:$}schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
34+
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
35+
version: '${3:0.1.0}'
36+
description: ${4:Synopsis for the resource's purpose}
3737
get:
3838
executable: ${5:executable name}
3939
args: ['${6:argument}']
@@ -58,10 +58,10 @@ defaultSnippets:
5858
markdownDescription: |-
5959
Defines a group resource that expects a list of resource instances and operates on them.
6060
body:
61-
$schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
62-
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
63-
version: '${3:0.1.0}'
64-
description: ${4:Synopsis for the resource's purpose}
61+
${escape_dollar:$}schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
62+
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
63+
version: '${3:0.1.0}'
64+
description: ${4:Synopsis for the resource's purpose}
6565
get:
6666
executable: ${5:executable name}
6767
args: ['${6:argument}']
@@ -98,10 +98,10 @@ defaultSnippets:
9898
Defines an adapter resource that enables users to define non-command-based DSC Resources in
9999
the configuration.
100100
body:
101-
$schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
102-
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
103-
version: '${3:0.1.0}'
104-
description: ${4:Synopsis for the resource's purpose}
101+
${escape_dollar:$}schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
102+
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
103+
version: '${3:0.1.0}'
104+
description: ${4:Synopsis for the resource's purpose}
105105
get:
106106
executable: ${5:executable name}
107107
args: ['${6:argument}']
@@ -138,16 +138,40 @@ defaultSnippets:
138138
description: ${28:explanation of property purpose and usage}
139139
type: ${29|string,integer,number,array,object,null|}
140140

141+
- label: ' Define a resource (importer)'
142+
markdownDescription: |-
143+
Defines an importer resource that can resolve an external source to nested resource
144+
instances.
145+
body:
146+
${escape_dollar:$}schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
147+
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
148+
kind: Import
149+
version: '${3:0.1.0}'
150+
description: ${4:Synopsis for the resource's purpose}
151+
resolve:
152+
executable: ${5:executable name}
153+
args: ['${6:argument}']
154+
input: ${7:stdin}
155+
schema:
156+
embedded:
157+
${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}
158+
type: object
159+
properties:
160+
${14:name}:
161+
title: ${15:property title}
162+
description: ${16:explanation of property purpose and usage}
163+
type: ${17|string,integer,number,array,object,null|}
164+
141165
- label: ' Define a resource (assertion-only)'
142166
markdownDescription: |-
143167
Defines an assertion resource that can get the current state of an instance but not configure
144168
it. By default, the resource relies on DSC's synthetic testing feature. If the resource
145169
implements the `test` operation itself, define the `test` property.
146170
body:
147-
$schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
148-
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
149-
version: '${3:0.1.0}'
150-
description: ${4:Synopsis for the resource's purpose}
171+
${escape_dollar:$}schema: <HOST>/<PREFIX>/<VERSION>/bundled/resource/manifest.yaml
172+
type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}'
173+
version: '${3:0.1.0}'
174+
description: ${4:Synopsis for the resource's purpose}
151175
get:
152176
executable: ${5:executable name}
153177
args: ['${6:argument}']
@@ -167,7 +191,6 @@ required:
167191
- $schema
168192
- type
169193
- version
170-
- get
171194
properties:
172195
$schema:
173196
title: Manifest Schema
@@ -430,6 +453,8 @@ properties:
430453
$ref: /<PREFIX>/<VERSION>/resource/manifest.export.yaml
431454
validate:
432455
$ref: /<PREFIX>/<VERSION>/resource/manifest.validate.yaml
456+
resolve:
457+
$ref: /<PREFIX>/<VERSION>/resource/manifest.resolve.yaml
433458
adapter:
434459
$ref: /<PREFIX>/<VERSION>/resource/manifest.adapter.yaml
435460
exitCodes:
@@ -488,3 +513,19 @@ properties:
488513
${3:second exit code number}: ${4:second exit code meaning}
489514
schema:
490515
$ref: /<PREFIX>/<VERSION>/resource/manifest.schema.yaml
516+
517+
allOf:
518+
# Adapter resources must define the adapter command
519+
- if:
520+
properties: { kind: { const: Adapter } }
521+
required: [kind]
522+
then:
523+
required: [adapter]
524+
# Importer resources must define resolve, all others must define get
525+
- if:
526+
properties: { kind: { const: Import } }
527+
required: [kind]
528+
then:
529+
required: [resolve]
530+
else:
531+
required: [get]

0 commit comments

Comments
 (0)
Please sign in to comment.