Freigeben über

Benutzerdefinierte Funktionen in Bicep

In Ihrer Bicep-Datei können Sie Ihre eigenen Funktionen erstellen. Diese Funktionen stehen dann zur Verwendung in Ihren Bicep-Dateien zur Verfügung. Benutzerdefinierte Funktionen sind von den standardmäßigen Bicep-Funktionen getrennt, die automatisch in der Bicep-Datei verfügbar sind. Erstellen Sie eigene Funktionen, wenn Sie über komplizierte Ausdrücke verfügen, die in Ihren Bicep-Dateien wiederholt verwendet werden. Durch die Verwendung benutzerdefinierter Funktionen wird automatisch die Codegenerierung der Sprachversion 2.0 aktiviert.

Um diese Funktion nutzen zu können, ist Bicep CLI Version 0.26.X oder höher erforderlich.

Begrenzungen

Beim Definieren einer Benutzerfunktion gelten einige Einschränkungen:

  • Die Funktion kann nur Parameter verwenden, die in der Funktion definiert sind.
  • Die Funktion kann nicht die reference-Funktion oder eine der list-Funktionen verwenden.
  • Für die Parameter der Funktion können keine Standardwerte verwendet werden.

Definieren von Funktionen

Verwenden Sie die func-Anweisung, um benutzerdefinierte Funktionen zu definieren.

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

Die folgenden Beispiele zeigen, wie Sie benutzerdefinierte Funktionen definieren und verwenden:

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

Die Ausgaben aus den vorherigen Beispielen sind:

Name type Wert
azureUrl Schnur https://microsoft.com/azure
greetingArray Anordnung ["Hi Evie!","Hi Casper!"]
Grußobjekt Objekt {"hello":"Hallo John!"}
nameArray Anordnung ["John"]
addNameArray Anordnung ["Mary";"Bob";"John"]

Sie haben die Flexibilität, eine andere benutzerdefinierte Funktion innerhalb einer benutzerdefinierten Funktion aufzurufen. Im vorangegangenen Beispiel können Sie mit der Funktionsdefinition von sayHelloString die Funktion sayHelloObject wie folgt umdefinieren:

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

Benutzerdefinierte Funktionen unterstützen die Verwendung benutzerdefinierter Datentypen. Beispiel:

@minValue(0)
type positiveInt = int

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

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

output elements positiveInt = typedArg(inArray)

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

Name type Wert
Elemente positivInt 3

Ab Bicep CLI Version 0.30.X können benutzerdefinierte Funktionen auf Variablen zugreifen, die in derselben Bicep-Datei definiert sind. Das folgende Beispiel veranschaulicht, wie eine benutzerdefinierte Funktion auf eine Variable verweisen kann:

var greetingPrefix = 'Hello'

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

output message string = greet('Azure')

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

Name type Wert
Nachricht Schnur Hallo, Azure!

Ab Bicep CLI Version 0.31.X können variablen, die aus anderen Bicep-Dateien importiert wurden, in Ihren benutzerdefinierten Funktionen wie lokal definierte Variablen zugänglich sein.

Angenommen, Sie haben eine Bicep-Datei namens shared.bicep ,die eine Variable exportiert:

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

Sie können diese Variable in ihre Bicep-Hauptdatei importieren und in einer benutzerdefinierten Funktion verwenden:

import shared from './shared.bicep'

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

output resourceName string = makeResourceName('storage')

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

Name type Wert
Ressourcenname Schnur Contoso-Speicher

Weitere Informationen zum Importieren von Variablen finden Sie unter Exportieren von Variablen, Typen und Funktionen.

Verwenden von Decorator-Elementen

Decorator-Elemente werden im Format @expression geschrieben und oberhalb von Funktionsdeklarationen platziert. In der folgenden Tabelle werden die für Funktionen verfügbaren Decorator-Elemente gezeigt.

Dekorateur Streitpunkt Beschreibung
Beschreibung Schnur Geben Sie Beschreibungen für die Funktion an.
Export nichts Gibt an, dass die Funktion für den Import durch eine andere Bicep-Datei verfügbar ist.
Metadaten Objekt Benutzerdefinierte Eigenschaften, die auf die Funktion angewendet werden sollen. Kann eine Beschreibungseigenschaft enthalten, die dem Description-Decorator entspricht.

Decorators befinden sich im sys-Namespace. Wenn Sie diesen Decorator von einem anderen Element gleichen Namens unterscheiden müssen, stellen Sie dem Decorator sys voran. Wenn Ihre Bicep-Datei z. B. eine Variable mit dem Namen description enthält, müssen Sie den sys-Namespace hinzufügen, wenn Sie den Decorator description verwenden.

Beschreibung

Um eine Erklärung hinzuzufügen, fügen Sie der Funktionsdeklaration eine Beschreibung hinzu. Beispiel:

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

Mit Markdown formatierter Text kann für den Beschreibungstext verwendet werden.

Exportieren

Verwenden Sie @export(), um die Funktion mit anderen Bicep-Dateien zu teilen. Weitere Informationen finden Sie unter Exportieren von Variablen, Typen und Funktionen.

Metadaten

Wenn Sie benutzerdefinierte Eigenschaften haben, die Sie auf eine benutzerdefinierte Funktion anwenden möchten, fügen Sie einen Metadaten-Decorator hinzu. Definieren Sie innerhalb der Metadaten ein Objekt mit den benutzerdefinierten Namen und Werten. Das Objekt, das Sie für die Metadaten definieren, kann Eigenschaften eines beliebigen Namens und Typs enthalten.

Sie können diesen Decorator verwenden, um Informationen über die Funktion nachzuverfolgen, bei denen es nicht sinnvoll wäre, sie in die Beschreibung aufzunehmen.

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

Wenn Sie ein @metadata()-Decorator-Element mit einer Eigenschaft bereitstellen, die mit einem anderen Decorator-Element in Konflikt steht, hat dieses Decorator-Element immer Vorrang vor allen Elementen im @metadata()-Decorator-Element. Daher ist die in Konflikt stehende Eigenschaft innerhalb des Werts @metadata() redundant und wird ersetzt. Weitere Informationen finden Sie unter Keine widersprüchlichen Metadaten.

Nächste Schritte