Enable resources to return _restartRequired metadata

SteveL-MSFT · SteveL-MSFT · commit 38a35b0d4748 · 2025-07-16T16:12:40.000-07:00
diff --git a/dsc/src/args.rs b/dsc/src/args.rs
@@ -289,4 +289,5 @@ pub enum SchemaType {
     ExtensionManifest,
     ExtensionDiscoverResult,
     FunctionDefinition,
+    RestartRequired
 }
diff --git a/dsc/src/util.rs b/dsc/src/util.rs
@@ -8,7 +8,10 @@ use dsc_lib::extensions::discover::DiscoverResult;
 use dsc_lib::extensions::extension_manifest::ExtensionManifest;
 use dsc_lib::{
     configure::{
-        config_doc::Configuration,
+        config_doc::{
+            Configuration,
+            RestartRequired,
+        },
         config_result::{
             ConfigurationGetResult,
             ConfigurationSetResult,
@@ -187,6 +190,9 @@ pub fn get_schema(schema: SchemaType) -> RootSchema {
         },
         SchemaType::FunctionDefinition => {
             schema_for!(FunctionDefinition)
+        },
+        SchemaType::RestartRequired => {
+            schema_for!(RestartRequired)
         }
     }
 }
diff --git a/dsc/tests/dsc_metadata.tests.ps1 b/dsc/tests/dsc_metadata.tests.ps1
@@ -71,4 +71,56 @@ Describe 'metadata tests' {
         $out.results[0].metadata.Microsoft.DSC | Should -BeNullOrEmpty
         (Get-Content $TestDrive/error.log) | Should -BeLike "*WARN*Resource returned '_metadata' property 'Microsoft.DSC' which is ignored*"
     }
+
+    It 'resource returning _restartRequired metadata is handled' {
+        $configYaml = @'
+        $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+        resources:
+          - name: one
+            type: Test/Metadata
+            properties:
+              _metadata:
+                _restartRequired:
+                  - system: mySystem
+                  - service: myService
+          - name: two
+            type: Test/Metadata
+            properties:
+              _metadata:
+                _restartRequired:
+                  - service: sshd
+          - name: three
+            type: Test/Metadata
+            properties:
+              _metadata:
+                _restartRequired:
+                  - process:
+                      name: myProcess
+                      id: 1234
+                  - process:
+                      name: anotherProcess
+                      id: 5678
+'@
+        $out = dsc config get -i $configYaml 2>$TestDrive/error.log | ConvertFrom-Json
+        $LASTEXITCODE | Should -Be 0
+        $out.results.count | Should -Be 3
+        $out.results[0].metadata._restartRequired.count | Should -Be 2
+        $out.results[0].metadata._restartRequired[0].system | Should -BeExactly 'mySystem'
+        $out.results[0].metadata._restartRequired[1].service | Should -BeExactly 'myService'
+        $out.results[1].metadata._restartRequired.count | Should -Be 1
+        $out.results[1].metadata._restartRequired[0].service | Should -BeExactly 'sshd'
+        $out.results[2].metadata._restartRequired.count | Should -Be 2
+        $out.results[2].metadata._restartRequired[0].process.name | Should -BeExactly 'myProcess'
+        $out.results[2].metadata._restartRequired[0].process.id | Should -Be 1234
+        $out.results[2].metadata._restartRequired[1].process.name | Should -BeExactly 'anotherProcess'
+        $out.results[2].metadata._restartRequired[1].process.id | Should -Be 5678
+        $out.metadata.'Microsoft.DSC'.restartRequired.count | Should -Be 5
+        $out.metadata.'Microsoft.DSC'.restartRequired[0].system | Should -BeExactly 'mySystem'
+        $out.metadata.'Microsoft.DSC'.restartRequired[1].service | Should -BeExactly 'myService'
+        $out.metadata.'Microsoft.DSC'.restartRequired[2].service | Should -BeExactly 'sshd'
+        $out.metadata.'Microsoft.DSC'.restartRequired[3].process.name | Should -BeExactly 'myProcess'
+        $out.metadata.'Microsoft.DSC'.restartRequired[3].process.id | Should -Be 1234
+        $out.metadata.'Microsoft.DSC'.restartRequired[4].process.name | Should -BeExactly 'anotherProcess'
+        $out.metadata.'Microsoft.DSC'.restartRequired[4].process.id | Should -Be 5678
+    }
 }
diff --git a/dsc_lib/locales/en-us.toml b/dsc_lib/locales/en-us.toml
@@ -69,6 +69,7 @@ invokeExpression = "Invoke property expression for %{name}: %{value}"
 propertyNotString = "Property '%{name}' with value '%{value}' is not a string"
 metadataMicrosoftDscIgnored = "Resource returned '_metadata' property 'Microsoft.DSC' which is ignored"
 metadataNotObject = "Resource returned '_metadata' property which is not an object"
+metadataRestartRequiredInvalid = "Resource returned '_metadata' property '_restartRequired' which contains invalid value: %{value}"
 
 [discovery.commandDiscovery]
 couldNotReadSetting = "Could not read 'resourcePath' setting"
diff --git a/dsc_lib/src/configure/config_doc.rs b/dsc_lib/src/configure/config_doc.rs
@@ -34,6 +34,21 @@ pub enum ExecutionKind {
     WhatIf,
 }
 
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct Process {
+    pub name: String,
+    pub id: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub enum RestartRequired {
+    System(String),
+    Service(String),
+    Process(Process),
+}
+
 #[derive(Debug, Default, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 pub struct MicrosoftDscMetadata {
     /// Version of DSC
@@ -57,6 +72,9 @@ pub struct MicrosoftDscMetadata {
     /// The security context of the configuration operation, can be specified to be required
     #[serde(rename = "securityContext", skip_serializing_if = "Option::is_none")]
     pub security_context: Option<SecurityContextKind>,
+    /// Indicates what needs to be restarted after the configuration operation
+    #[serde(rename = "restartRequired", skip_serializing_if = "Option::is_none")]
+    pub restart_required: Option<Vec<RestartRequired>>,
 }
 
 impl MicrosoftDscMetadata {
diff --git a/dsc_lib/src/configure/context.rs b/dsc_lib/src/configure/context.rs
@@ -7,7 +7,7 @@ use security_context_lib::{get_security_context, SecurityContext};
 use serde_json::{Map, Value};
 use std::{collections::HashMap, path::PathBuf};
 
-use super::config_doc::{DataType, SecurityContextKind};
+use super::config_doc::{DataType, RestartRequired, SecurityContextKind};
 
 pub struct Context {
     pub execution_type: ExecutionKind,
@@ -17,6 +17,7 @@ pub struct Context {
     pub security_context: SecurityContextKind,
     pub variables: Map<String, Value>,
     pub start_datetime: DateTime<Local>,
+    pub restart_required: Option<Vec<RestartRequired>>,
 }
 
 impl Context {
@@ -33,6 +34,7 @@ impl Context {
             },
             variables: Map::new(),
             start_datetime: chrono::Local::now(),
+            restart_required: None,
         }
     }
 }
diff --git a/dsc_lib/src/configure/mod.rs b/dsc_lib/src/configure/mod.rs
@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 use crate::configure::config_doc::{ExecutionKind, Metadata, Resource};
-use crate::configure::parameters::Input;
+use crate::configure::{config_doc::RestartRequired, parameters::Input};
 use crate::dscerror::DscError;
 use crate::dscresources::invoke_result::ExportResult;
 use crate::dscresources::{
@@ -87,17 +87,17 @@ pub fn add_resource_export_results_to_configuration(resource: &DscResource, conf
                 other: Map::new(),
             };
             if let Some(security_context) = props.remove("_securityContext") {
-                let context: SecurityContextKind = serde_json::from_value(security_context)?;
+                let security_context: SecurityContextKind = serde_json::from_value(security_context)?;
                 metadata.microsoft = Some(
                         MicrosoftDscMetadata {
-                            security_context: Some(context),
+                            security_context: Some(security_context),
                             ..Default::default()
                         }
                 );
             }
             r.properties = escape_property_values(&props)?;
             let mut properties = serde_json::to_value(&r.properties)?;
-            get_metadata_from_result(&mut properties, &mut metadata)?;
+            get_metadata_from_result(None, &mut properties, &mut metadata)?;
             r.properties = Some(properties.as_object().cloned().unwrap_or_default());
             r.metadata = if metadata.microsoft.is_some() || !metadata.other.is_empty() {
                 Some(metadata)
@@ -225,14 +225,24 @@ fn check_security_context(metadata: Option<&Metadata>) -> Result<(), DscError> {
     Ok(())
 }
 
-fn get_metadata_from_result(result: &mut Value, metadata: &mut Metadata) -> Result<(), DscError> {
+fn get_metadata_from_result(mut context: Option<&mut Context>, result: &mut Value, metadata: &mut Metadata) -> Result<(), DscError> {
     if let Some(metadata_value) = result.get("_metadata") {
         if let Some(metadata_map) = metadata_value.as_object() {
             for (key, value) in metadata_map {
                 if key.starts_with("Microsoft.DSC") {
                     warn!("{}", t!("configure.mod.metadataMicrosoftDscIgnored", key = key));
                     continue;
                 }
+                if let Some(ref mut context) = context {
+                    if key == "_restartRequired" {
+                        if let Some(restart_required) = serde_json::from_value::<Vec<RestartRequired>>(value.clone()).ok() {
+                            context.restart_required.get_or_insert_with(Vec::new).extend(restart_required);
+                        } else {
+                            warn!("{}", t!("configure.mod.metadataRestartRequiredInvalid", value = value));
+                            continue;
+                        }
+                    }
+                }
                 metadata.other.insert(key.clone(), value.clone());
             }
         } else {
@@ -335,7 +345,7 @@ impl Configurator {
             match &mut get_result {
                 GetResult::Resource(ref mut resource_result) => {
                     self.context.references.insert(format!("{}:{}", resource.resource_type, resource.name), serde_json::to_value(&resource_result.actual_state)?);
-                    get_metadata_from_result(&mut resource_result.actual_state, &mut metadata)?;
+                    get_metadata_from_result(Some(&mut self.context), &mut resource_result.actual_state, &mut metadata)?;
                 },
                 GetResult::Group(group) => {
                     let mut results = Vec::<Value>::new();
@@ -488,7 +498,7 @@ impl Configurator {
             match &mut set_result {
                 SetResult::Resource(resource_result) => {
                     self.context.references.insert(format!("{}:{}", resource.resource_type, resource.name), serde_json::to_value(&resource_result.after_state)?);
-                    get_metadata_from_result(&mut resource_result.after_state, &mut metadata)?;
+                    get_metadata_from_result(Some(&mut self.context), &mut resource_result.after_state, &mut metadata)?;
                 },
                 SetResult::Group(group) => {
                     let mut results = Vec::<Value>::new();
@@ -558,7 +568,7 @@ impl Configurator {
             match &mut test_result {
                 TestResult::Resource(resource_test_result) => {
                     self.context.references.insert(format!("{}:{}", resource.resource_type, resource.name), serde_json::to_value(&resource_test_result.actual_state)?);
-                    get_metadata_from_result(&mut resource_test_result.actual_state, &mut metadata)?;
+                    get_metadata_from_result(Some(&mut self.context), &mut resource_test_result.actual_state, &mut metadata)?;
                 },
                 TestResult::Group(group) => {
                     let mut results = Vec::<Value>::new();
@@ -765,6 +775,11 @@ impl Configurator {
                     end_datetime: Some(end_datetime.to_rfc3339()),
                     duration: Some(end_datetime.signed_duration_since(self.context.start_datetime).to_string()),
                     security_context: Some(self.context.security_context.clone()),
+                    restart_required: if let Some(restart_required) = self.context.restart_required.clone() {
+                        Some(restart_required)
+                    } else {
+                        None
+                    },
                 }
             ),
             other: Map::new(),

Original file line number	Diff line number	Diff line change
`@@ -289,4 +289,5 @@ pub enum SchemaType {`
`289`	`289`	`ExtensionManifest,`
`290`	`290`	`ExtensionDiscoverResult,`
`291`	`291`	`FunctionDefinition,`
	`292`	`+ RestartRequired`
`292`	`293`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ use security_context_lib::{get_security_context, SecurityContext};`
`7`	`7`	`use serde_json::{Map, Value};`
`8`	`8`	`use std::{collections::HashMap, path::PathBuf};`
`9`	`9`
`10`		`-use super::config_doc::{DataType, SecurityContextKind};`
	`10`	`+use super::config_doc::{DataType, RestartRequired, SecurityContextKind};`
`11`	`11`
`12`	`12`	`pub struct Context {`
`13`	`13`	`pub execution_type: ExecutionKind,`
`@@ -17,6 +17,7 @@ pub struct Context {`
`17`	`17`	`pub security_context: SecurityContextKind,`
`18`	`18`	`pub variables: Map<String, Value>,`
`19`	`19`	`pub start_datetime: DateTime<Local>,`
	`20`	`+ pub restart_required: Option<Vec<RestartRequired>>,`
`20`	`21`	`}`
`21`	`22`
`22`	`23`	`impl Context {`
`@@ -33,6 +34,7 @@ impl Context {`
`33`	`34`	`},`
`34`	`35`	`variables: Map::new(),`
`35`	`36`	`start_datetime: chrono::Local::now(),`
	`37`	`+ restart_required: None,`
`36`	`38`	`}`
`37`	`39`	`}`
`38`	`40`	`}`