Condividi tramite

Funzioni definite dall'utente in Bicep

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

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 TIPO Valore
azureUrl Stringa https://microsoft.com/azure
arraySaluti Matrice ["Hi Evie!","Hi Casper!"]
oggetto di saluto Oggetto {"hello":"Hi John!"}
nameArray Matrice ["John"]
aggiungiNomeArray Matrice ["Mary","Bob","John"]

È 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 TIPO Valore
Elementi figlio positiveInt 3

A partire dalla versione 0.30.X dell'interfaccia della riga di comando di Bicep, le funzioni definite dall'utente possono accedere alle variabili definite nello stesso file Bicep. L'esempio seguente illustra come una funzione definita dall'utente può fare riferimento a una variabile:

var greetingPrefix = 'Hello'

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

output message string = greet('Azure')

L'output dell'esempio precedente è:

Nome TIPO Valore
Messaggio Stringa Ciao, Azure!

A partire dalla versione 0.31.X dell'interfaccia della riga di comando di Bicep, le variabili importate da altri file Bicep sono accessibili all'interno delle funzioni definite dall'utente, proprio come le variabili definite in locale.

Si supponga di avere un file Bicep denominato shared.bicep che esporta una variabile:

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

È possibile importare questa variabile nel file Bicep principale e usarla all'interno di una funzione definita dall'utente:

import shared from './shared.bicep'

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

output resourceName string = makeResourceName('storage')

L'output dell'esempio precedente è:

Nome TIPO Valore
nomeRisorsa Stringa Contoso-storage

Per altre informazioni sull'importazione di variabili, vedere Esportare variabili, tipi e funzioni.

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.

Decoratore Argomento Descrizione
descrizione stringa Consente di fornire descrizioni per la funzione.
esportazione Nessuno Indica che la funzione è disponibile per l'importazione da un altro file Bicep.
metadati 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