Merge pull request #249682 from mumian/0828-udf

Bicep user-defined function

Author: v-regandowner

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

@@ -3,7 +3,7 @@ title: Bicep config file
 description: Describes the configuration file for your Bicep deployments
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 08/08/2023
+ms.date: 08/30/2023
 ---
 
 # Configure your Bicep environment
@@ -56,7 +56,7 @@ The preceding sample enables 'userDefineTypes' and 'extensibility`. The availabl
 - **sourceMapping**: Enables basic source mapping to map an error location returned in the ARM template layer back to the relevant location in the Bicep file.
 - **resourceTypedParamsAndOutputs**: Enables the type for a parameter or output to be of type resource to make it easier to pass resource references between modules. This feature is only partially implemented. See [Simplifying resource referencing](https://github.com/azure/bicep/issues/2245).
 - **symbolicNameCodegen**: Allows the ARM template layer to use a new schema to represent resources as an object dictionary rather than an array of objects. This feature improves the semantic equivalent of the Bicep and ARM templates, resulting in more reliable code generation. Enabling this feature has no effect on the Bicep layer's functionality.
-- **userDefinedFunctions**: Allows you to define your own custom functions.
+- **userDefinedFunctions**: Allows you to define your own custom functions. See [User-defined functions in Bicep](./user-defined-functions.md).
 - **userDefinedTypes**: Allows you to define your own custom types for parameters. See [User-defined types in Bicep](https://aka.ms/bicepCustomTypes).
 
 ## Next steps

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

@@ -3,7 +3,7 @@ title: Bicep file structure and syntax
 description: Describes the structure and properties of a Bicep file using declarative syntax.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 06/06/2023
+ms.date: 08/30/2023
 ---
 
 # Understand the structure and syntax of Bicep files
@@ -23,6 +23,8 @@ metadata <metadata-name> = ANY
 
 targetScope = '<scope>'
 
+func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>
+
 @<decorator>(<argument>)
 param <parameter-name> <parameter-data-type> = <default-value>
 
@@ -95,6 +97,21 @@ The allowed values are:
 
 In a module, you can specify a scope that is different than the scope for the rest of the Bicep file. For more information, see [Configure module scope](modules.md#set-module-scope)
 
+## Functions (Preview)
+
+> [!NOTE]
+> To enable the preview feature, see [Enable experimental features](./bicep-config.md#enable-experimental-features).
+
+In your Bicep file, you can create your own functions in addition to using the [standard Bicep functions](./bicep-functions.md) that are automatically available within your Bicep files. Create your own functions when you have complicated expressions that are used repeatedly in your Bicep files.
+
+```bicep
+func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'
+
+output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')
+```
+
+For more information, see [User-defined functions](./user-defined-functions.md).
+
 ## Parameters
 
 Use parameters for values that need to vary for different deployments. You can define a default value for the parameter that is used if no value is provided during deployment.

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

@@ -267,6 +267,9 @@
   - name: User-defined data types (type)
     displayName: custom
     href: user-defined-data-types.md
+  - name: User-defined functions (func)
+    displayName: custom
+    href: user-defined-functions.md
   - name: Parameters (param)
     href: parameters.md
     displayName: decorators,secure,objects,constraints

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

@@ -0,0 +1,90 @@
+---
+title: User-defined functions in Bicep
+description: Describes how to define and use user-defined functions in Bicep.
+ms.topic: conceptual
+ms.custom: devx-track-bicep
+ms.date: 08/30/2023
+---
+
+# User-defined functions in Bicep (Preview)
+
+Within your Bicep file, you can create your own functions. These functions are available for use in your Bicep files. User-defined functions are separate from the [standard Bicep functions](./bicep-functions.md) that are automatically available within your Bicep files. Create your own functions when you have complicated expressions that are used repeatedly in your Bicep files.
+
+[Bicep version 0.20 or newer](./install.md) is required to use this feature.
+
+## Enable the preview feature
+
+To enable this preview, modify your project's [bicepconfig.json](./bicep-config.md) file to include the following JSON:
+
+```json
+{
+  "experimentalFeaturesEnabled": {
+    "userDefinedFunctions": true
+  }
+}
+```
+
+## Define the function
+
+Use the `func` statement to define user-defined functions.
+
+```bicep
+func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>
+```
+
+## Examples
+
+The following examples show how to define and use user-defined functions:
+
+```bicep
+func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'
+
+func sayHelloString(name string) string => 'Hi ${name}!'
+
+func sayHelloObject(name string) object => {
+  hello: 'Hi ${name}!'
+}
+
+func nameArray(name string) array => [
+  name
+]
+
+func addNameArray(name string) array => [
+  'Mary'
+  'Bob'
+  name
+]
+
+output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')
+output greetingArray array = map(['Evie', 'Casper'], name => sayHelloString(name))
+output greetingObject object = sayHelloObject('John')
+output nameArray array = nameArray('John')
+output addNameArray array = addNameArray('John')
+
+```
+
+The outputs from the preceding examples are:
+
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| azureUrl | String | https://microsoft.com/azure |
+| greetingArray | Array | ["Hi Evie!","Hi Casper!"] |
+| greetingObject | Object | {"hello":"Hi John!"} |
+| nameArray | Array | ["John"] |
+| addNameArray | Array | ["Mary","Bob","John"] |
+
+## Limitations
+
+When defining a user function, there are some restrictions:
+
+* The function can't access variables.
+* The function can only use parameters that are defined in the function.
+* The function can't call other user-defined functions.
+* The function can't use the [reference](bicep-functions-resource.md#reference) function or any of the [list](bicep-functions-resource.md#list) functions.
+* Parameters for the function can't have default values.
+
+## Next steps
+
+* To learn about the Bicep file structure and syntax, see [Understand the structure and syntax of Bicep files](./file.md).
+* For a list of the available Bicep functions, see [Bicep functions](./bicep-functions.md).