Partager via

Fonctions définies par l’utilisateur dans Bicep

  • Article

Vous pouvez créer vos propres fonctions à l’intérieur du fichier Bicep. 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 lorsque vous avez des expressions complexes utilisées à plusieurs reprises 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 0.26.X ou ultérieure est nécessaire pour utiliser cette fonctionnalité.

Limites

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

  • La fonction ne peut pas accéder aux variables.
  • 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>

Exemples

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 des exemples précédents sont :

Nom Type Valeur
azureUrl String https://microsoft.com/azure
greetingArray Tableau ["Hi Evie!","Hi Casper!"]
greetingObject Objet {"hello":"Hi John!"}
nameArray Tableau ["John"]
addNameArray Tableau ["Mary","Bob","John"]

Avec Bicep CLI version 0.23.X ou ultérieure, 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. Par 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 :

Nom Type Valeur
éléments positiveInt 3

Utiliser des éléments décoratifs

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

Élément décoratif Argument Description
description string Fournissez des descriptions pour la fonction.
export Aucune Indique que la fonction est disponible pour l’importation par un autre fichier Bicep.
métadonnées object Propriétés personnalisées à appliquer à la fonction. Peut inclure une propriété Description qui est équivalente à l’élément décoratif de description.

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.

Description

Pour ajouter une explication, ajoutez une description aux déclarations de fonction. Par 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.

Export

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 avez des propriétés personnalisées que vous souhaitez appliquer à une fonction définie par l’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 judicieux 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 @metadata() élément décoratif 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 @metadata() l’élément décoratif. 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