Merge branch 'reference-doc-function' of https://github.com/Gijsreyn/operation-methods into reference-doc-function

Author: Gijsreyn

archive/registry/Cargo.toml

@@ -19,7 +19,7 @@ clap = { version = "4.1", features = ["derive"] }
 crossterm = { version = "0.26" }
 ntreg = { path = "../ntreg" }
 ntstatuserror = { path = "../ntstatuserror" }
-schemars = { version = "0.8" }
+schemars = { version = "1.0" }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = { version = "1.0", features = ["preserve_order"] }
 

build.ps1

@@ -24,6 +24,8 @@ param(
 )
 
 $env:RUSTC_LOG=$null
+$env:RUSTFLAGS='-Dwarnings'
+
 if ($Verbose) {
     $env:RUSTC_LOG='rustc_codegen_ssa::back::link=info'
 }
@@ -40,6 +42,7 @@ if ($GetPackageVersion) {
 $filesForWindowsPackage = @(
     'appx.dsc.extension.json',
     'appx-discover.ps1',
+    'bicep.dsc.extension.json',
     'dsc.exe',
     'dsc_default.settings.json',
     'dsc.settings.json',
@@ -75,6 +78,7 @@ $filesForWindowsPackage = @(
 )
 
 $filesForLinuxPackage = @(
+    'bicep.dsc.extension.json',
     'dsc',
     'dsc_default.settings.json',
     'dsc.settings.json'
@@ -99,6 +103,7 @@ $filesForLinuxPackage = @(
 )
 
 $filesForMacPackage = @(
+    'bicep.dsc.extension.json',
     'dsc',
     'dsc_default.settings.json',
     'dsc.settings.json'
@@ -305,6 +310,7 @@ if (!$SkipBuild) {
         "dsc_lib",
         "dsc",
         "dscecho",
+        "extensions/bicep",
         "osinfo",
         "powershell-adapter",
         'resources/PSScript',
@@ -313,8 +319,7 @@ if (!$SkipBuild) {
         "sshdconfig",
         "tools/dsctest",
         "tools/test_group_resource",
-        "y2j",
-        "."
+        "y2j"
     )
     $pedantic_unclean_projects = @()
     $clippy_unclean_projects = @("tree-sitter-dscexpression", "tree-sitter-ssh-server-config")
@@ -564,7 +569,11 @@ if ($Test) {
         (Get-Module -Name Pester -ListAvailable).Path
     }
 
-    Invoke-Pester -ErrorAction Stop
+    try {
+        Invoke-Pester -ErrorAction Stop
+    } catch {
+        throw "Pester had unexpected error: $($_.Exception.Message)"
+    }
 }
 
 function Find-MakeAppx() {

docs/reference/resources/Microsoft/DSC/Transitional/RunCommandOnSet/examples/run-powershell-command.md

@@ -70,7 +70,7 @@ dsc config set --input $document
 To verify the result, you can run the `winget.exe` command:
 
 ```powershell
-winget list --id Microsoft.PowerShell
+winget list --id Microsoft.PowerShell.Preview
 ```
 
 <!-- Link reference definitions -->

docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md

@@ -40,7 +40,7 @@ differingProperties:
 - StartupType
 ```
 
-The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `property` property is mismatched between the desired state and actual state.
+The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `StartupType` property is mismatched between the desired state and actual state.
 
 ## Ensure a service is running with automatic startup
 

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

@@ -0,0 +1,148 @@
+---
+description: Reference for the 'and' DSC configuration document function
+ms.date:     01/19/2025
+ms.topic:    reference
+title:       and
+---
+
+# and
+
+## Synopsis
+
+Returns true if all arguments are true.
+
+## Syntax
+
+```Syntax
+and(<arg1>, <arg2>, ...)
+```
+
+## Description
+
+The `and()` function evaluates if all arguments are true. It takes two or more boolean arguments
+and returns `true` only if every argument is `true`. If any argument is `false`, the function
+returns `false`.
+
+This function uses short-circuit evaluation, meaning it returns `false` as soon as it encounters
+the first `false` argument without evaluating the remaining arguments.
+
+## Examples
+
+### Example 1 - Basic and operation
+
+This configuration demonstrates basic usage of the `and()` function.
+
+```yaml
+# and.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Echo and result
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output: "[and(true, true)]"
+```
+
+```bash
+dsc config get --file and.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.1291763S
+  name: Echo and result
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output: true
+messages: []
+hadErrors: false
+```
+
+### Example 2 - And operation with false value
+
+This example shows the `and()` function returning false when one argument is false.
+
+```yaml
+# and.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Echo and result with false
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output: "[and(true, false, true)]"
+```
+
+```bash
+dsc config get --file and.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.0329292S
+  name: Echo and result with false
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output: false
+messages: []
+hadErrors: false
+```
+
+### Example 3 - And operation with multiple conditions
+
+This configuration uses the `and()` function with multiple boolean expressions.
+
+```yaml
+# and.example.3.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Echo complex and operation
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output: "[and(equals(5, 5), equals('hello', 'hello'), true)]"
+```
+
+```bash
+dsc config get --file and.example.3.dsc.config.yaml
+```
+
+```yaml
+results:
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.0514415S
+  name: Echo complex and operation
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output: true
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### arguments
+
+The `and()` function requires two or more boolean arguments.
+
+```yaml
+Type:         boolean
+Required:     true
+MinimumCount: 2
+MaximumCount: 18446744073709551615
+```
+
+## Output
+
+The `and()` function returns `true` if all arguments are `true`, otherwise it returns `false`.
+
+```yaml
+Type: boolean
+```
+
+<!-- Link reference definitions -->

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

@@ -0,0 +1,135 @@
+---
+description: Reference for the 'bool' DSC configuration document function
+ms.date:     01/19/2025
+ms.topic:    reference
+title:       bool
+---
+
+# bool
+
+## Synopsis
+
+Converts a string or number to a boolean value.
+
+## Syntax
+
+```Syntax
+bool(<value>)
+```
+
+## Description
+
+The `bool()` function converts a string or number to a boolean value. For string arguments,
+it accepts "true" (case-insensitive) which converts to `true`, and "false" (case-insensitive)
+which converts to `false`. For numeric arguments, zero converts to `false` and any non-zero
+value converts to `true`.
+
+> [!NOTE]
+> Any string argument other than `true` or `false` (case-insensitive) will raise a DSC error.
+
+## Examples
+
+### Example 1 - Convert string to boolean
+
+This configuration demonstrates converting string values to boolean.
+
+```yaml
+# bool.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Echo bool from string
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output:
+        trueValue: "[bool('true')]"
+        falseValue: "[bool('FALSE')]"
+```
+
+```bash
+dsc config get --file bool.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.0334711S
+  name: Echo bool from string
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        trueValue: true
+        falseValue: false
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Convert number to boolean
+
+This example shows the `bool()` function converting numeric values to boolean.
+
+```yaml
+# bool.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Echo bool from numbers
+    type: Microsoft.DSC.Debug/Echo
+    properties:
+      output:
+        zeroIsFalse: "[bool(0)]"
+        oneIsTrue: "[bool(1)]"
+        negativeIsTrue: "[bool(-5)]"
+        positiveIsTrue: "[bool(42)]"
+```
+
+```bash
+dsc config get --file bool.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.0323199S
+  name: Echo bool from numbers
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        zeroIsFalse: false
+        oneIsTrue: true
+        negativeIsTrue: true
+        positiveIsTrue: true
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### value
+
+The `bool()` function requires a single argument that is either a string or number.
+
+For strings, valid values are:
+- "true" (case-insensitive) - converts to `true`
+- "false" (case-insensitive) - converts to `false`
+
+For numbers:
+- 0 - converts to `false`
+- Any non-zero value - converts to `true`
+
+```yaml
+Type:         [string, integer]
+Required:     true
+MinimumCount: 1
+MaximumCount: 1
+```
+
+## Output
+
+The `bool()` function returns a boolean value based on the input argument.
+
+```yaml
+Type: boolean
+```