|
| 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 |
0 commit comments