Merge branch 'main' into get-as-export

Author: SteveL-MSFT

CHANGELOG.md

@@ -75,6 +75,15 @@ changes since the last release, see the [diff on GitHub][unreleased].
     for the `v3.0.0.0-alpha.5` release. Leave the release links under the release section.
 -->
 
+## [v3.1.0][release-v3.1.0] - 2025-06-18
+
+This section includes a summary of changes for the `3.1.0` release. For the full list of changes
+in this release, see the [diff on GitHub][compare-v3.1.0].
+
+<!-- Release links -->
+[release-v3.1.0]: https://github.com/PowerShell/DSC/releases/tag/v3.1.0 "Link to the DSC v3.1.0 release on GitHub"
+[compare-v3.1.0]: https://github.com/PowerShell/DSC/compare/v3.0.2...v3.1.0
+
 ### Added
 
 - Added support for defining adapted resource instances in configuration documents without

docs/reference/cli/resource/test.md

@@ -16,19 +16,19 @@ Validates the actual state of a resource instance against a desired state.
 ### Instance properties from input option
 
 ```sh
-dsc resource set --input <INPUT> --resource <RESOURCE>
+dsc resource test --input <INPUT> --resource <RESOURCE>
 ```
 
 ### Instance properties from file
 
 ```sh
-dsc resource set --file <FILE> --resource <RESOURCE>
+dsc resource test --file <FILE> --resource <RESOURCE>
 ```
 
 ### Instance properties from stdin
 
 ```sh
-cat <FILE> | dsc resource set [Options] --resource <RESOURCE> --file -
+cat <FILE> | dsc resource test [Options] --resource <RESOURCE> --file -
 ```
 
 ## Description

docs/reference/schemas/config/parameter.md

@@ -29,7 +29,7 @@ Parameters are defined as key-value pairs in the `parameters` property of a conf
 The key is the parameter's name, which is used to reference the parameter in the [resources][01]
 property of the configuration document. The value is an object that defines the parameter.
 
-Every parameter defines its data type. Parameters may also define a default value, validation
+Every parameter defines its data type. Parameters can also define a default value, validation
 checks, a description of their purpose, and arbitrary metadata.
 
 To reference parameters in resource instances, use the [parameters() configuration function][02].
@@ -42,7 +42,7 @@ To reference parameters in resource instances, use the [parameters() configurati
 
 ### description
 
-Parameters may define a short explanation of their purpose and usage with the `description`
+Parameters can define a short explanation of their purpose and usage with the `description`
 property. To define a longer explanation in YAML, use the folded block syntax or literal block
 syntax.
 
@@ -68,8 +68,8 @@ data type for every passed parameter before executing a configuration operation.
 
 The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the
 values. If a secure data type parameter is used for a resource instance property that doesn't
-expect a secure value, the resource may still log or record the value. If the resource has
-independent logging or recording that isn't handled by DSC, the value may be stored insecurely.
+expect a secure value, the resource might still log or record the value. If the resource has
+independent logging or recording that isn't handled by DSC, the value might be stored insecurely.
 
 Use secure strings for passwords and secrets.
 
@@ -84,7 +84,7 @@ ValidValues: [string, securestring, int, bool, object, secureobject, array]
 
 ### defaultValue
 
-Parameters may define a default value with the `defaultValue` property. If the parameter isn't
+Parameters can define a default value with the `defaultValue` property. If the parameter isn't
 passed at runtime, DSC uses the default value for the parameter. If the parameter isn't passed at
 runtime and no default value is defined, DSC raises an error. The value must be valid for the
 parameter's `type`.
@@ -96,7 +96,7 @@ ValidJSONTypes: [string, integer, object, array, boolean]
 
 ### allowedValues
 
-Parameters may limit the set of valid values for the parameter by defining the `allowedValues`
+Parameters can limit the set of valid values for the parameter by defining the `allowedValues`
 property. DSC validates parameters passed at runtime and defined as `defaultValue` against this
 list of values. If any of the values is invalid, DSC raises an error.
 

docs/reference/schemas/config/resource.md

@@ -69,7 +69,7 @@ Pattern:  ^\w+(\.\w+){0,2}\/\w+$
 ### properties
 
 The `properties` of a resource instance define its desired state. The value of this property must
-be an object. For assertion  resources, the value may be an empty object (`{}`). DSC uses the
+be an object. For assertion  resources, the value can be an empty object (`{}`). DSC uses the
 DSC Resource's instance schema to validate the defined properties.
 
 <!-- For more information about instance schemas in DSC, see [DSC Resource instance schemas][aa]. -->

docs/reference/schemas/resource/properties/purge.md

@@ -1,5 +1,5 @@
 ---
-description: JSON schema reference for the '_purge' well-known DSC Resource property.
+description: JSON schema reference for the '_purge' canonical DSC Resource property.
 ms.date:     07/03/2025
 ms.topic:    reference
 title:       DSC Resource _purge property schema

dsc/tests/dsc_functions_secret.tests.ps1 renamed to dsc/tests/dsc_extension_secret.tests.ps1

@@ -116,4 +116,19 @@ Describe 'Tests for the secret() function and extensions' {
         $out.results.Count | Should -Be 1
         $out.results[0].result.actualState.Output | Should -BeExactly 'SameSecret'
     }
+
+    It 'Secret with multiple lines' {
+        $configYaml = @'
+            $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: "[secret('MultiLine')]"
+'@
+        dsc -l trace config get -i $configYaml 2> $TestDrive/error.log | ConvertFrom-Json
+        $LASTEXITCODE | Should -Be 2
+        $errorMessage = Get-Content -Raw -Path $TestDrive/error.log
+        $errorMessage | Should -Match "Extension 'Test/Secret2' returned multiple lines which is not supported for secrets"
+    }
 }

dsc_lib/locales/en-us.toml

@@ -182,13 +182,12 @@ discoverNoResults = "No results returned for discovery extension '%{extension}'"
 discoverNotAbsolutePath = "Resource path from extension '%{extension}' is not an absolute path: %{path}"
 extensionReturned = "Extension '%{extension}' returned line: %{line}"
 retrievingSecretFromExtension = "Retrieving secret '%{name}' from extension '%{extension}'"
-secretExtensionReturnedInvalidJson = "Extension '%{extension}' returned invalid JSON: %{error}"
 extensionReturnedSecret = "Extension '%{extension}' returned secret"
 extensionReturnedNoSecret = "Extension '%{extension}' did not return a secret"
-secretNoResults = "Extension '%{extension}' returned no output"
 importingFile = "Importing file '%{file}' with extension '%{extension}'"
 importNotSupported = "Import is not supported by extension '%{extension}' for file '%{file}'"
 importNoResults = "Extension '%{extension}' returned no results for import"
+secretMultipleLinesReturned = "Extension '%{extension}' returned multiple lines which is not supported for secrets"
 
 [extensions.extension_manifest]
 extensionManifestSchemaTitle = "Extension manifest schema URI"

dsc_lib/src/extensions/dscextension.rs

@@ -9,7 +9,20 @@ use schemars::JsonSchema;
 use std::{fmt::Display, path::Path};
 use tracing::{debug, info, trace};
 
-use crate::{discovery::command_discovery::{load_manifest, ImportedManifest}, dscerror::DscError, dscresources::{command_resource::{invoke_command, process_args}, dscresource::DscResource}, extensions::{import::ImportArgKind, secret::SecretResult}};
+use crate::{
+    discovery::command_discovery::{
+        load_manifest, ImportedManifest
+    },
+    dscerror::DscError,
+    dscresources::{
+        command_resource::{
+            invoke_command,
+            process_args
+        },
+        dscresource::DscResource
+    },
+    extensions::import::ImportArgKind
+};
 
 use super::{discover::DiscoverResult, extension_manifest::ExtensionManifest, secret::SecretArgKind};
 
@@ -229,21 +242,18 @@ impl DscExtension {
                 extension.exit_codes.as_ref(),
             )?;
             if stdout.is_empty() {
-                info!("{}", t!("extensions.dscextension.secretNoResults", extension = self.type_name));
+                debug!("{}", t!("extensions.dscextension.extensionReturnedNoSecret", extension = self.type_name));
                 Ok(None)
             } else {
-                let result: SecretResult = match serde_json::from_str(&stdout) {
-                    Ok(value) => value,
-                    Err(err) => {
-                        return Err(DscError::Extension(t!("extensions.dscextension.secretExtensionReturnedInvalidJson", extension = self.type_name, error = err).to_string()));
-                    }
-                };
-                if result.secure_string.is_some() {
-                    debug!("{}", t!("extensions.dscextension.extensionReturnedSecret", extension = self.type_name));
+                // see if multiple lines were returned
+                let secret = if stdout.lines().count() > 1 {
+                    return Err(DscError::NotSupported(t!("extensions.dscextension.secretMultipleLinesReturned", extension = self.type_name).to_string()));
                 } else {
-                    debug!("{}", t!("extensions.dscextension.extensionReturnedNoSecret", extension = self.type_name));
-                }
-                Ok(result.secure_string)
+                    debug!("{}", t!("extensions.dscextension.extensionReturnedSecret", extension = self.type_name));
+                    // remove any trailing newline characters
+                    stdout.trim_end_matches('\n').to_string()
+                };
+                Ok(Some(secret))
             }
         } else {
             Err(DscError::UnsupportedCapability(

dsc_lib/src/extensions/secret.rs

@@ -30,9 +30,3 @@ pub struct SecretMethod {
     /// The arguments to pass to the command to perform a Get.
     pub args: Option<Vec<SecretArgKind>>,
 }
-
-#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
-pub struct SecretResult {
-    #[serde(rename = "secureString")]
-    pub secure_string: Option<String>,
-}

examples/extensions/azcli/azcli.dsc.extension.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json",
+    "type": "Microsoft.Azure.CLI/KeyVault",
+    "version": "1.0.0",
+    "description": "Retrieve secrets from Azure KeyVault.  Requires AzCLI to already be installed.",
+    "secret": {
+        "executable": "az.cmd",
+        "outputKind": "PlainText",
+        "args": [
+            "keyvault",
+            "secret",
+            "show",
+            {
+                "vaultArg": "--vault-name"
+            },
+            {
+                "nameArg": "--name"
+            },
+            "--query",
+            "value",
+            "--output",
+            "tsv"
+        ]
+    }
+}