Fonctions définies par l’utilisateur dans Bicep

Dans votre fichier Bicep, vous pouvez créer vos propres fonctions. Ces fonctions peuvent être utilisées dans vos fichiers Bicep. Les fonctions définies par l’utilisateur sont distinctes des fonctions Bicep standard qui sont automatiquement disponibles dans vos fichiers Bicep. Créez vos propres fonctions quand vous avez des expressions complexes qui sont utilisées de manière répétitive dans vos fichiers Bicep. L’utilisation de fonctions définies par l’utilisateur permet automatiquement de générer du code dans la version 2.0 du langage de programmation.

Bicep CLI version 1.2 ou ultérieure est obligatoire pour utiliser cette fonctionnalité.

Limites

La définition d’une fonction utilisateur est soumise à certaines restrictions :

• La fonction ne peut utiliser que des paramètres définis dans l’autre fonction.
• La fonction ne peut pas utiliser la fonction reference ni aucune des fonctions list.
• Les paramètres de la fonction ne peuvent pas avoir de valeur par défaut.

Définir des fonctions

Utilisez l’instruction func pour définir des fonctions définies par l’utilisateur.

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

Les exemples suivants montrent comment définir et utiliser des fonctions définies par l’utilisateur :

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

Les sorties de l’exemple précédent sont :

Vous avez la possibilité d’appeler une autre fonction définie par l’utilisateur dans une fonction définie par l’utilisateur. Dans l’exemple précédent, avec la définition de fonction de sayHelloString, vous pouvez redéfinir la fonction sayHelloObject comme suit :

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

Les fonctions définies par l’utilisateur prennent en charge l’utilisation de types de données définis par l’utilisateur. Voici un exemple :

@minValue(0)
type positiveInt = int

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

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

output elements positiveInt = typedArg(inArray)

La sortie de l’exemple précédent est :

À compter de Bicep CLI version 0.30.X, les fonctions définies par l’utilisateur peuvent accéder aux variables définies dans le même fichier Bicep. L’exemple suivant montre comment une fonction définie par l’utilisateur peut référencer une variable :

var greetingPrefix = 'Hello'

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

output message string = greet('Azure')

La sortie de l’exemple précédent est :

À compter de Bicep CLI version 0.31.X, les variables importées à partir d’autres fichiers Bicep sont accessibles dans vos fonctions définies par l’utilisateur, tout comme les variables définies localement.

Supposons que vous disposez d’un fichier Bicep nommé shared.bicep qui exporte une variable :

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

Vous pouvez importer cette variable dans votre fichier Bicep principal et l’utiliser dans une fonction définie par l’utilisateur :

import shared from './shared.bicep'

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

output resourceName string = makeResourceName('storage')

La sortie de l’exemple précédent est :

Pour plus d’informations sur l’importation de variables, consultez Exporter des variables, des types et des fonctions.

Utiliser des éléments décoratifs

Les éléments décoratifs sont écrits au format @expression et placés au-dessus des déclarations de fonctions. Le tableau suivant présente les éléments décoratifs disponibles pour les fonctions.

Les éléments décoratifs se trouvent dans l’espace de noms sys. Si vous devez différencier un élément décoratif d'un autre élément portant le même nom, faites précéder l’élément décoratif de sys. Par exemple, si votre fichier Bicep contient une variable nommée description, vous devez ajouter l’espace de noms sys lors de l’utilisation de l’élément décoratif description.

Descriptif

Pour ajouter une explication, ajoutez une description aux déclarations de fonction. Voici un exemple :

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

Du texte au format Markdown peut être utilisé pour le texte de description.

Exporter

Utilisez @export() pour partager la fonction avec d’autres fichiers Bicep. Pour plus d’informations, consultez Exporter des variables, des types et des fonctions.

Métadonnées

Si vous disposez de propriétés personnalisées que vous souhaitez appliquer à une fonction définie par un utilisateur, ajoutez un élément décoratif de métadonnées. Dans les métadonnées, définissez un objet avec des noms et valeurs personnalisés. L’objet que vous définissez pour les métadonnées peut contenir des propriétés de n’importe quel nom et type.

Vous pouvez utiliser cet élément décoratif pour suivre les informations relatives à la fonction qu'il n'est pas utile d'ajouter à la description.

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

Lorsque vous fournissez un élément décoratif @metadata() avec une propriété qui est en conflit avec un autre élément décoratif, cet élément décoratif est toujours prioritaire sur tout ce qui se passe dans l’élément décoratif @metadata(). Par conséquent, la propriété en conflit dans la valeur @metadata() est redondante et sera remplacée. Pour plus d’informations, consultez Aucune métadonnée en conflit.

Étapes suivantes

• Pour plus d’informations sur la structure et la syntaxe d’un fichier Bicep, consultez Présentation de la structure et de la syntaxe des fichiers Bicep.
• Pour obtenir la liste des fonctions Bicep disponibles, consultez les fonctions Bicep.