Condividi tramite

Funzioni definite dall'utente in Bicep

  • Articolo

All'interno del file Bicep è possibile creare funzioni personalizzate. Tali funzioni sono disponibili per usare i file Bicep. Le funzioni definite dall'utente sono separate dalle funzioni standard di Bicep disponibili automaticamente nei file Bicep. Creare funzioni personalizzate quando sono presenti espressioni complesse che vengono usate ripetutamente nei file Bicep. L'uso di funzioni definite dall'utente abilita automaticamente la generazione del codice della versione 2.0 del linguaggio.

Per usare questa funzionalità, è necessaria l'interfaccia della riga di comando Bicep versione 0.26.X o successive.

Limiti

Quando si definisce una funzione utente, è necessario tenere presenti alcune limitazioni:

  • La funzione non può accedere alle variabili.
  • La funzione può usare solo i parametri definiti in essa.
  • La funzione non può usare la funzione riferimento né una qualsiasi delle funzioni dielenco.
  • I parametri della funzione non possono avere valori predefiniti.

Definire le funzioni

Usare l'istruzione func per definire funzioni definite dall'utente.

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

Esempi

Gli esempi seguenti illustrano come definire e usare funzioni definite dall'utente:

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

Gli output degli esempi precedenti sono:

Nome Type Valore
azureUrl String https://microsoft.com/azure
greetingArray Matrice ["Hi Evie!","Hi Casper!"]
greetingObject Oggetto {"hello":"Hi John!"}
nameArray Matrice ["John"]
addNameArray Matrice ["Mary","Bob","John"]

Con l'interfaccia della riga di comando di Bicep versione 0.23.X o successiva, è possibile richiamare un'altra funzione definita dall'utente all'interno di una funzione definita dall'utente. Nell'esempio precedente, con la definizione di funzione di sayHelloString, è possibile ridefinire la funzione sayHelloObject come:

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

Le funzioni definite dall'utente supportano l'uso di tipi di dati definiti dall'utente. Ad esempio:

@minValue(0)
type positiveInt = int

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

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

output elements positiveInt = typedArg(inArray)

L'output dell'esempio precedente è:

Nome Type Valore
Elementi figlio positiveInt 3

Usare elementi Decorator

Gli elementi Decorator vengono scritti nel formato @expression e vengono posizionati sopra le dichiarazioni di funzione. Nella tabella seguente vengono indicati gli elementi Decorator disponibili per le funzioni.

Decorator Argomento Descrizione
description stringa Consente di fornire descrizioni per la funzione.
export Nessuno Indica che la funzione è disponibile per l'importazione da un altro file Bicep.
metadata oggetto Proprietà personalizzate da applicare alla funzione. Può includere una proprietà description equivalente all'elemento decorator della descrizione.

I decorator si trovano nello spazio dei nomi sys. Se è necessario distinguere un decorator da un altro elemento con lo stesso nome, anteporre al decorator con sys. Ad esempio, se il file Bicep include una variabile denominata description, è necessario aggiungere lo spazio dei nomi sys quando si usa l'elemento Decorator description.

Descrizione

Per specificare una spiegazione, aggiungere un elemento description alla dichiarazione della funzione. Ad esempio:

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

Il testo in formato Markdown può essere usato come testo dell'elemento description.

Esportazione

Usare @export() per condividere la funzione con altri file Bicep. Per altre informazioni, vedere Esportare variabili, tipi e funzioni.

Metadati UFX

Se si dispone di proprietà personalizzate da applicare a una funzione definita dall'utente, aggiungere un elemento Decorator metadata. All'interno dei metadati definire un oggetto con i nomi e i valori personalizzati. L'oggetto definito per i metadati può contenere proprietà di qualsiasi nome e tipo.

È possibile usare questo elemento Decorator per tenere traccia delle informazioni sulla funzione che non ha senso aggiungere a description.

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

Quando si fornisce un decorator @metadata() con una proprietà in conflitto con un altro decorator, tale decorator ha sempre la precedenza su qualsiasi elemento nel decorator @metadata(). Pertanto, la proprietà in conflitto all'interno del valore @metadata() è ridondante e verrà sostituita. Per altre informazioni, vedere Nessun metadati in conflitto.

Passaggi successivi