Compartir a través de

Funciones definidas por el usuario en Bicep

  • Artículo

Dentro de su archivo Bicep, puede crear sus propias funciones. Estas funciones están disponibles para su uso en los archivos de Bicep. Las funciones definidas por el usuario son independientes de las funciones estándar de Bicep que están disponibles automáticamente en sus archivos de Bicep. Cree sus propias funciones cuando tenga expresiones complicadas que se usen repetidamente en los archivos de Bicep. El uso de funciones definidas por el usuario habilita automáticamente la generación de código para la versión 2.0 del lenguaje.

Para usar esta característica, se necesita la versión 0.26.X o posterior de la CLI de Bicep.

Limitaciones

Al definir una función de usuario, hay algunas restricciones:

  • La función no puede acceder a las variables.
  • La función solo puede usar los parámetros que se definen en la función.
  • La función no puede usar la función reference ni ninguna de las funciones list.
  • Los parámetros de la función no pueden tener valores predeterminados.

Definición de funciones

Use la instrucción func para definir funciones definidas por el usuario.

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

Ejemplos

En los ejemplos siguientes se muestra cómo definir y usar funciones definidas por el usuario:

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

Las salidas de los ejemplos anteriores son:

Nombre Tipo Value
azureUrl String https://microsoft.com/azure
greetingArray Matriz ["Hi Evie!","Hi Casper!"]
greetingObject Object {"hello":"Hi John!"}
nameArray Matriz ["John"]
addNameArray Matriz ["Mary","Bob","John"]

Con la CLI de Bicep versión 0.23.X o posterior, tiene la flexibilidad de invocar otra función definida por el usuario dentro de una función definida por el usuario. En el ejemplo anterior, con la definición de función de sayHelloString, puede volver a definir la función sayHelloObject como:

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

Las funciones definidas por el usuario admiten el uso de tipos de datos definidos por el usuario. Por ejemplo:

@minValue(0)
type positiveInt = int

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

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

output elements positiveInt = typedArg(inArray)

El resultado del ejemplo anterior es:

Nombre Tipo Value
Elementos positiveInt 3

Usar decoradores

Los decoradores se escriben en el formato @expression y se colocan encima de las declaraciones de función. En la tabla siguiente se muestran los decoradores disponibles para las funciones.

Decorador Argumento Descripción
descripción string Proporcione descripciones para la función.
export None Indica que la función está disponible para la importación por otro archivo de Bicep.
metadata objeto Propiedades personalizadas que se aplicarán a la función. Pueden incluir una propiedad de descripción equivalente al decorador de la descripción.

Los decoradores están en el espacio de nombres sys. Si tiene que diferenciar un decorador de otro elemento con el mismo nombre, anteceda el decorador con sys. Por ejemplo, si el archivo de Bicep incluye una variable llamada description, debe agregar el espacio de nombres sys al usar el decorador description.

Descripción

Para agregar una explicación, agregue una descripción a la declaración de función. Por ejemplo:

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

El texto con formato Markdown se puede usar para el texto de descripción.

Exportación

Use @export() para compartir la función con otros archivos de Bicep. Para obtener más información, consulte Exportación de variables, tipos y funciones.

Metadatos

Si tiene propiedades personalizadas que desea aplicar a una función definida por el usuario, agregue un decorador de metadatos. Dentro de los metadatos, defina un objeto con los nombres y valores personalizados. El objeto que defina para los metadatos puede contener propiedades de cualquier nombre y tipo.

Este decorador se puede utilizar para rastrear información sobre la función que no tenga sentido añadir a la descripción.

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

Cuando se proporciona un decorador @metadata() con una propiedad que está en conflicto con otro decorador, ese decorador siempre tiene prioridad sobre cualquier elemento del decorador @metadata(). Por tanto, la propiedad en conflicto dentro del valor @metadata() es redundante y se reemplazará. Para obtener más información, consulte Regla de linter: no-conflicting-metadata.

Pasos siguientes