Merge branch 'main' into add-registry-what-if

Author: tgauth

CHANGELOG.md

@@ -81,28 +81,33 @@ changes since the last release, see the [diff on GitHub][unreleased].
   [actual configuration set operation][ur-ab], except that the metadata field
   [executionType][ur-ac] is set to `WhatIf` instead of `Actual`.
 
-  In this release, the generated output is synthetic, based on the results of the resources' `test`
-  operation. In the future, resources will be able to participate in what-if operations, reporting
-  more specifically how they will change the system. For example, participating resources could
-  indicate whether an actual set operation will require a reboot or whether the current user has
-the correct permissions to manage that resource instance.
+  By default, the generated output is synthetic, based on the results of the resources' `test`
+  operation. Resources can define the [whatIf][ur-ad] property in their resource manifest to
+  participate in what-if operations, reporting more specifically how they will change the system.
+  For example, participating resources could indicate whether an actual set operation will require
+  a reboot or whether the current user has the correct permissions to manage that resource
+  instance.
+
+  Participating resources have the [WhatIf capability][ur-ae].
 
   <details><summary>Related work items</summary>
 
   - Issues: [#70][#70]
-  - PRs: [#400][#400]
+  - PRs:
+    - [#400][#400]
+    - [#441][#441]
 
   </details>
 
-- Added support for [importer resources][ur-ad]. These resources resolve external sources to a
+- Added support for [importer resources][ur-af]. These resources resolve external sources to a
   nested DSC Configuration document. The resolved instances are processed as nested resource
   instances.
 
   This required some updates to the schemas, all backwards-compatible:
 
-  - Added a new [resourceKind][ur-ae] named `Import`.
-  - Added the [resolve][ur-af] command to resource manifests.
-  - Added the new [`Resolve`][ur-ag] capability, returned in the output for the
+  - Added a new [resourceKind][ur-ag] named `Import`.
+  - Added the [resolve][ur-ah] command to resource manifests.
+  - Added the new [`Resolve`][ur-ai] capability, returned in the output for the
     [dsc resource list][cmd-rlist] command when DSC discovers an importer resource.
 
   <details><summary>Related work items</summary>
@@ -202,7 +207,6 @@ the correct permissions to manage that resource instance.
 
   </details>
 
-
 ### Fixed
 
 - Fixed the JSON Schema for [exit codes][ur-fa] in the resource manifest to support negative
@@ -216,14 +220,29 @@ the correct permissions to manage that resource instance.
 
   </details>
 
+- Fixed the behavior of the [int()][int()] configuration function to error when given an input
+  value other than a string or integer. Prior to this release, when you specified a number with
+  a fractional part as input for the function, it coerced the input value to an integer representing
+  the fractional part. Starting with this release, the `int()` function raises an invalid input
+  error when the input value isn't a string or an integer.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#390][#390]
+  - PRs: [#438][#438]
+
+  </details>
+
 <!-- Unreleased change links -->
 [ur-aa]: ./docs/reference/cli/config/set.md#-w---what-if
 [ur-ab]: ./docs/reference/schemas/outputs/config/set.md
 [ur-ac]: ./docs/reference/schemas/metadata/Microsoft.DSC/properties.md#executiontype
-[ur-ad]: ./docs/reference/schemas/definitions/resourceKind.md#importer-resources
-[ur-ae]: ./docs/reference/schemas/definitions/resourceKind.md
-[ur-af]: ./docs/reference/schemas/resource/manifest/resolve.md
-[ur-ag]: ./docs/reference/schemas/outputs/resource/list.md#capability-resolve
+[ur-ad]: ./docs/reference/schemas/resource/manifest/whatif.md
+[ur-ae]: ./docs/reference/schemas/outputs/resource/list.md#capability-whatif
+[ur-af]: ./docs/reference/schemas/definitions/resourceKind.md#importer-resources
+[ur-ag]: ./docs/reference/schemas/definitions/resourceKind.md
+[ur-ah]: ./docs/reference/schemas/resource/manifest/resolve.md
+[ur-ai]: ./docs/reference/schemas/outputs/resource/list.md#capability-resolve
 [ur-fa]: ./docs/reference/schemas/resource/manifest/root.md#exitcodes
 
 ## [v3.0.0-preview.7][release-v3.0.0-preview.7] - 2024-04-22
@@ -1481,6 +1500,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#382]: https://github.com/PowerShell/DSC/issues/382
 [#385]: https://github.com/PowerShell/DSC/issues/385
 [#388]: https://github.com/PowerShell/DSC/issues/388
+[#390]: https://github.com/PowerShell/DSC/issues/390
 [#397]: https://github.com/PowerShell/DSC/issues/397
 [#400]: https://github.com/PowerShell/DSC/issues/400
 [#401]: https://github.com/PowerShell/DSC/issues/401
@@ -1491,6 +1511,8 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#429]: https://github.com/PowerShell/DSC/issues/429
 [#432]: https://github.com/PowerShell/DSC/issues/432
 [#434]: https://github.com/PowerShell/DSC/issues/434
+[#438]: https://github.com/PowerShell/DSC/issues/438
+[#441]: https://github.com/PowerShell/DSC/issues/441
 [#45]:  https://github.com/PowerShell/DSC/issues/45
 [#49]:  https://github.com/PowerShell/DSC/issues/49
 [#57]:  https://github.com/PowerShell/DSC/issues/57

CODE_OF_CONDUCT.md

@@ -1,8 +1,10 @@
-# Code of Conduct
+# Microsoft Open Source Code of Conduct
 
-This project has adopted the [Microsoft Open Source Code of Conduct][conduct-code].
-For more information see the [Code of Conduct FAQ][conduct-FAQ] or contact [[email protected]][conduct-email] with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 
-[conduct-code]: https://opensource.microsoft.com/codeofconduct/
-[conduct-FAQ]: https://opensource.microsoft.com/codeofconduct/faq/
-[conduct-email]: mailto:[email protected]
+Resources:
+
+- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
+- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+- Contact [[email protected]](mailto:[email protected]) with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support)

CONTRIBUTING.md

@@ -66,7 +66,7 @@ To run the link-checker, follow these steps:
 ## Code of Conduct Enforcement
 
 Reports of abuse will be reviewed by the PS-Committee and if it has been determined that violations of the
-Code of Conduct has occurred, then a temporary ban may be imposed.
+[Code of Conduct](CODE_OF_CONDUCT.md) has occurred, then a temporary ban may be imposed.
 The duration of the temporary ban will depend on the impact and/or severity of the infraction.
 This can vary from 1 day, a few days, a week, and up to 30 days.
 Repeat offenses may result in a permanent ban from the PowerShell org.

README.md

@@ -65,6 +65,14 @@ DSCv3 uses JSON schemas to define the structure of resources, configuration docu
 outputs that DSCv3 returns. These schemas make it easier to integrate DSCv3 with other tools,
 because they standardize and document how to interface with DSCv3.
 
+## Code of Conduct
+
+Please see our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in this project.
+
+## Security Policy
+
+For any security issues, please see our [Security Policy](SECURITY.md).
+
 [00]: https://github.com/powershell/psdesiredstateconfiguration
 [01]: https://github.com/PowerShell/DSC/releases/latest
 [02]: https://learn.microsoft.com/powershell/dsc/overview?view=dsc-3.0&preserve-view=true

SECURITY.md

@@ -1,12 +1,41 @@
-# Security Vulnerabilities
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->
 
-Security issues are treated very seriously and will, by default,
-takes precedence over other considerations including usability, performance,
-etc...  Best effort will be used to mitigate side effects of a security
-change, but DSC must be secure by default.
+## Security
 
-## Reporting a security vulnerability
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin) and [PowerShell](https://github.com/PowerShell).
 
-If you believe that there is a security vulnerability in DSC,
-it **must** be reported using [https://aka.ms/secure-at](https://aka.ms/secure-at) to allow for [Coordinated Vulnerability Disclosure](https://technet.microsoft.com/security/dn467923).
-**Only** file an issue, if [MSRC](https://www.microsoft.com/en-us/msrc/faqs-report-an-issue?rtc=1) has confirmed filing an issue is appropriate.
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report).
+
+If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

docs/reference/schemas/config/functions/int.md

@@ -1,6 +1,6 @@
 ---
 description: Reference for the 'int' DSC configuration document function
-ms.date:     04/09/2024
+ms.date:     06/13/2024
 ms.topic:    reference
 title:       int
 ---
@@ -9,7 +9,7 @@ title:       int
 
 ## Synopsis
 
-Returns an integer from an input string or non-integer number.
+Returns an integer from an input string or integer.
 
 ## Syntax
 
@@ -19,8 +19,9 @@ int(<inputValue>)
 
 ## Description
 
-The `int()` function returns an integer, converting an input string or non-integer number into an
-integer. It truncates the fractional part of the input number, it doesn't round up.
+The `int()` function returns an integer, converting an input string into an integer. If you pass an
+integer, it returns the integer. If you pass any other value, including a non-integer number, the
+function raises an invalid input error.
 
 ## Examples
 
@@ -57,17 +58,12 @@ hadErrors: false
 
 ### inputValue
 
-The `int()` function expects input as either a string or a number. If the value is a string that
-can't be parsed as a number, DSC returns an error for the function.
-
-> [!NOTE]
-> There is an open bug (see [GitHub issue #390][#390]) for this function when operating on numbers.
-> The function correctly returns the expected value for string representations of numbers with
-> fractional parts, but returns the fractional part instead of the integer for actual numbers.
-> Specify the input value for this function as a string instead of a number.
+The `int()` function expects input as either a string or an integer. If the value is a string that
+can't be parsed as a number DSC returns an error for the function. If the value isn't a string or
+integer, DSC returns an invalid input error for the function.
 
 ```yaml
-Type:         [String, Number]
+Type:         [String, Integer]
 Required:     true
 MinimumCount: 1
 MaximumCount: 1
@@ -84,4 +80,3 @@ Type: integer
 ```
 
 <!-- Link reference definitions -->
-[#390]: https://github.com/PowerShell/DSC/issues/390

docs/reference/schemas/outputs/resource/list.md

@@ -85,15 +85,15 @@ optional and depend on the resource.
 
 The following list describes the available capabilities for a resource:
 
-- <a id="capability-get" /> `Get` - The resource supports retrieving the current state of an
+- <a id="capability-get" ></a> `Get` - The resource supports retrieving the current state of an
   instance. All DSC Resources must have this capability. A resource has this capability when it
   defines the mandatory [get][07] property in its resource manifest.
-- <a id="capability-set" /> `Set` - The resource supports enforcing the desired state of an
+- <a id="capability-set" ></a> `Set` - The resource supports enforcing the desired state of an
   instance. A resource has this capability when it defines the [set][08] property in its resource
   manifest. Resources without this capability can't be used with the [dsc resource set][09] or
   [dsc config set][10] commands unless they're in a [Microsoft.DSC/Assertion][11] group as a nested
   instance.
-- <a id="capability-sethandlesexist" /> `SetHandlesExist` - The resource supports the
+- <a id="capability-sethandlesexist" ></a> `SetHandlesExist` - The resource supports the
   [_exist property][12] directly. A resource has this capability when it defines the
   [handlesExist][13] property as `true` in the definition of the [set][08] command property in its
   resource manifest.
@@ -106,28 +106,43 @@ The following list describes the available capabilities for a resource:
 
   If the resource doesn't have this capability or the `Delete` capability, DSC raises an error when
   an instance defines `_exist` as `false`.
-- <a id="capability-test" /> `Test` - The resource supports validating the desired state of an
+- <a id="capability-whatif" ></a> `WhatIf` - The resource supports returning explicit information
+  about how it will modify state when a user calls [dsc config set][10] with the [--what-if][15]
+  option. A resource has this capability when it defines the [What-if method][16] in its resource
+  manifest.
+
+  When a resource has this capability, DSC calls the defined command with its arguments when a
+  user executes the `dsc config set` command with the `--what-if` option.
+
+  When a resource doesn't have this capability, DSC synthesizes how the resource will change and
+  instance by converting the `Test` result for the instance into a `Set` result. The synthetic
+  operation can't indicate potential issues or changes that can't be determined by comparing the
+  result of the `Test` operation against the resource's desired state. For example, the credentials
+  used to test a resource might be valid for that operation, but not have permissions to actually
+  modify the system state. Only a resource with this capability can fully report whether and how
+  the resource will change system state.
+- <a id="capability-test" ></a> `Test` - The resource supports validating the desired state of an
   instance against the current state of the instance. A resource has this capability when it
-  defines the [test][15] property in its resource manifest.
+  defines the [test][17] property in its resource manifest.
 
   If a resource doesn't have the `Test` capability, DSC uses a synthetic test for instances of the
   resource. The synthetic test compares each property for the desired state of an instance against
   the actual state. The synthetic test uses strict, case-sensitive equivalence. If the desired
   state for a property and the actual state aren't the same, DSC marks the property as out of the
   desired state.
-- <a id="capability-delete" /> `Delete` - The resource supports removing an instance. A resource
+- <a id="capability-delete" ></a> `Delete` - The resource supports removing an instance. A resource
   has this capability when it defines the [delete][14] property in its resource manifest. This
   capability isn't mutually exclusive with the `SetHandlesExist` property. A resource can handle
-  the `_exist` property in set operations and be called directly with [dsc resource delete][16] to
+  the `_exist` property in set operations and be called directly with [dsc resource delete][18] to
   remove an instance.
-- <a id="capability-export" /> `Export` - The resource supports enumerating every instance of the
-  resource. A resource has this capability when it defines the [export][17] property in its resource
-  manifest. Only resources with this capability are usable with the [dsc resource export][18] and
-  [dsc config export][19] commands.
-- <a id="capability-resolve" /> `Resolve` - The resource supports resolving nested resource
+- <a id="capability-export" ></a> `Export` - The resource supports enumerating every instance of
+  the resource. A resource has this capability when it defines the [export][19] property in its
+  resource manifest. Only resources with this capability are usable with the
+  [dsc resource export][20] and [dsc config export][21] commands.
+- <a id="capability-resolve" ></a> `Resolve` - The resource supports resolving nested resource
   instances from an external source. A resource has this capability when it defines the
-  [resolve][20] property in its resource manifest. This functionality is primarily used by
-  [importer resources][21].
+  [resolve][22] property in its resource manifest. This functionality is primarily used by
+  [importer resources][23].
 
 ```yaml
 Type:              array
@@ -215,7 +230,7 @@ Required: true
 
 Represents the values defined in the resource's manifest. This value is `null` for resources that
 aren't command-based. For more information on the value for this property, see
-[Command-based DSC Resource manifest schema reference][22].
+[Command-based DSC Resource manifest schema reference][24].
 
 ```yaml
 Type:     [object, 'null']
@@ -237,11 +252,13 @@ Required: true
 [12]: ../../resource/properties/exist.md
 [13]: ../../resource/manifest/set.md#handlesexist
 [14]: ../../resource/manifest/delete.md
-[15]: ../../resource/manifest/test.md
-[16]: ../../../cli/resource/delete.md
-[17]: ../../resource/manifest/export.md
-[18]: ../../../cli/resource/export.md
-[19]: ../../../cli/config/export.md
-[20]: ../../resource/manifest/resolve.md
-[21]: ../../definitions/resourceKind.md#importer-resources
-[22]: ../../resource/manifest/root.md
+[15]: ../../../cli/config/set.md#-w---what-if
+[16]: ../../resource/manifest/whatif.md
+[17]: ../../resource/manifest/test.md
+[18]: ../../../cli/resource/delete.md
+[19]: ../../resource/manifest/export.md
+[20]: ../../../cli/resource/export.md
+[21]: ../../../cli/config/export.md
+[22]: ../../resource/manifest/resolve.md
+[23]: ../../definitions/resourceKind.md#importer-resources
+[24]: ../../resource/manifest/root.md