From 31ac5ea759aa84d0012579572b455b6051c96ad7 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Sat, 11 Jul 2026 15:43:34 +0200 Subject: [PATCH 1/3] docs: add examples for validating minimum operating system version with `Microsoft/OSInfo` --- .../validate-minimum-version.config.dsc.yaml | 18 +++++ .../examples/validate-minimum-version.md | 81 +++++++++++++++++++ .../resources/Microsoft/OSInfo/index.md | 26 +++--- 3 files changed, 116 insertions(+), 9 deletions(-) create mode 100644 docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.config.dsc.yaml create mode 100644 docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.md diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.config.dsc.yaml new file mode 100644 index 000000000..e774cbae1 --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.config.dsc.yaml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Operating System Assertion + type: Microsoft.DSC/Assertion + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Minimum operating system version + type: Microsoft/OSInfo + properties: + version: '>= 10.0' + - name: Show operating system + type: Microsoft.DSC.Debug/Echo + properties: + output: 'The operating system meets the minimum version requirement.' + dependsOn: + - "[resourceId('Microsoft.DSC/Assertion', 'Operating System Assertion')]" diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.md b/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.md new file mode 100644 index 000000000..ea36b0877 --- /dev/null +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-minimum-version.md @@ -0,0 +1,81 @@ +--- +description: Validate a minimum operating system version with Microsoft/OSInfo +ms.date: 07/11/2026 +ms.topic: reference +title: Validate a minimum operating system version +--- + +# Validate a minimum operating system version + +This example uses the `Microsoft/OSInfo` resource with the `Microsoft.DSC/Assertion` group +resource to verify that the operating system version meets a minimum requirement before DSC runs +another resource. + +> [!IMPORTANT] +> The `osinfo` command and `Microsoft/OSInfo` resource are a proof-of-concept example for use with +> DSC. Don't use it in production. + +## Definition + +The **Operating System Assertion** group contains a `Microsoft/OSInfo` resource instance with the +version constraint `>= 10.0`. The `Microsoft.DSC/Assertion` resource always invokes **Test** for +nested instances. If the operating system is earlier than version `10.0`, the configuration fails +and DSC doesn't invoke **Show operating system**. + +:::code language="yaml" source="validate-minimum-version.config.dsc.yaml"::: + +## Running the configuration + +Run the configuration with the [dsc config set][01] command: + +```bash +dsc config set --file ./validate-minimum-version.config.dsc.yaml +``` + +On an operating system whose version is at least `10.0`, DSC returns successful results for both +the assertion group and the dependent echo resource: + +```yaml +results: +- name: Operating System Assertion + type: Microsoft.DSC/Assertion + result: + beforeState: + - name: Minimum operating system version + type: Microsoft/OSInfo + result: + actualState: + family: Windows + version: 10.0.26200 + _inDesiredState: true + afterState: + - name: Minimum operating system version + type: Microsoft/OSInfo + result: + desiredState: + version: '>= 10.0' + actualState: + family: Windows + version: 10.0.26200 + edition: Windows 11 + bitness: 64 + architecture: x86_64 + _inDesiredState: true + inDesiredState: true + differingProperties: + - version + changedProperties: [] +- name: Show operating system + type: Microsoft.DSC.Debug/Echo + result: + beforeState: + output: The operating system meets the minimum version requirement. + afterState: + output: The operating system meets the minimum version requirement. + changedProperties: null +messages: [] +hadErrors: false +``` + + +[01]: ../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/OSInfo/index.md b/docs/reference/resources/Microsoft/OSInfo/index.md index 9e72cd481..d74aa3fb4 100644 --- a/docs/reference/resources/Microsoft/OSInfo/index.md +++ b/docs/reference/resources/Microsoft/OSInfo/index.md @@ -1,6 +1,6 @@ --- description: Microsoft/OSInfo DSC resource reference documentation -ms.date: 03/25/2025 +ms.date: 07/11/2026 ms.topic: reference title: Microsoft/OSInfo --- @@ -46,10 +46,9 @@ The `Microsoft/OSInfo` resource enables you to assert whether a machine meets cr the operating system. The resource is only capable of assertions. It doesn't implement the set operation and can't configure the operating system. -The resource doesn't implement the [test operation][01]. It relies on the synthetic testing feature -of DSC instead. The synthetic test uses a case-sensitive equivalency comparison between the actual -state of the instance properties and the desired state. If any property value isn't an exact match, -DSC considers the instance to be out of the desired state. +The resource implements the [test operation][01]. The test operation compares every specified +instance property to the actual operating system information. The `version` property supports +version comparison constraints; all other properties use case-sensitive equality comparison. The instance properties returned by this resource depend on the operating system `family` as listed in the following table: @@ -75,11 +74,9 @@ None. This resource has the following capabilities: - `get` - You can use the resource to retrieve the actual state of an instance. +- `test` - You can use the resource to test whether an instance is in the desired state. - `export` - You can use the resource to retrieve the actual state of every instance. -This resource uses the synthetic test functionality of DSC to determine whether an instance is -in the desired state. - This resource doesn't have the `set` capability. You can't use it to modify the state of a system. For more information about resource capabilities, see @@ -89,6 +86,7 @@ For more information about resource capabilities, see 1. [Validate operating system information with dsc resource][03] 1. [Validate operating system information in a configuration][04] +1. [Validate a minimum operating system version in a configuration][07] ## Properties @@ -210,7 +208,16 @@ IsWriteOnly : false -Defines the version of the operating system as a string. +Defines the version of the operating system as a string. During the **Test** operation, this +property accepts an exact version string or a version comparison constraint. + +The supported comparison operators are `>`, `<`, `=`, `>=`, and `<=`. Whitespace between the +operator and version is optional. When you omit an operator, the resource performs an exact string +comparison. For example, `10.0`, `=10.0`, and `= 10.0` require an exact match, while `>= 10.0` +requires the operating system version to be at least `10.0`. + +The version value after an operator must begin with a digit. Unsupported operators, such as `~=`, +are treated as literal exact-match values and won't match a normal operating system version. ### $id @@ -256,3 +263,4 @@ operation failure. [04]: examples/validate-in-a-configuration.md [05]: ../../../../concepts/resources/properties.md#read-only-resource-properties [06]: ../../../tools/osinfo.md +[07]: examples/validate-minimum-version.md From 20b7f46458e33970987f4f4afe9e0cdb278671ba Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Sun, 12 Jul 2026 11:55:19 +0200 Subject: [PATCH 2/3] Fix Copilot remarks --- .../examples/validate-with-dsc-resource.md | 142 +++++++++--------- .../resources/Microsoft/OSInfo/index.md | 7 +- 2 files changed, 72 insertions(+), 77 deletions(-) diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md index b229a3115..e804f997c 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md @@ -2,7 +2,7 @@ description: > Validate operating system information with the Microsoft/OSInfo DSC Resource and the dsc resource commands. -ms.date: 03/25/2025 +ms.date: 07/12/2026 ms.topic: reference title: Validate operating system information with dsc resource --- @@ -69,6 +69,7 @@ actualState: version: 10.0.22621 edition: Windows 11 Enterprise bitness: '64' + architecture: x86_64 ``` --- @@ -79,10 +80,13 @@ DSC can use the resource to validate the operating system information. When you [dsc resource test][02] command, input JSON representing the desired state of the instance is required. The JSON must define at least one instance property to validate. -The resource doesn't implement the [test operation][03]. It relies on the synthetic testing feature -of DSC instead. The synthetic test uses a case-sensitive equivalency comparison between the actual -state of the instance properties and the desired state. If any property value isn't an exact match, -DSC considers the instance to be out of the desired state. +The resource implements the [test operation][03]. The command passes the desired state to the +resource over stdin and the resource returns the actual operating system information with an +`_inDesiredState` value. DSC returns that value as `inDesiredState` in the test result. + +All properties except `version` use case-sensitive equality comparison. For `version`, you can use +an exact version or a constraint with `>`, `<`, `=`, `>=`, or `<=`. For more information, see the +[version property][04] reference. # [Linux](#tab/linux) @@ -90,49 +94,46 @@ This test checks whether the `family` property for the instance is `Linux`. It p state for the instance to the command from stdin with the `--file` (`-f`) option. ```bash -invalid_instance='{"family": "Linux"}' -echo $invalid_instance | dsc resource test -r "${resource}" -f - +valid_instance='{"family": "Linux", "version": ">= 20.04"}' +echo $valid_instance | dsc resource test -r Microsoft/OSInfo -f - ``` ```yaml desiredState: - family: linux + family: Linux + version: '>= 20.04' actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Linux version: '20.04' codename: focal - bitness: '64' + bitness: 64 architecture: x86_64 -inDesiredState: false -differingProperties: -- family + _inDesiredState: true +inDesiredState: true +differingProperties: [] ``` -The result shows that the resource is out of the desired state because the actual state of the -`family` property wasn't case-sensitively equal to the desired state. - -The next test validates that the operating system is a 64-bit Linux operating system. It passes -the desired state for the instance to the command with the `--input` (`-i`) option. +The result shows that the resource evaluated both the family and version constraint successfully. +The next test demonstrates a case-sensitive mismatch. ```bash -valid_instance='{ "family": "Linux", "bitness": "64" }' -echo $valid_instance | dsc resource test -r Microsoft/OSInfo -i $valid_instance +invalid_instance='{ "family": "linux" }' +dsc resource test -r Microsoft/OSInfo -i $invalid_instance ``` ```yaml desiredState: - family: Linux - bitness: '64' + family: linux actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Linux version: '20.04' codename: focal - bitness: '64' + bitness: 64 architecture: x86_64 -inDesiredState: true -differingProperties: [] + _inDesiredState: false +inDesiredState: false +differingProperties: +- family ``` # [macOS](#tab/macos) @@ -141,100 +142,94 @@ This test checks whether the `family` property for the instance is `macOS`. It p state for the instance to the command from stdin with the `--file` (`-f`) option. ```zsh -invalid_instance='{"family": "macOS"}' -echo $invalid_instance | dsc resource test -r Microsoft/OSInfo -f - +valid_instance='{"family": "macOS", "version": ">= 13.0"}' +echo $valid_instance | dsc resource test -r Microsoft/OSInfo -f - ``` ```yaml desiredState: family: macOS + version: '>= 13.0' actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json - family: MacOS + family: macOS version: 13.5.0 - bitness: '64' + bitness: 64 architecture: arm64 -inDesiredState: false -differingProperties: -- family + _inDesiredState: true +inDesiredState: true +differingProperties: [] ``` -The result shows that the resource is out of the desired state because the actual state of the -`family` property wasn't case-sensitively equal to the desired state. - -The next test validates that the operating system is a 64-bit macOS operating system. It passes the -desired state for the instance to the command with the `--input` (`-i`) option. +The result shows that the resource evaluates the version constraint in addition to the family. +The next test demonstrates a case-sensitive mismatch. ```zsh -valid_instance='{ "family": "MacOS", "bitness": "64" }' -dsc resource test -r Microsoft/OSInfo -i $valid_instance +invalid_instance='{ "family": "MacOS" }' +dsc resource test -r Microsoft/OSInfo -i $invalid_instance ``` ```yaml desiredState: family: MacOS - bitness: '64' actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json - family: MacOS + family: macOS version: 13.5.0 - bitness: '64' + bitness: 64 architecture: arm64 -inDesiredState: true -differingProperties: [] + _inDesiredState: false +inDesiredState: false +differingProperties: +- family ``` # [Windows](#tab/windows) -This test checks whether the `family` property for the instance is `windows`. It passes the desired -state for the instance to the command from stdin with the `--file` (`-f`) option. +This test checks whether the `family` property for the instance is `Windows` and whether the +operating system version is at least `10.0`. It passes the desired state for the instance to the +command from stdin with the `--file` (`-f`) option. ```powershell -$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON -$invalidInstance | dsc resource test --resource Microsoft/OSInfo --file - +$validInstance = @{ family = 'Windows'; version = '>= 10.0' } | ConvertTo-JSON +$validInstance | dsc resource test --resource Microsoft/OSInfo --file - ``` ```yaml desiredState: - family: windows + family: Windows + version: '>= 10.0' actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Windows version: 10.0.22621 edition: Windows 11 Enterprise - bitness: "64" -inDesiredState: false -differingProperties: -- family + bitness: 64 + architecture: x86_64 + _inDesiredState: true +inDesiredState: true +differingProperties: [] ``` -The result shows that the resource is out of the desired state because the actual state of the -`family` property wasn't case-sensitively equal to the desired state. - -The next test validates that the operating system is a 64-bit Windows operating system. It passes -the desired state for the instance to the command with the `--input` (`-i`) option. +The result shows that the resource evaluated both the family and version constraint successfully. +The next test demonstrates a case-sensitive mismatch. ```powershell -$validInstance = @{ - family = 'Windows' - bitness = '64' -} | ConvertTo-JSON +$invalidInstance = @{ family = 'windows' } | ConvertTo-JSON -dsc resource test --resource Microsoft/OSInfo --input $validInstance +dsc resource test --resource Microsoft/OSInfo --input $invalidInstance ``` ```yaml desiredState: - family: Windows - bitness: '64' + family: windows actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Windows version: 10.0.22621 edition: Windows 11 Enterprise - bitness: "64" -inDesiredState: true -differingProperties: [] + bitness: 64 + architecture: x86_64 + _inDesiredState: false +inDesiredState: false +differingProperties: +- family ``` --- @@ -243,3 +238,4 @@ differingProperties: [] [01]: ../../../../cli/resource/get.md [02]: ../../../../cli/resource/test.md [03]: ../../../../../concepts/resources/overview.md#test-operations +[04]: ../index.md#version diff --git a/docs/reference/resources/Microsoft/OSInfo/index.md b/docs/reference/resources/Microsoft/OSInfo/index.md index d74aa3fb4..d03c2e2cf 100644 --- a/docs/reference/resources/Microsoft/OSInfo/index.md +++ b/docs/reference/resources/Microsoft/OSInfo/index.md @@ -57,7 +57,7 @@ listed in the following table: | :-------: | :--------------------------------------------------------- | | `Linux` | `architecture`, `bitness`, `codename`, `family`, `version` | | `MacOS` | `architecture`, `bitness`, `family`, `version` | -| `Windows` | `bitness`, `edition`, `family`, `version` | +| `Windows` | `architecture`, `bitness`, `edition`, `family`, `version` | > [!NOTE] > This resource is installed with DSC itself on all platforms. @@ -98,7 +98,7 @@ The following list describes the properties for the resource. - **Instance properties:** The following properties are optional. They define the desired state for an instance of the resource. - - [architecture](#architecture) - Defines the processor architecture on Linux and macOS systems. + - [architecture](#architecture) - Defines the processor architecture. - [bitness](#bitness) - Defines whether the operating system is 32-bit or 64-bit. - [codename](#codename) - Defines the codename for Linux systems. - [edition](#edition) - Defines the edition for Windows systems. @@ -124,8 +124,7 @@ IsWriteOnly : false -Defines the processor architecture as reported by `uname -m` on the operating system. The resource -doesn't return this property for Windows machines. +Defines the processor architecture reported by the operating system. ### bitness From 68367c13942e8cbcb3e0ce3f79ca99156dc82bd9 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Sun, 12 Jul 2026 11:56:26 +0200 Subject: [PATCH 3/3] Add macOS --- .../OSInfo/examples/validate-with-dsc-resource.md | 11 ++++------- docs/reference/resources/Microsoft/OSInfo/index.md | 9 ++++----- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md index e804f997c..194efe9da 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md +++ b/docs/reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md @@ -32,11 +32,10 @@ dsc resource get -r Microsoft/OSInfo ```yaml actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Linux version: '20.04' codename: focal - bitness: '64' + bitness: 64 architecture: x86_64 ``` @@ -49,10 +48,9 @@ dsc resource get -r Microsoft/OSInfo ```yaml actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json - family: MacOS + family: macOS version: 13.5.0 - bitness: '64' + bitness: 64 architecture: arm64 ``` @@ -64,11 +62,10 @@ dsc resource get --resource Microsoft/OSInfo ```yaml actualState: - $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json family: Windows version: 10.0.22621 edition: Windows 11 Enterprise - bitness: '64' + bitness: 64 architecture: x86_64 ``` diff --git a/docs/reference/resources/Microsoft/OSInfo/index.md b/docs/reference/resources/Microsoft/OSInfo/index.md index d03c2e2cf..8658c3044 100644 --- a/docs/reference/resources/Microsoft/OSInfo/index.md +++ b/docs/reference/resources/Microsoft/OSInfo/index.md @@ -56,7 +56,7 @@ listed in the following table: | `family` | Returned instance properties | | :-------: | :--------------------------------------------------------- | | `Linux` | `architecture`, `bitness`, `codename`, `family`, `version` | -| `MacOS` | `architecture`, `bitness`, `family`, `version` | +| `macOS` | `architecture`, `bitness`, `family`, `version` | | `Windows` | `architecture`, `bitness`, `edition`, `family`, `version` | > [!NOTE] @@ -131,18 +131,17 @@ Defines the processor architecture reported by the operating system.
Expand for bitness property metadata ```yaml -Type : string +Type : integer IsRequired : false IsKey : false IsReadOnly : false IsWriteOnly : false -ValidValues : ['32', '64', unknown] +ValidValues : [32, 64] ```
-Defines whether the operating system is a 32-bit or 64-bit operating system. When the resource -can't determine this information, it returns a value of `unknown`. +Defines whether the operating system is a 32-bit or 64-bit operating system. ### codename