add metadata to configuration result output

Author: Steve Lee (POWERSHELL HE/HIM) (from Dev Box)

dsc/tests/dsc_config_get.tests.ps1

@@ -41,7 +41,19 @@ Describe 'dsc config get tests' {
               properties:
                 output: hello
 "@
-        $null = $config_yaml | dsc config get --format pretty-json | Out-String
+        $result = $config_yaml | dsc config get --format pretty-json | ConvertFrom-Json
+        $result.hadErrors | Should -BeFalse
+        $result.results.Count | Should -Be 1
+        $result.results[0].Name | Should -Be 'Echo'
+        $result.results[0].type | Should -BeExactly 'Test/Echo'
+        $result.results[0].result.actualState.output | Should -Be 'hello'
+        $result.metadata.'Microsoft.DSC'.version | Should -BeLike '3.*'
+        $result.metadata.'Microsoft.DSC'.operation | Should -BeExactly 'Get'
+        $result.metadata.'Microsoft.DSC'.executionType | Should -BeExactly 'Actual'
+        $result.metadata.'Microsoft.DSC'.startDatetime | Should -Not -BeNullOrEmpty
+        $result.metadata.'Microsoft.DSC'.endDatetime | Should -Not -BeNullOrEmpty
+        $result.metadata.'Microsoft.DSC'.duration | Should -Not -BeNullOrEmpty
+        $result.metadata.'Microsoft.DSC'.securityContext | Should -BeExactly 'Restricted'
         $LASTEXITCODE | Should -Be 0
     }
 }

dsc/tests/dsc_config_set.tests.ps1

@@ -17,6 +17,8 @@ Describe 'dsc config set tests' {
 "@
         $out = $config_yaml | dsc config set | ConvertFrom-Json
         $LASTEXITCODE | Should -Be 0
+        $out.hadErrors | Should -BeFalse
+        $out.results.Count | Should -Be 2
         $out.results[0].type | Should -BeExactly 'Test/Exist'
         $out.results[0].result.beforeState._exist | Should -BeFalse
         $out.results[0].result.afterState.state | Should -BeExactly 'Absent'
@@ -26,5 +28,13 @@ Describe 'dsc config set tests' {
         $out.results[1].result.beforeState._exist | Should -BeFalse
         $out.results[1].result.afterState.deleteCalled | Should -BeTrue
         $out.results[1].result.afterState._exist | Should -BeFalse
+        $out.metadata.'Microsoft.DSC'.version | Should -BeLike '3.*'
+        $out.metadata.'Microsoft.DSC'.operation | Should -BeExactly 'Set'
+        $out.metadata.'Microsoft.DSC'.executionType | Should -BeExactly 'Actual'
+        $out.metadata.'Microsoft.DSC'.startDatetime | Should -Not -BeNullOrEmpty
+        $out.metadata.'Microsoft.DSC'.endDatetime | Should -Not -BeNullOrEmpty
+        $out.metadata.'Microsoft.DSC'.duration | Should -Not -BeNullOrEmpty
+        $out.metadata.'Microsoft.DSC'.securityContext | Should -BeExactly 'Restricted'
+
     }
 }

dsc/tests/dsc_export.tests.ps1

@@ -38,6 +38,7 @@ Describe 'resource export tests' {
         $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json'
         $config_with_process_list.'resources' | Should -Not -BeNullOrEmpty
         $config_with_process_list.resources.count | Should -BeGreaterThan 1
+        $config_with_process_list.metadata.'Microsoft.DSC'.operation | Should -BeExactly 'Export'
     }
 
     It 'Configuration Export can be piped to configuration Set' -Skip:(!$IsWindows) {

dsc_lib/Cargo.toml

@@ -5,7 +5,7 @@ edition = "2021"
 
 [dependencies]
 base64 = "0.22"
-chrono = "0.4.26"
+chrono = { version = "0.4.26" }
 derive_builder ="0.20"
 indicatif = { version = "0.17" }
 jsonschema = "0.17"

dsc_lib/src/configure/config_doc.rs

@@ -6,6 +6,8 @@ use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 use std::collections::HashMap;
 
+use super::config_result::ResultMetadata;
+
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 pub enum ContextKind {
     Configuration,
@@ -27,6 +29,13 @@ pub struct MicrosoftDscMetadata {
     pub required_security_context: Option<SecurityContextKind>,
 }
 
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+#[serde(untagged)]
+pub enum MicrosoftMetadata {
+    DscInput(Metadata),
+    DscResult(ResultMetadata),
+}
+
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 pub struct Metadata {
     #[serde(rename = "Microsoft.DSC", skip_serializing_if = "Option::is_none")]
@@ -45,7 +54,7 @@ pub struct Configuration {
     pub variables: Option<HashMap<String, Value>>,
     pub resources: Vec<Resource>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub metadata: Option<Metadata>,
+    pub metadata: Option<MicrosoftMetadata>,
 }
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]

dsc_lib/src/configure/config_result.rs

@@ -4,7 +4,9 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use crate::dscresources::invoke_result::{GetResult, SetResult, TestResult};
-use crate::configure::config_doc;
+use crate::configure::config_doc::Configuration;
+
+use super::config_doc::SecurityContextKind;
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 pub enum MessageLevel {
@@ -23,6 +25,41 @@ pub struct ResourceMessage {
     pub level: MessageLevel,
 }
 
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+pub enum Operation {
+    Get,
+    Set,
+    Test,
+    Export,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+pub enum ExecutionKind {
+    Actual,
+    WhatIf,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+pub struct ResultMetadata {
+    #[serde(rename = "Microsoft.DSC")]
+    pub microsoft: MicrosoftDscResultMetadata,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+pub struct MicrosoftDscResultMetadata {
+    pub version: String,
+    pub operation: Operation,
+    #[serde(rename = "executionType")]
+    pub execution_type: ExecutionKind,
+    #[serde(rename = "startDatetime")]
+    pub start_datetime: String,
+    #[serde(rename = "endDatetime")]
+    pub end_datetime: String,
+    pub duration: String,
+    #[serde(rename = "securityContext")]
+    pub security_context: SecurityContextKind,
+}
+
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ResourceGetResult {
@@ -45,6 +82,7 @@ impl From<ResourceTestResult> for ResourceGetResult {
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ConfigurationGetResult {
+    pub metadata: Option<ResultMetadata>,
     pub results: Vec<ResourceGetResult>,
     pub messages: Vec<ResourceMessage>,
     #[serde(rename = "hadErrors")]
@@ -55,6 +93,7 @@ impl ConfigurationGetResult {
     #[must_use]
     pub fn new() -> Self {
         Self {
+            metadata: None,
             results: Vec::new(),
             messages: Vec::new(),
             had_errors: false,
@@ -75,6 +114,7 @@ impl From<ConfigurationTestResult> for ConfigurationGetResult {
             results.push(result.into());
         }
         Self {
+            metadata: None,
             results,
             messages: test_result.messages,
             had_errors: test_result.had_errors,
@@ -115,6 +155,7 @@ impl Default for GroupResourceSetResult {
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ConfigurationSetResult {
+    pub metadata: Option<ResultMetadata>,
     pub results: Vec<ResourceSetResult>,
     pub messages: Vec<ResourceMessage>,
     #[serde(rename = "hadErrors")]
@@ -125,6 +166,7 @@ impl ConfigurationSetResult {
     #[must_use]
     pub fn new() -> Self {
         Self {
+            metadata: None,
             results: Vec::new(),
             messages: Vec::new(),
             had_errors: false,
@@ -171,6 +213,7 @@ impl Default for GroupResourceTestResult {
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ConfigurationTestResult {
+    pub metadata: Option<ResultMetadata>,
     pub results: Vec<ResourceTestResult>,
     pub messages: Vec<ResourceMessage>,
     #[serde(rename = "hadErrors")]
@@ -181,6 +224,7 @@ impl ConfigurationTestResult {
     #[must_use]
     pub fn new() -> Self {
         Self {
+            metadata: None,
             results: Vec::new(),
             messages: Vec::new(),
             had_errors: false,
@@ -197,7 +241,8 @@ impl Default for ConfigurationTestResult {
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ConfigurationExportResult {
-    pub result: Option<config_doc::Configuration>,
+    pub metadata: Option<ResultMetadata>,
+    pub result: Option<Configuration>,
     pub messages: Vec<ResourceMessage>,
     #[serde(rename = "hadErrors")]
     pub had_errors: bool,
@@ -207,6 +252,7 @@ impl ConfigurationExportResult {
     #[must_use]
     pub fn new() -> Self {
         Self {
+            metadata: None,
             result: None,
             messages: Vec::new(),
             had_errors: false,

dsc_lib/src/configure/context.rs

@@ -1,24 +1,37 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use chrono::{DateTime, Local};
+use crate::configure::ExecutionKind;
+use security_context_lib::{get_security_context, SecurityContext};
 use serde_json::Value;
 use std::collections::HashMap;
 
-use super::config_doc::DataType;
+use super::config_doc::{DataType, SecurityContextKind};
 
 pub struct Context {
+    pub execution_type: ExecutionKind,
+    pub outputs: HashMap<String, Value>, // this is used by the `reference()` function to retrieve output
     pub parameters: HashMap<String, (Value, DataType)>,
+    pub security_context: SecurityContextKind,
     _variables: HashMap<String, Value>,
-    pub outputs: HashMap<String, Value>, // this is used by the `reference()` function to retrieve output
+
+    pub start_datetime: DateTime<Local>,
 }
 
 impl Context {
     #[must_use]
     pub fn new() -> Self {
         Self {
+            execution_type: ExecutionKind::Actual,
+            outputs: HashMap::new(),
             parameters: HashMap::new(),
+            security_context: match get_security_context() {
+                SecurityContext::Admin => SecurityContextKind::Elevated,
+                SecurityContext::User => SecurityContextKind::Restricted,
+            },
             _variables: HashMap::new(),
-            outputs: HashMap::new(),
+            start_datetime: chrono::Local::now(),
         }
     }
 }

dsc_lib/src/configure/mod.rs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use crate::configure::config_doc::{MicrosoftMetadata, MicrosoftMetadata::DscInput};
 use crate::configure::parameters::Input;
 use crate::dscerror::DscError;
 use crate::dscresources::dscresource::get_diff;
@@ -11,17 +12,16 @@ use crate::DscResource;
 use crate::discovery::Discovery;
 use crate::parser::Statement;
 use self::context::Context;
-use self::config_doc::{Configuration, DataType, Metadata, SecurityContextKind};
+use self::config_doc::{Configuration, DataType, SecurityContextKind};
 use self::depends_on::get_resource_invocation_order;
-use self::config_result::{ConfigurationGetResult, ConfigurationSetResult, ConfigurationTestResult, ConfigurationExportResult};
+use self::config_result::{ConfigurationExportResult, ConfigurationGetResult, ConfigurationSetResult, ConfigurationTestResult, ExecutionKind, MicrosoftDscResultMetadata, Operation, ResultMetadata};
 use self::contraints::{check_length, check_number_limits, check_allowed_values};
 use indicatif::ProgressStyle;
 use security_context_lib::{SecurityContext, get_security_context};
 use serde_json::{Map, Value};
 use std::{collections::HashMap, mem};
 use tracing::{debug, info, trace, warn_span, Span};
 use tracing_indicatif::span_ext::IndicatifSpanExt;
-
 pub mod context;
 pub mod config_doc;
 pub mod config_result;
@@ -165,12 +165,12 @@ fn add_metadata(kind: &Kind, mut properties: Option<Map<String, Value>> ) -> Res
     Ok(serde_json::to_string(&properties)?)
 }
 
-fn check_security_context(metadata: &Option<Metadata>) -> Result<(), DscError> {
+fn check_security_context(metadata: &Option<MicrosoftMetadata>) -> Result<(), DscError> {
     if metadata.is_none() {
         return Ok(());
     }
 
-    if let Some(metadata) = &metadata {
+    if let Some(DscInput(metadata)) = &metadata {
         if let Some(microsoft_dsc) = &metadata.microsoft {
             if let Some(required_security_context) = &microsoft_dsc.required_security_context {
                 match required_security_context {
@@ -251,6 +251,9 @@ impl Configurator {
             result.results.push(resource_result);
         }
 
+        result.metadata = Some(
+            self.get_result_metadata(Operation::Get)
+        );
         std::mem::drop(pb_span_enter);
         std::mem::drop(pb_span);
         Ok(result)
@@ -343,6 +346,9 @@ impl Configurator {
             }
         }
 
+        result.metadata = Some(
+            self.get_result_metadata(Operation::Set)
+        );
         mem::drop(pb_span_enter);
         mem::drop(pb_span);
         Ok(result)
@@ -384,6 +390,9 @@ impl Configurator {
             result.results.push(resource_result);
         }
 
+        result.metadata = Some(
+            self.get_result_metadata(Operation::Test)
+        );
         std::mem::drop(pb_span_enter);
         std::mem::drop(pb_span);
         Ok(result)
@@ -423,9 +432,14 @@ impl Configurator {
             add_resource_export_results_to_configuration(dsc_resource, Some(dsc_resource), &mut conf, input.as_str())?;
         }
 
+        conf.metadata = Some(
+            MicrosoftMetadata::DscResult(
+                self.get_result_metadata(Operation::Export)
+            )
+        );
+        result.result = Some(conf);
         std::mem::drop(pb_span_enter);
         std::mem::drop(pb_span);
-        result.result = Some(conf);
         Ok(result)
     }
 
@@ -497,6 +511,21 @@ impl Configurator {
         Ok(())
     }
 
+    fn get_result_metadata(&self, operation: Operation) -> ResultMetadata {
+        let end_datetime = chrono::Local::now();
+        ResultMetadata {
+            microsoft: MicrosoftDscResultMetadata {
+                version: env!("CARGO_PKG_VERSION").to_string(),
+                operation,
+                execution_type: self.context.execution_type.clone(),
+                start_datetime: self.context.start_datetime.to_rfc3339(),
+                end_datetime: end_datetime.to_rfc3339(),
+                duration: end_datetime.signed_duration_since(self.context.start_datetime).to_string(),
+                security_context: self.context.security_context.clone(),
+            }
+        }
+    }
+
     fn validate_parameter_type(name: &str, value: &Value, parameter_type: &DataType) -> Result<(), DscError> {
         match parameter_type {
             DataType::String | DataType::SecureString => {