Merge pull request #296760 from mumian/0321-fail-function

Document the fail() function

Author: v-dirichards

articles/azure-resource-manager/bicep/bicep-functions-flow-control.md

@@ -0,0 +1,47 @@
+---
+title: Bicep functions - flow control
+description: Describes the functions that incluence execution flow.
+ms.topic: reference
+ms.custom: devx-track-bicep
+ms.date: 03/25/2025
+---
+
+# Flow control functions for Bicep
+
+Bicep provides the `fail` function for influencing execution flow.
+
+The `fail` function is primarily used for enforcing constraints and terminating evaluation based on logical conditions. It usually works within short-circuiting expressions like [?? (coalesce operator)](./operators-logical.md#coalesce-) and [?: (ternary operator)](./operators-logical.md#conditional-expression--). For more information, see [Logical operators](./operators-logical.md).
+
+## fail
+
+`fail(arg1)`
+
+The `fail` function is useful for enforcing constraints in expressions, but it can only be used within short-circuiting functions—operations that stop execution as soon as the outcome is determined.
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| arg1 |Yes |string|A descriptive error message that explains why the failure occurred.|
+
+### Examples
+
+The following example shows how to use `fail`.
+
+```bicep
+anObjectParameter.?name ?? anObjectParameter.?id ?? fail('Expected anObjectParameter to have either a .name or a .id property')
+```
+
+Here, the coalesce operator (??) ensures that if **.name** exists, execution stops immediately. If **.name** is null or undefined, **.id** is checked. If both are missing, `fail` is triggered, preventing further execution.
+
+```bicep
+x != 0 ? y / x : fail('x cannot be zero because it will be used as a divisor')
+```
+
+In this case, the ternary operator (? :) checks if **x** is nonzero before performing division. If **x** is **0**, `fail` is invoked, stopping execution before an invalid operation occurs.
+
+## Next steps
+
+* For other actions involving logical values, see [logical operators](./operators-logical.md).

articles/azure-resource-manager/bicep/bicep-functions-logical.md

@@ -32,7 +32,7 @@ A boolean of the converted value.
 
 ### Examples
 
-The following example shows how to use bool with a string or integer.
+The following example shows how to use `bool` with a string or integer.
 
 ```bicep
 output trueString1 bool = bool('true')

articles/azure-resource-manager/bicep/bicep-functions.md

@@ -87,6 +87,12 @@ The following functions are available for loading the content from external file
 * [loadYamlContent](bicep-functions-files.md#loadyamlcontent)
 * [loadTextContent](bicep-functions-files.md#loadtextcontent)
 
+## Flow-control functions
+
+The following function is available for influencing execution flow. This function is in the `sys` namespace:
+
+* [fail](bicep-functions-flow-control.md#fail)
+
 ## Lambda functions
 
 The following functions are available for working with lambda expressions. All of these functions are in the `sys` namespace:

articles/azure-resource-manager/bicep/operators-logical.md

@@ -3,7 +3,7 @@ title: Bicep logical operators
 description: Describes Bicep logical operators that evaluate conditions.
 ms.topic: reference
 ms.custom: devx-track-bicep
-ms.date: 02/12/2025
+ms.date: 03/21/2025
 ---
 
 # Bicep logical operators
@@ -153,7 +153,7 @@ Output from the example:
 
 `operand1 ?? operand2`
 
-Returns first non-null value from operands.
+Returns first non-null value from operands. To control the execution flow, see the [fail function](./bicep-functions-flow-control.md#fail).
 
 ### Operands
 
@@ -197,7 +197,7 @@ Output from the example:
 
 `condition ? true-value : false-value`
 
-Evaluates a condition and returns a value whether the condition is true or false.
+Evaluates a condition and returns a value whether the condition is true or false. To control the execution flow, see the [fail function](./bicep-functions-flow-control.md#fail).
 
 ### Operands
 

articles/azure-resource-manager/bicep/toc.yml

@@ -338,6 +338,9 @@
     - name: File functions
       displayName: loadFileAsBase64,loadJsonContent,loadYamlContent,loadTextContent
       href: bicep-functions-files.md
+    - name: Flow-control functions
+      displayName: fail
+      href: bicep-functions-flow-control.md
     - name: Lambda functions
       displayName: filter,map,reduce,sort,toObject
       href: bicep-functions-lambda.md