Add tryWhich() function and enable manifests to have condition

SteveL-MSFT · SteveL-MSFT · commit 44ab18b680c5 · 2025-10-24T14:09:10.000-07:00
diff --git a/dsc/tests/dsc_extension_manifest.tests.ps1 b/dsc/tests/dsc_extension_manifest.tests.ps1
@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+Describe 'Extension Manifests' {
+    It 'Extension manifests with condition: <condition>' -TestCases @(
+        @{ condition = "[equals(1, 1)]"; shouldBeFound = $true }
+        @{ condition = "[equals(1, 0)]"; shouldBeFound = $false }
+    ) {
+        param($condition, $shouldBeFound)
+
+        $extension_manifest = @"
+{
+    "`$schema": "https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json",
+    "type": "Test/Extension",
+    "condition": "$condition",
+    "version": "0.1.0",
+    "import": {
+        "fileExtensions": ["foo"],
+        "executable": "dsc"
+    }
+}
+"@
+
+        try {
+            $env:DSC_RESOURCE_PATH = $TestDrive
+            $manifestPath = Join-Path -Path $TestDrive -ChildPath 'Extension.dsc.extension.json'
+            $extension_manifest | Out-File -FilePath $manifestPath -Encoding utf8
+            $extensions = dsc extension list | ConvertFrom-Json -Depth 10
+            $LASTEXITCODE | Should -Be 0
+            if ($shouldBeFound) {
+                $extensions.count | Should -Be 1
+                $extensions.type | Should -BeExactly 'Test/Extension'
+            }
+            else {
+                $extensions.count | Should -Be 0
+            }
+        } finally {
+            $env:DSC_RESOURCE_PATH = $null
+        }
+    }
+}
diff --git a/dsc/tests/dsc_functions.tests.ps1 b/dsc/tests/dsc_functions.tests.ps1
@@ -1204,4 +1204,27 @@ Describe 'tests for function expressions' {
     $expected = "Microsoft.DSC.Debug/Echo:$([Uri]::EscapeDataString($name))"
     $out.results[0].result.actualState.output | Should -BeExactly $expected
   }
+
+  It 'tryWhich() works for: <expression>' -TestCases @(
+    @{ expression = "[tryWhich('pwsh')]"; found = $true }
+    @{ expression = "[tryWhich('nonexistentcommand12345')]"; found = $false }
+  ) {
+    param($expression, $found)
+
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: "$expression"
+"@
+    $out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log | ConvertFrom-Json
+    $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+    if ($found) {
+      $out.results[0].result.actualState.output | Should -Not -BeNullOrEmpty
+    } else {
+      $out.results[0].result.actualState.output | Should -BeNullOrEmpty
+    }
+  }
 }
diff --git a/dsc/tests/dsc_resource_manifest.tests.ps1 b/dsc/tests/dsc_resource_manifest.tests.ps1
@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+Describe 'Resource Manifests' {
+    It 'Resource manifests with condition: <condition>' -TestCases @(
+        @{ condition = "[equals(1, 1)]"; shouldBeFound = $true }
+        @{ condition = "[equals(1, 0)]"; shouldBeFound = $false }
+    ) {
+        param($condition, $shouldBeFound)
+
+        $resource_manifest = @"
+{
+    "`$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json",
+    "type": "Test/MyEcho",
+    "version": "1.0.0",
+    "condition": "$condition",
+    "get": {
+        "executable": "dscecho",
+        "args": [
+            {
+                "jsonInputArg": "--input",
+                "mandatory": true
+            }
+        ]
+    },
+    "schema": {
+        "command": {
+            "executable": "dscecho"
+        }
+    }
+}
+"@
+
+        try {
+            $env:DSC_RESOURCE_PATH = $TestDrive
+            $manifestPath = Join-Path -Path $TestDrive -ChildPath 'MyEcho.dsc.resource.json'
+            $resource_manifest | Out-File -FilePath $manifestPath -Encoding utf8
+            $resources = dsc resource list | ConvertFrom-Json -Depth 10
+            $LASTEXITCODE | Should -Be 0
+            if ($shouldBeFound) {
+                $resources.count | Should -Be 1
+                $resources.type | Should -BeExactly 'Test/MyEcho'
+            }
+            else {
+                $resources.count | Should -Be 0
+            }
+        } finally {
+            $env:DSC_RESOURCE_PATH = $null
+        }
+    }
+}
diff --git a/extensions/bicep/bicep.dsc.extension.json b/extensions/bicep/bicep.dsc.extension.json
@@ -3,6 +3,7 @@
     "type": "Microsoft.DSC.Extension/Bicep",
     "version": "0.1.0",
     "description": "Enable passing Bicep file directly to DSC, but requires bicep executable to be available.",
+    "condition": "[not(equals(tryWhich('bicep'), null()))]",
     "import": {
         "fileExtensions": ["bicep"],
         "executable": "bicep",
diff --git a/lib/dsc-lib/locales/en-us.toml b/lib/dsc-lib/locales/en-us.toml
@@ -118,6 +118,8 @@ foundResourceWithVersion = "Found matching resource '%{resource}' version %{vers
 foundNonAdapterResources = "Found %{count} non-adapter resources"
 resourceMissingRequireAdapter = "Resource '%{resource}' is missing 'require_adapter' field."
 extensionDiscoverFailed = "Extension '%{extension}' failed to discover resources: %{error}"
+conditionNotBoolean = "Condition '%{condition}' did not evaluate to a boolean"
+conditionNotMet = "Condition '%{condition}' not met, skipping manifest at '%{path}'"
 
 [dscresources.commandResource]
 invokeGet = "Invoking get for '%{resource}'"
@@ -542,6 +544,10 @@ invoked = "tryGet function"
 invalidKeyType = "Invalid key type, must be a string"
 invalidIndexType = "Invalid index type, must be an integer"
 
+[functions.tryWhich]
+description = "Attempts to locate an executable in the system PATH.  Null is returned if the executable is not found otherwise the full path to the executable is returned."
+invoked = "tryWhich function"
+
 [functions.union]
 description = "Returns a single array or object with all elements from the parameters"
 invoked = "union function"
diff --git a/lib/dsc-lib/src/discovery/command_discovery.rs b/lib/dsc-lib/src/discovery/command_discovery.rs
@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-use crate::{discovery::discovery_trait::{DiscoveryFilter, DiscoveryKind, ResourceDiscovery}};
+use crate::{discovery::discovery_trait::{DiscoveryFilter, DiscoveryKind, ResourceDiscovery}, parser::Statement};
 use crate::{locked_is_empty, locked_extend, locked_clone, locked_get};
+use crate::configure::context::Context;
 use crate::dscresources::dscresource::{Capability, DscResource, ImplementedAs};
 use crate::dscresources::resource_manifest::{import_manifest, validate_semver, Kind, ResourceManifest, SchemaKind};
 use crate::dscresources::command_resource::invoke_command;
@@ -640,6 +641,10 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {
                 }
             }
         };
+        if !evaluate_condition(manifest.condition.as_deref())? {
+            debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = manifest.condition.unwrap_or_default()));
+            return Ok(vec![]);
+        }
         let resource = load_resource_manifest(path, &manifest)?;
         return Ok(vec![ImportedManifest::Resource(resource)]);
     }
@@ -659,10 +664,15 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {
                 }
             }
         };
+        if !evaluate_condition(manifest.condition.as_deref())? {
+                debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = manifest.condition.unwrap_or_default()));
+                return Ok(vec![]);
+        }
         let extension = load_extension_manifest(path, &manifest)?;
         return Ok(vec![ImportedManifest::Extension(extension)]);
     }
     if DSC_MANIFEST_LIST_EXTENSIONS.iter().any(|ext| file_name_lowercase.ends_with(ext)) {
+        let mut resources: Vec<ImportedManifest> = vec![];
         let manifest_list = if extension_is_json {
             match serde_json::from_str::<ManifestList>(&contents) {
                 Ok(manifest) => manifest,
@@ -678,15 +688,22 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {
                 }
             }
         };
-        let mut resources = vec![];
         if let Some(resource_manifests) = &manifest_list.resources {
             for res_manifest in resource_manifests {
+                if !evaluate_condition(res_manifest.condition.as_deref())? {
+                    debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = res_manifest.condition.unwrap_or_default()));
+                    continue;
+                }
                 let resource = load_resource_manifest(path, res_manifest)?;
                 resources.push(ImportedManifest::Resource(resource));
             }
         }
         if let Some(extension_manifests) = &manifest_list.extensions {
             for ext_manifest in extension_manifests {
+                if !evaluate_condition(ext_manifest.condition.as_deref())? {
+                    debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = ext_manifest.condition.unwrap_or_default()));
+                    continue;
+                }
                 let extension = load_extension_manifest(path, ext_manifest)?;
                 resources.push(ImportedManifest::Extension(extension));
             }
diff --git a/lib/dsc-lib/src/dscresources/resource_manifest.rs b/lib/dsc-lib/src/dscresources/resource_manifest.rs
@@ -32,6 +32,9 @@ pub struct ResourceManifest {
     /// The namespaced name of the resource.
     #[serde(rename = "type")]
     pub resource_type: String,
+    /// An optional condition for the resource to be active.  If the condition evaluates to false, the resource is skipped.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
     /// The kind of resource.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub kind: Option<Kind>,
diff --git a/lib/dsc-lib/src/extensions/discover.rs b/lib/dsc-lib/src/extensions/discover.rs
@@ -91,7 +91,7 @@ impl DscExtension {
                     let manifest_path = Path::new(&discover_result.manifest_path);
                     // Currently we don't support extensions discovering other extensions
                     for imported_manifest in load_manifest(manifest_path)? {
-                        if let ImportedManifest::Resource(resource) = imported_manifest {
+                        if let Some(ImportedManifest::Resource(resource)) = imported_manifest {
                             resources.push(resource);
                         }
                     }
diff --git a/lib/dsc-lib/src/extensions/extension_manifest.rs b/lib/dsc-lib/src/extensions/extension_manifest.rs
@@ -23,6 +23,9 @@ pub struct ExtensionManifest {
     pub r#type: String,
     /// The version of the extension using semantic versioning.
     pub version: String,
+    /// An optional condition for the extension to be active.  If the condition evaluates to false, the extension is skipped.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
     /// The description of the extension.
     pub description: Option<String>,
     /// Tags for the extension.
diff --git a/lib/dsc-lib/src/functions/equals.rs b/lib/dsc-lib/src/functions/equals.rs
@@ -20,8 +20,8 @@ impl Function for Equals {
             min_args: 2,
             max_args: 2,
             accepted_arg_ordered_types: vec![
-                vec![FunctionArgKind::Number, FunctionArgKind::String, FunctionArgKind::Array, FunctionArgKind::Object],
-                vec![FunctionArgKind::Number, FunctionArgKind::String, FunctionArgKind::Array, FunctionArgKind::Object],
+                vec![FunctionArgKind::Null, FunctionArgKind::Number, FunctionArgKind::String, FunctionArgKind::Array, FunctionArgKind::Object],
+                vec![FunctionArgKind::Null, FunctionArgKind::Number, FunctionArgKind::String, FunctionArgKind::Array, FunctionArgKind::Object],
             ],
             remaining_arg_accepted_types: None,
             return_types: vec![FunctionArgKind::Boolean],
@@ -74,6 +74,13 @@ mod tests {
         assert_eq!(result, Value::Bool(false));
     }
 
+    #[test]
+    fn null_equal() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[equals(null(),null())]", &Context::new()).unwrap();
+        assert_eq!(result, Value::Bool(true));
+    }
+
     // TODO: Add tests for arrays once `createArray()` is implemented
     // TODO: Add tests for objects once `createObject()` is implemented
 }
diff --git a/lib/dsc-lib/src/functions/mod.rs b/lib/dsc-lib/src/functions/mod.rs
@@ -78,6 +78,7 @@ pub mod uri_component_to_string;
 pub mod user_function;
 pub mod utc_now;
 pub mod variables;
+pub mod try_which;
 
 /// The kind of argument that a function accepts.
 #[derive(Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Serialize, JsonSchema)]
@@ -205,6 +206,7 @@ impl FunctionDispatcher {
             Box::new(uri_component_to_string::UriComponentToString{}),
             Box::new(utc_now::UtcNow{}),
             Box::new(variables::Variables{}),
+            Box::new(try_which::TryWhich{}),
         ];
         for function in function_list {
             functions.insert(function.get_metadata().name.clone(), function);
diff --git a/lib/dsc-lib/src/functions/try_which.rs b/lib/dsc-lib/src/functions/try_which.rs
@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use crate::DscError;
+use crate::configure::context::Context;
+use crate::functions::{FunctionArgKind, Function, FunctionCategory, FunctionMetadata};
+use rust_i18n::t;
+use serde_json::Value;
+use tracing::debug;
+use which::which;
+
+#[derive(Debug, Default)]
+pub struct TryWhich {}
+
+impl Function for TryWhich {
+    fn get_metadata(&self) -> FunctionMetadata {
+        FunctionMetadata {
+            name: "tryWhich".to_string(),
+            description: t!("functions.tryWhich.description").to_string(),
+            category: vec![FunctionCategory::System],
+            min_args: 1,
+            max_args: 1,
+            accepted_arg_ordered_types: vec![vec![FunctionArgKind::String]],
+            remaining_arg_accepted_types: None,
+            return_types: vec![
+                FunctionArgKind::String,
+                FunctionArgKind::Null,
+            ],
+        }
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.tryWhich.invoked"));
+
+        let exe = args[0].as_str().unwrap();
+        match which(exe) {
+            Ok(found_path) => {
+                let path_str = found_path.to_string_lossy().to_string();
+                Ok(Value::String(path_str))
+            },
+            Err(_) => {
+                // In tryWhich, we return null if not found
+                Ok(Value::Null)
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::configure::context::Context;
+    use crate::parser::Statement;
+    use serde_json::Value;
+
+    #[test]
+    fn exe_exists() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryWhich('dsc')]", &Context::new()).unwrap();
+        #[cfg(windows)]
+        assert!(result.as_str().unwrap().to_lowercase().ends_with("\\dsc.exe"));
+        #[cfg(not(windows))]
+        assert!(result.as_str().unwrap().ends_with("/dsc"));
+    }
+
+    #[test]
+    fn invalid_exe() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryWhich('does_not_exist')]", &Context::new()).unwrap();
+        assert_eq!(result, Value::Null);
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,9 @@`
`1`	`1`	`// Copyright (c) Microsoft Corporation.`
`2`	`2`	`// Licensed under the MIT License.`
`3`	`3`
`4`		`-use crate::{discovery::discovery_trait::{DiscoveryFilter, DiscoveryKind, ResourceDiscovery}};`
	`4`	`+use crate::{discovery::discovery_trait::{DiscoveryFilter, DiscoveryKind, ResourceDiscovery}, parser::Statement};`
`5`	`5`	`use crate::{locked_is_empty, locked_extend, locked_clone, locked_get};`
	`6`	`+use crate::configure::context::Context;`
`6`	`7`	`use crate::dscresources::dscresource::{Capability, DscResource, ImplementedAs};`
`7`	`8`	`use crate::dscresources::resource_manifest::{import_manifest, validate_semver, Kind, ResourceManifest, SchemaKind};`
`8`	`9`	`use crate::dscresources::command_resource::invoke_command;`
`@@ -640,6 +641,10 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {`
`640`	`641`	`}`
`641`	`642`	`}`
`642`	`643`	`};`
	`644`	`+ if !evaluate_condition(manifest.condition.as_deref())? {`
	`645`	`+ debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = manifest.condition.unwrap_or_default()));`
	`646`	`+ return Ok(vec![]);`
	`647`	`+ }`
`643`	`648`	`let resource = load_resource_manifest(path, &manifest)?;`
`644`	`649`	`return Ok(vec![ImportedManifest::Resource(resource)]);`
`645`	`650`	`}`
`@@ -659,10 +664,15 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {`
`659`	`664`	`}`
`660`	`665`	`}`
`661`	`666`	`};`
	`667`	`+ if !evaluate_condition(manifest.condition.as_deref())? {`
	`668`	`+ debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = manifest.condition.unwrap_or_default()));`
	`669`	`+ return Ok(vec![]);`
	`670`	`+ }`
`662`	`671`	`let extension = load_extension_manifest(path, &manifest)?;`
`663`	`672`	`return Ok(vec![ImportedManifest::Extension(extension)]);`
`664`	`673`	`}`
`665`	`674`	`if DSC_MANIFEST_LIST_EXTENSIONS.iter().any(\|ext\| file_name_lowercase.ends_with(ext)) {`
	`675`	`+ let mut resources: Vec<ImportedManifest> = vec![];`
`666`	`676`	`let manifest_list = if extension_is_json {`
`667`	`677`	`match serde_json::from_str::<ManifestList>(&contents) {`
`668`	`678`	`Ok(manifest) => manifest,`
`@@ -678,15 +688,22 @@ pub fn load_manifest(path: &Path) -> Result<Vec<ImportedManifest>, DscError> {`
`678`	`688`	`}`
`679`	`689`	`}`
`680`	`690`	`};`
`681`		`- let mut resources = vec![];`
`682`	`691`	`if let Some(resource_manifests) = &manifest_list.resources {`
`683`	`692`	`for res_manifest in resource_manifests {`
	`693`	`+ if !evaluate_condition(res_manifest.condition.as_deref())? {`
	`694`	`+ debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = res_manifest.condition.unwrap_or_default()));`
	`695`	`+ continue;`
	`696`	`+ }`
`684`	`697`	`let resource = load_resource_manifest(path, res_manifest)?;`
`685`	`698`	`resources.push(ImportedManifest::Resource(resource));`
`686`	`699`	`}`
`687`	`700`	`}`
`688`	`701`	`if let Some(extension_manifests) = &manifest_list.extensions {`
`689`	`702`	`for ext_manifest in extension_manifests {`
	`703`	`+ if !evaluate_condition(ext_manifest.condition.as_deref())? {`
	`704`	`+ debug!("{}", t!("discovery.commandDiscovery.conditionNotMet", path = path.to_string_lossy(), condition = ext_manifest.condition.unwrap_or_default()));`
	`705`	`+ continue;`
	`706`	`+ }`
`690`	`707`	`let extension = load_extension_manifest(path, ext_manifest)?;`
`691`	`708`	`resources.push(ImportedManifest::Extension(extension));`
`692`	`709`	`}`
Original file line number	Diff line number	Diff line change
`@@ -91,7 +91,7 @@ impl DscExtension {`
`91`	`91`	`let manifest_path = Path::new(&discover_result.manifest_path);`
`92`	`92`	`// Currently we don't support extensions discovering other extensions`
`93`	`93`	`for imported_manifest in load_manifest(manifest_path)? {`
`94`		`- if let ImportedManifest::Resource(resource) = imported_manifest {`
	`94`	`+ if let Some(ImportedManifest::Resource(resource)) = imported_manifest {`
`95`	`95`	`resources.push(resource);`
`96`	`96`	`}`
`97`	`97`	`}`