add resource support for what-if through additional parameter during config set

Author: tgauth

dsc/tests/dsc_whatif.tests.ps1

@@ -67,4 +67,40 @@ Describe 'whatif tests' {
         $result | Should -Match 'ERROR.*?Not implemented.*?what-if'
         $LASTEXITCODE | Should -Be 2
     }
+
+    It 'actual execution of WhatIf resource' {
+        $config_yaml = @"
+        `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
+        resources:
+        - name: WhatIf
+          type: Test/WhatIf
+          properties:
+            executionType: Actual
+"@
+        $result = $config_yaml | dsc config set | ConvertFrom-Json
+        $result.metadata.'Microsoft.DSC'.executionType | Should -BeExactly 'Actual'
+        $result.results.result.afterState.executionType | Should -BeExactly 'Actual'
+        $result.results.result.changedProperties | Should -Be $null
+        $result.hadErrors | Should -BeFalse
+        $result.results.Count | Should -Be 1
+        $LASTEXITCODE | Should -Be 0
+    }
+
+    It 'what-if execution of WhatIf resource' {
+        $config_yaml = @"
+        `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
+        resources:
+        - name: WhatIf
+          type: Test/WhatIf
+          properties:
+            executionType: Actual
+"@
+        $result = $config_yaml | dsc config set -w | ConvertFrom-Json
+        $result.metadata.'Microsoft.DSC'.executionType | Should -BeExactly 'WhatIf'
+        $result.results.result.afterState.executionType | Should -BeExactly 'WhatIf'
+        $result.results.result.changedProperties | Should -BeExactly 'executionType'
+        $result.hadErrors | Should -BeFalse
+        $result.results.Count | Should -Be 1
+        $LASTEXITCODE | Should -Be 0
+    }
 }

dsc_lib/src/dscresources/command_resource.rs

@@ -105,7 +105,7 @@ pub fn invoke_set(resource: &ResourceManifest, cwd: &str, desired: &str, skip_te
     if !skip_test && set.pre_test != Some(true) {
         info!("No pretest, invoking test {}", &resource.resource_type);
         let test_result = invoke_test(resource, cwd, desired)?;
-        if execution_type == &ExecutionKind::WhatIf {
+        if execution_type == &ExecutionKind::WhatIf && set.handles_what_if != Some(true) {
             return Ok(test_result.into());
         }
         let (in_desired_state, actual_state) = match test_result {
@@ -130,9 +130,8 @@ pub fn invoke_set(resource: &ResourceManifest, cwd: &str, desired: &str, skip_te
         }
     }
 
-    if ExecutionKind::WhatIf == *execution_type {
-        // TODO: continue execution when resources can implement what-if; only return an error here temporarily
-        return Err(DscError::NotImplemented("what-if not yet supported for resources that implement pre-test".to_string()));
+    if ExecutionKind::WhatIf == *execution_type && set.handles_what_if != Some(true) {
+        return Err(DscError::NotImplemented("cannot process what-if execution type, resource does not implement what-if or pre-test".to_string()));
     }
 
     let Some(get) = &resource.get else {
@@ -158,7 +157,16 @@ pub fn invoke_set(resource: &ResourceManifest, cwd: &str, desired: &str, skip_te
 
     let mut env: Option<HashMap<String, String>> = None;
     let mut input_desired: Option<&str> = None;
-    let args = process_args(&set.args, desired);
+    let mut args = process_args(&set.args, desired);
+    if ExecutionKind::WhatIf == *execution_type {
+        if let Some(mut arguments) = args {
+            arguments.push("--what-if".to_string());
+            args = Some(arguments);
+        }
+        else {
+            args = Some(vec!["--what-if".to_string()]);
+        }
+    }
     match &set.input {
         Some(InputKind::Env) => {
             env = Some(json_to_hashmap(desired)?);

dsc_lib/src/dscresources/dscresource.rs

@@ -50,6 +50,8 @@ pub enum Capability {
     Set,
     /// The resource supports the `_exist` property directly.
     SetHandlesExist,
+    /// The resource supports the `what-if` execution type directly.
+    SetHandlesWhatIf,
     /// The resource supports validating configuration.
     Test,
     /// The resource supports deleting configuration.

dsc_lib/src/dscresources/resource_manifest.rs

@@ -171,6 +171,9 @@ pub struct SetMethod {
     /// Indicates that the resource directly handles `_exist` as a property.
     #[serde(rename = "handlesExist", skip_serializing_if = "Option::is_none")]
     pub handles_exist: Option<bool>,
+    /// Indicates that the resource directly handles `what-if` execution type.
+    #[serde(rename = "handlesWhatIf", skip_serializing_if = "Option::is_none")]
+    pub handles_what_if: Option<bool>,
     /// The type of return value expected from the Set method.
     #[serde(rename = "return", skip_serializing_if = "Option::is_none")]
     pub returns: Option<ReturnKind>,

tools/dsctest/dscwhatif.dsc.resource.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json",
+    "type": "Test/WhatIf",
+    "version": "0.1.0",
+    "get": {
+        "executable": "dsctest",
+        "args": [
+            "what-if"
+        ]
+    },
+    "set": {
+        "executable": "dsctest",
+        "args": [
+            "what-if"
+        ],
+        "handlesWhatIf": true,
+        "implementsPretest": true,
+        "return": "state"
+    },
+    "schema": {
+        "command": {
+            "executable": "dsctest",
+            "args": [
+                "schema",
+                "-s",
+                "what-if"
+            ]
+        }
+    }
+}

tools/dsctest/src/args.rs

@@ -10,6 +10,7 @@ pub enum Schemas {
     Exist,
     Sleep,
     Trace,
+    WhatIf,
 }
 
 #[derive(Debug, Parser)]
@@ -54,4 +55,10 @@ pub enum SubCommand {
 
     #[clap(name = "trace", about = "The trace level")]
     Trace,
+
+    #[clap(name = "what-if", about = "Check if it is a what-if operation")]
+    WhatIf {
+        #[clap(name = "what-if", short, long, help = "The input to the what-if command as JSON")]
+        what_if: bool,
+    }
 }

tools/dsctest/src/main.rs

@@ -7,6 +7,7 @@ mod echo;
 mod exist;
 mod sleep;
 mod trace;
+mod whatif;
 
 use args::{Args, Schemas, SubCommand};
 use clap::Parser;
@@ -16,6 +17,7 @@ use crate::echo::Echo;
 use crate::exist::{Exist, State};
 use crate::sleep::Sleep;
 use crate::trace::Trace;
+use crate::whatif::WhatIf;
 use std::{thread, time::Duration};
 
 fn main() {
@@ -75,6 +77,9 @@ fn main() {
                 Schemas::Trace => {
                     schema_for!(Trace)
                 },
+                Schemas::WhatIf => {
+                    schema_for!(WhatIf)
+                },
             };
             serde_json::to_string(&schema).unwrap()
         },
@@ -100,6 +105,14 @@ fn main() {
             };
             serde_json::to_string(&trace).unwrap()
         },
+        SubCommand::WhatIf { what_if } => {
+            let result: WhatIf = if what_if {
+                WhatIf { execution_type: "WhatIf".to_string() }
+            } else {
+                WhatIf { execution_type: "Actual".to_string() }
+            };
+            serde_json::to_string(&result).unwrap()
+        },
     };
 
     println!("{json}");

tools/dsctest/src/whatif.rs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+// #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+// #[serde(untagged)]
+// pub enum ExecutionKind {
+//     #[serde(rename = "actual")]
+//     Actual,
+//     #[serde(rename = "whatIf")]
+//     WhatIf,
+// }
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct WhatIf {
+    #[serde(rename = "executionType")]
+    pub execution_type: String,
+}