|
| 1 | +--- |
| 2 | +title: User-defined functions in Bicep |
| 3 | +description: Describes how to define and use user-defined functions in Bicep. |
| 4 | +ms.topic: conceptual |
| 5 | +ms.custom: devx-track-bicep |
| 6 | +ms.date: 08/29/2023 |
| 7 | +--- |
| 8 | + |
| 9 | +# User-defined functions in Bicep (Preview) |
| 10 | + |
| 11 | +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. |
| 12 | + |
| 13 | +## Enable the preview feature |
| 14 | + |
| 15 | +To enable this preview, modify your project's [bicepconfig.json](./bicep-config.md) file to include the following JSON: |
| 16 | + |
| 17 | +```json |
| 18 | +{ |
| 19 | + "experimentalFeaturesEnabled": { |
| 20 | + "userDefinedFunctions": true |
| 21 | + } |
| 22 | +} |
| 23 | +``` |
| 24 | + |
| 25 | +## Define the function |
| 26 | + |
| 27 | +You can use the `func` statement to define user-defined functions. |
| 28 | + |
| 29 | +```bicep |
| 30 | +func <user-defined-function-name> (<argument> <data-type>, <argument> <date-type>, ...) <function-data-type> => <expression> |
| 31 | +``` |
| 32 | + |
| 33 | +Your functions require a namespace value to avoid naming conflicts with template functions. The following example shows a function that returns a unique name: |
| 34 | + |
| 35 | +```bicep |
| 36 | +func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}' |
| 37 | +
|
| 38 | +func sayHello(name string) string => 'Hi ${name}!' |
| 39 | +
|
| 40 | +func objReturnType(name string) object => { |
| 41 | + hello: 'Hi ${name}!' |
| 42 | +} |
| 43 | +
|
| 44 | +func arrayReturnType(name string) array => [ |
| 45 | + name |
| 46 | +] |
| 47 | +
|
| 48 | +func asdf(name string) array => [ |
| 49 | + 'asdf' |
| 50 | + name |
| 51 | +] |
| 52 | +
|
| 53 | +@minValue(0) |
| 54 | +type positiveInt = int |
| 55 | +
|
| 56 | +func typedArg(input string[]) positiveInt => length(input) |
| 57 | +``` |
| 58 | + |
| 59 | +## Use the function |
| 60 | + |
| 61 | +The following example shows a template that includes a user-defined function to get a unique name for a storage account. The template has a parameter named `storageNamePrefix` that is passed as a parameter to the function. |
| 62 | + |
| 63 | +```json |
| 64 | +{ |
| 65 | + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", |
| 66 | + "contentVersion": "1.0.0.0", |
| 67 | + "parameters": { |
| 68 | + "storageNamePrefix": { |
| 69 | + "type": "string", |
| 70 | + "maxLength": 11 |
| 71 | + } |
| 72 | + }, |
| 73 | + "functions": [ |
| 74 | + { |
| 75 | + "namespace": "contoso", |
| 76 | + "members": { |
| 77 | + "uniqueName": { |
| 78 | + "parameters": [ |
| 79 | + { |
| 80 | + "name": "namePrefix", |
| 81 | + "type": "string" |
| 82 | + } |
| 83 | + ], |
| 84 | + "output": { |
| 85 | + "type": "string", |
| 86 | + "value": "[concat(toLower(parameters('namePrefix')), uniqueString(resourceGroup().id))]" |
| 87 | + } |
| 88 | + } |
| 89 | + } |
| 90 | + } |
| 91 | +], |
| 92 | + "resources": [ |
| 93 | + { |
| 94 | + "type": "Microsoft.Storage/storageAccounts", |
| 95 | + "apiVersion": "2022-09-01", |
| 96 | + "name": "[contoso.uniqueName(parameters('storageNamePrefix'))]", |
| 97 | + "location": "South Central US", |
| 98 | + "sku": { |
| 99 | + "name": "Standard_LRS" |
| 100 | + }, |
| 101 | + "kind": "StorageV2", |
| 102 | + "properties": { |
| 103 | + "supportsHttpsTrafficOnly": true |
| 104 | + } |
| 105 | + } |
| 106 | + ] |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +During deployment, the `storageNamePrefix` parameter is passed to the function: |
| 111 | + |
| 112 | +* The template defines a parameter named `storageNamePrefix`. |
| 113 | +* The function uses `namePrefix` because you can only use parameters defined in the function. For more information, see [Limitations](#limitations). |
| 114 | +* In the template's `resources` section, the `name` element uses the function and passes the `storageNamePrefix` value to the function's `namePrefix`. |
| 115 | + |
| 116 | +## Limitations |
| 117 | + |
| 118 | +When defining a user function, there are some restrictions: |
| 119 | + |
| 120 | +* The function can't access variables. |
| 121 | +* The function can only use parameters that are defined in the function. When you use the [parameters](template-functions-deployment.md#parameters) function within a user-defined function, you're restricted to the parameters for that function. |
| 122 | +* The function can't call other user-defined functions. |
| 123 | +* The function can't use the [reference](template-functions-resource.md#reference) function or any of the [list](template-functions-resource.md#list) functions. |
| 124 | +* Parameters for the function can't have default values. |
| 125 | + |
| 126 | +## Next steps |
| 127 | + |
| 128 | +* To learn about the available properties for user-defined functions, see [Understand the structure and syntax of ARM templates](./syntax.md). |
| 129 | +* For a list of the available template functions, see [ARM template functions](template-functions.md). |
0 commit comments