Benutzerdefinierte Funktionen in Bicep

  • Artikel

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 nicht auf Variablen zugreifen.
  • 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>

Beispiele

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 String https://microsoft.com/azure
greetingArray Array ["Hi Evie!","Hi Casper!"]
greetingObject Object {"hello":"Hi John!"}
nameArray Array ["John"]
addNameArray Array ["Mary","Bob","John"]

Mit Bicep CLI Version 0.23.X oder höher haben Sie die Flexibilität, eine benutzerdefinierte Funktion innerhalb einer anderen 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

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.

Decorator Argument Beschreibung
Beschreibung string Geben Sie Beschreibungen für die Funktion an.
Export none Gibt an, dass die Funktion für den Import durch eine andere Bicep-Datei verfügbar ist.
metadata 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. Zum 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