Bicep 中的用户定义函数

在 Bicep 文件中，可以创建自己的函数。 这些函数可用于 Bicep 文件。 用户定义函数不同于 Bicep 文件中自动可用的标准 Bicep 函数。 当有复杂的表达式在 Bicep 文件中重复使用时，请创建自己的函数。 使用用户定义的函数时会自动启用语言版本 2.0 代码生成。

需要安装 Bicep CLI 0.26.X 或更高版本才能使用此功能。

限制

定义用户函数时，存在一些限制：

• 函数仅可使用函数中定义的参数。
• 该函数不能使用 reference 函数或任何 list 函数。
• 该函数的参数不能具有默认值。

定义函数

使用 func 语句定义用户定义的函数。

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

以下示例演示如何定义和使用用户定义的函数：

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')

上述示例的输出如下：

你可以灵活地在用户定义的函数中调用另一个用户定义的函数。 在前面的示例中，使用 sayHelloString 的函数定义，可以将 sayHelloObject 函数重新定义为：

func sayHelloObject(name string) object => {
  hello: sayHelloString(name)
}

用户定义的函数支持使用 用户定义的数据类型。 例如：

@minValue(0)
type positiveInt = int

func typedArg(input string[]) positiveInt => length(input)

param inArray array = [
  'Bicep'
  'ARM'
  'Terraform'
]

output elements positiveInt = typedArg(inArray)

前述示例的输出为：

从 Bicep CLI 版本 0.30.X 起，用户定义的函数可以访问在同一 Bicep 文件中定义的变量。 以下示例演示用户定义函数如何引用变量：

var greetingPrefix = 'Hello'

func greet(name string) string => '${greetingPrefix}, ${name}!'

output message string = greet('Azure')

前述示例的输出为：

从 Bicep CLI 版本 0.31.X 开始，从其他 Bicep 文件导入的变量可在用户定义的函数中访问，就像在本地定义的变量一样。

假设你有一个名为 shared.bicep 的 Bicep 文件，它导出一个变量：

// shared.bicep
@export()
var sharedPrefix = 'Contoso'

可以将此变量导入主 Bicep 文件中，并将其用于用户定义的函数：

import shared from './shared.bicep'

func makeResourceName(suffix string) string => '${shared.sharedPrefix}-${suffix}'

output resourceName string = makeResourceName('storage')

前述示例的输出为：

有关导入变量的详细信息，请参阅 导出变量、类型和函数。

使用修饰器

修饰器采用格式 @expression 编写，放置在函数声明上方。 下表显示了函数的可用修饰器。

修饰器位于 sys 命名空间中。 如果需要将修饰器与具有相同名称的其他项区分开来，请在修饰器前面加上 sys。 例如，如果 Bicep 文件包含名为 description 的变量，则必须在使用说明修饰器时添加 sys 命名空间。

说明

若要添加解释，请将说明添加到函数声明。 例如：

@description('The say hello function.')
func sayHelloString(name string) string => 'Hi ${name}!'

Markdown 格式的文本可用于说明文本。

导出

使用 @export() 与其他 Bicep 文件共享函数。 有关详细信息，请参阅导出变量、类型和函数。

元数据

如果你有要应用于用户定义的函数的自定义属性，请添加元数据修饰器。 在元数据中，使用自定义名称和值来定义对象。 为元数据定义的对象可以包含任何名称和类型的属性。

可以使用此修饰器来跟踪不适合添加到描述的函数的相关信息。

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
type settings object

当向 @metadata() 修饰器提供与另一个修饰器冲突的属性时，该修饰器始终优先于 @metadata() 修饰器中的任何内容。 因此，@metadata() 值中的冲突属性是冗余的，将被替换。 有关详细信息，请参阅无冲突元数据。

后续步骤

• 若要了解 Bicep 文件结构和语法，请参阅了解 Bicep 文件的结构和语法。
• 请参阅 Bicep 函数，了解可用 Bicep 函数列表。