(SCHEMA) Update resource manifest schema source for whatIf

This change updates the schema source definitions for the
resource manifest and the `dsc resource list` output to
account for the new `whatIf` property and `WhatIf` resource
capability.

A future commit will regenerate the schemas.

Author: michaeltlombardi

schemas/src/outputs/resource/list.yaml

@@ -34,6 +34,7 @@ properties:
         - Get
         - Set
         - SetHandlesExist
+        - WhatIf
         - Test
         - Delete
         - Export

schemas/src/resource/manifest.whatIf.yaml

@@ -0,0 +1,280 @@
+# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
+$schema: https://json-schema.org/draft/2020-12/schema
+$id:     <HOST>/<PREFIX>/<VERSION>/resource/manifest.whatIf.yaml
+
+title: What-if method
+description: >-
+  Defines how DSC must call the DSC Resource to indicate whether and how the set command will
+  modify an instance and how to process the output from the DSC Resource.
+markdownDescription: | # VS Code only
+  ***
+  [_Online Documentation_][01]
+  ***
+
+  Defines how DSC must call the DSC Resource to indicate whether and how the set command will
+  modify an instance and how to process the output from the DSC Resource. If a resource doesn't
+  define this method in the manifest, DSC synthesizes this behavior by converting the result of
+  the test operation for the resource into the [set result][02].
+
+  This method definition has the same structure as the [set method][03] in the resource manifest.
+
+  DSC sends data to the command in three ways:
+
+  1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed
+     JSON object without spaces or newlines between the object properties.
+  1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment
+     variable for each property in the input data object, using the name and value of the property.
+  1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string
+     representing the data as a compressed JSON object to the specified 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.
+
+  You must define the `input` property, one JSON input argument in the `args` property array, or
+  both.
+
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/outputs/resource/set?<DOCS_VERSION_PIN>
+  [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
+
+type: object
+required:
+  - executable
+properties:
+  executable:
+    $ref: /<PREFIX>/<VERSION>/definitions/commandExecutable.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines the name of the command to run. The value must be the name of a command discoverable
+      in the system's `PATH` environment variable or the full path to the command. A file extension
+      is only required when the command isn't recognizable by the operating system as an
+      executable.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#executable
+  args:
+    $ref: /<PREFIX>/<VERSION>/definitions/commandArgs.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines an array of strings to pass as arguments to the command. DSC passes the arguments to
+      the command in the order they're specified.
+
+      For example, the given the following definition:
+
+      ```json
+      {
+        "executable": "myresource",
+        "args":       ["config", "set", "--what-if"],
+      }
+      ```
+
+      DSC invokes the command for the resource as:
+
+      ```bash
+      myresource config set --what-if
+      ```
+
+      If you want to pass the JSON object representing the property bag for a resource instance to
+      an argument, you can define a single item in the array as a JSON object. Indicate the name of
+      the argument with the `jsonInputArg` string property and whether the argument is mandatory
+      for the command with the `mandatory` boolean property.` When the `mandatory` property is
+      defined as `true`, DSC passes an empty string to the argument when no JSON input is
+      available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass
+      the argument at all when no JSON input is available. The default value for the `mandatory`
+      property is `false`.
+
+      For example, given the following definition:
+
+      ```json
+      {
+        "executable": "myresource"
+        "args":       [
+          "config",
+          "set",
+          "--what-if",
+          { "jsonInputArg": "--properties" }
+        ]
+      }
+      ```
+
+      DSC invokes the command for the resource as:
+
+      ```bash
+      myresource config set --what-if --properties <JSON string of instance properties>
+      ```
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#args
+  input:
+    $ref: /<PREFIX>/<VERSION>/definitions/inputKind.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines how DSC should pass input to the command, either as environment variables or JSON
+      over `stdin`. This property is optional when you define an object in the `args` list. If
+      you define a JSON input argument and an `input`, DSC sends the JSON data both ways:
+
+      - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable
+        for each property in the JSON input and passes the JSON input object as a string to the
+        defined argument.
+      - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over
+        stdin and as a string to the defined argument.
+      - If you define a JSON input argument without defining the `input` property, DSC only passes
+        the JSON input as a string to the defined 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. This makes the manifest invalid. You must define the
+      `input` property, a JSON input argument in the `args` property array, or both.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#input
+  implementsPretest:
+    title: Resource Performs Pre-Test
+    description: >-
+      Defines whether the DSC Resource performs its own test to ensure idempotency when calling the
+      `set --what-if` command. Set this value to `true` if the DSC Resource tests input before
+      processing how it will modify system state.
+    type: boolean
+    default: false
+    # VS Code only
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines whether the DSC Resource performs its own test to ensure idempotency when calling the
+      `set --what-if` command . Set this value to `true` if the DSC Resource tests input before
+      processing how it will modify system state.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#implementspretest
+  handlesExist:
+    title: Resource handles _exist property
+    description: >-
+      Defines whether the DSC Resource has its own built-in handling for the `_exist` common
+      property. Set this value to `true` if the DSC Resource handles instance deletion internally
+      when receiving a `set --what-if` command where the instance defines the `_exist` property as
+      `false`.
+    type: boolean
+    default: false
+    # VS Code only
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines whether the DSC Resource has its own built-in handling for the [`_exist`][02] common
+      property. Set this value to `true` if the DSC Resource handles instance deletion internally
+      when receiving a `set --what-if` command where the instance defines the `_exist` property as
+      `false`.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#handlesExist
+      [02]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
+  return:
+    description: >-
+      Defines whether the command returns a JSON blob of the DSC Resource's expected state after a
+      set operation in what-if mode or the state and an array of the properties the DSC Resource
+      would modify.
+    $ref: /<PREFIX>/<VERSION>/definitions/returnKind.yaml
+    # VS Code only
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines whether the command returns a JSON blob of the DSC Resource's expected state after a
+      set operation in what-if mode or the state and an array of the properties the DSC Resource
+      would modify.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>#return
+    markdownEnumDescriptions:
+      - | # state
+          _Final state only_
+
+          > Indicates that the resource returns only the instance's expected final state after the
+          > set operation as a JSON blob.
+      - | # stateAndDiff
+          _Final state and changed properties_
+
+          > Indicates that the resource returns the instance's expected final state and an array of
+          > property names that the resource would modify.
+
+# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand
+# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when
+# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to
+# support 2019-09 and later, we can simplify this to two schemas.
+#
+# We use long lines for error messages, which can't use Markdown.
+oneOf:
+  - # What-if command with explicit input kind - when `input` is defined and `args` is only strings.
+    # This subschema never triggers an error in testing.
+    required: [input]
+    not:
+      properties: { args: { contains: { type: object } } } 
+  - # What-if command with JSON input argument - when `input` isn't defined and `args` doesn't
+    # include a JSON input argument. Only raises an error when `args` has zero JSON input arguments
+    # or more than one.
+    not: { required: [input] }
+    properties:
+      args:
+        errorMessage: |-
+          The `whatIf` 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.
+
+          You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:
+
+          <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
+        contains:  { type: object }
+        minContains: 1
+        maxContains: 1
+  - # What-if command with explicit input kind and JSON input argument - when `input` is defined and
+    # args includes a JSON input argument. Only raises an error when `input` is defined and `args`
+    # contains more than one JSON input argument.
+    required: [input]
+    properties:
+      args:
+        errorMessage: |-
+          You can only specify one JSON input argument for the `whatIf` 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.
+
+          For more information, see:
+
+          <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
+        contains:  { type: object }
+        minContains: 1
+        maxContains: 1
+
+defaultSnippets: # VS Code only
+  - label: ' Define without arguments'
+    markdownDescription: |
+      Define the `whatIf` command for the resource when no arguments are required and the JSON
+      input is sent over stdin or as environment variables.
+    body:
+      input:              ${1|stdin,env|}
+      implementsPretest: ^${2|true,false|}
+      return:             ${3|state,stateAndDiff|}
+      executable:         ${4:executable_name}
+  - label: ' Define with string arguments'
+    markdownDescription: |-
+      Define the `whatIf` command for the resource when at least one argument is required and the
+      JSON input is sent over stdin or as environment variables.
+    body:
+      input:              ${1|stdin,env|}
+      implementsPretest: ^${2|true,false|}
+      return:             ${3|state,stateAndDiff|}
+      executable:         ${4:executable_name}
+      args:
+        - ${5:--first-argument}
+  - label: ' Define with a JSON input argument'
+    markdownDescription: |-
+      Define the `whatIf` command for the resource where the JSON input is passed as a one-line
+      JSON object string to the specified argument.
+    body:
+      implementsPretest: ^${1|true,false|}
+      return:             ${2|state,stateAndDiff|}
+      executable:         ${3:executable_name}
+      args:
+        - jsonInputArg:  ${4:argument_name}
+          mandatory:    ^$5

schemas/src/resource/manifest.yaml

@@ -445,6 +445,8 @@ properties:
     $ref: /<PREFIX>/<VERSION>/resource/manifest.get.yaml
   set:
     $ref: /<PREFIX>/<VERSION>/resource/manifest.set.yaml
+  whatIf:
+    $ref: /<PREFIX>/<VERSION>/resource/manifest.whatIf.yaml
   test:
     $ref: /<PREFIX>/<VERSION>/resource/manifest.test.yaml
   delete: