Benutzerdefinierte Datentypen in Bicep

Hier erfahren Sie, wie Sie benutzerdefinierte Datentypen in Bicep erstellen. Informationen zu vom System definierten Datentypen finden Sie unter Datentypen. Durch die Verwendung von benutzerdefinierten Datentypen wird automatisch die Codegenerierung mit der Sprachversion 2.0 aktiviert.

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

Definieren von Typen

Sie können die Anweisung „type“ verwenden, um benutzerdefinierte Datentypen zu erstellen. Sie können an einigen Stellen auch Typausdrücke verwenden, um benutzerdefinierte Typen zu definieren.

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

Das Decorator-Element @allowed ist nur für param-Anweisungen zulässig. Zum Deklarieren eines Typs mit einer Gruppe vordefinierter Werte in type verwenden Sie die Union-Typsyntax.

Zu den gültigen Typausdrücken gehören:

• Symbolische Verweise sind Bezeichner, die auf einen Ambient-Typ (z.  B. string oder int) oder auf ein deklariertes benutzerdefiniertes Typsymbol in einer „type“-Anweisung verweisen:

  // Bicep data type reference
  type myStringType = string
  
  // user-defined type reference
  type myOtherStringType = myStringType
  

• Primitive Literale, einschließlich Zeichenfolgen, ganzer Zahlen und boolescher Werte, sind gültige Typausdrücke. Zum Beispiel:

  // a string type with three allowed values.
  type myStringLiteralType = 'bicep' | 'arm' | 'azure'
  
  // an integer type with one allowed value
  type myIntLiteralType = 10
  
  // an boolean type with one allowed value
  type myBoolLiteralType = true
  

• Sie können Arraytypen deklarieren, indem Sie [] an einen beliebigen gültigen Typausdruck anfügen:

  // A string type array
  type myStrStringsType1 = string[]
  // A string type array with three allowed values
  type myStrStringsType2 = ('a' | 'b' | 'c')[]
  
  type myIntArrayOfArraysType = int[][]
  
  // A mixed-type array with four allowed values
  type myMixedTypeArrayType = ('fizz' | 42 | {an: 'object'} | null)[]
  

• Objekttypen enthalten 0 oder mehr Eigenschaften zwischen geschweiften Klammern:

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  Jede Eigenschaft in einem Objekt besteht aus einem Schlüssel und einem Wert, getrennt durch einen Doppelpunkt :. Der Schlüssel kann eine beliebige Zeichenfolge sein, wobei Nicht-Identifiziererwerte in Anführungszeichen eingeschlossen sind. Der Wert kann ein beliebiger Ausdruckstyp sein.

  Eigenschaften sind erforderlich, es sei denn, sie verfügen über einen Optionalitäts-Marker „?“ nach dem Eigenschaftswert. Die -Eigenschaft „sku“ im folgenden Beispiel ist beispielsweise optional:

  type storageAccountConfigType = {
    name: string
    sku: string?
  }
  

  Sie können Decorator-Elemente auf Eigenschaften anwenden. Ein Sternchen (*) kann verwendet werden, damit alle Werte eine Einschränkung erfordern. Sie können weitere Eigenschaften mithilfe von * definieren. In diesem Beispiel wird ein Objekt erstellt, das einen Schlüssel vom Typ int namens id erfordert. Alle anderen Einträge im Objekt müssen mindestens 10 Zeichen lang sein.

  type obj = {
    @description('The object ID')
    id: int
  
    @description('Additional properties')
    @minLength(10)
    *: string
  }
  

  Das folgende Beispiel zeigt, wie Sie die Union-Typsyntax verwenden, um einen Satz vordefinierter Werte aufzulisten:

  type directions = 'east' | 'south' | 'west' | 'north'
  
  type obj = {
    level: 'bronze' | 'silver' | 'gold'
  }
  

• Objekttypen können direkte oder indirekte Rekursion verwenden, solange mindestens ein Zweig des Pfads zum Rekursionspunkt optional ist. Die Definition „myObjectType“ im folgenden Beispiel ist beispielsweise gültig, da die direkt rekursive Eigenschaft „recursiveProp“ optional ist:

  type myObjectType = {
    stringProp: string
    recursiveProp: myObjectType?
  }
  

  Die folgende Typdefinition wäre ungültig, da level1, level2, level3, level4 und level5 nicht optional sind.

  type invalidRecursiveObjectType = {
    level1: {
      level2: {
        level3: {
          level4: {
            level5: invalidRecursiveObjectType
          }
        }
      }
    }
  }
  

• Sie können unäre Bicep-Operatoren mit ganzzahligen und booleschen Literalen oder Verweisen auf ganzzahlige oder boolesche Literalsymbole verwendet werden:

  type negativeIntLiteral = -10
  type negatedIntReference = -negativeIntLiteral
  
  type negatedBoolLiteral = !true
  type negatedBoolReference = !negatedBoolLiteral
  

• Unions können eine beliebige Anzahl von Literalausdrücken enthalten. Union-Typen werden in Bicep in die Einschränkung für zulässige Werte übersetzt, sodass nur Literale als Elemente zulässig sind.

  type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
  type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
  

Sie können Typausdrücke in der type-Anweisung verwenden, und Sie können Typausdrücke auch verwenden, um benutzerdefinierte Datentypen zu erstellen, wie an den folgenden Stellen gezeigt:

• Als Typklausel einer „param“-Anweisung. Beispiel:

  param storageAccountConfig {
    name: string
    sku: string
  }
  

• Nach „:“ in einer Eigenschaft eines Objekttyps. Beispiel:

  param storageAccountConfig {
   name: string
    properties: {
      sku: string
    }
  } = {
    name: 'store$(uniqueString(resourceGroup().id)))'
    properties: {
      sku: 'Standard_LRS'
    }
  }
  

• Vor „[]“ in einem Arrayausdruck. Beispiel:

  param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]
  

Eine typische Bicep-Datei zum Erstellen eines Speicherkontos sieht folgendermaßen aus:

param location string = resourceGroup().location
param storageAccountName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountSKU string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

Mit benutzerdefinierten Datentypen kann dies folgendermaßen aussehen:

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Verwenden von Decorator-Elementen

Decorator-Elemente werden im Format @expression geschrieben und oberhalb der Deklarationen des benutzerdefinierten Datentyps platziert. In der folgenden Tabelle werden die für benutzerdefinierte Datentypen verfügbaren Decorator-Elemente gezeigt.

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 Namespace sys hinzufügen, wenn Sie den Decorator description verwenden.

Diskriminator

Siehe Markierter Union-Datentyp.

Beschreibung

Fügen Sie dem benutzerdefinierten Datentyp eine Beschreibung hinzu. Sie können Decorator-Elemente auf Eigenschaften anwenden. Zum Beispiel:

@description('Define a new object type.')
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}

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

Exportieren

Verwenden Sie @export(), um den benutzerdefinierten Datentyp für andere Bicep-Dateien freizugeben. Weitere Informationen finden Sie unter Exportieren von Variablen, Typen und Funktionen.

Ganzzahlige Einschränkungen

Sie können die minimalen und maximalen Werte für den Integer-Typ festlegen. Sie können eine oder beide Einschränkungen festlegen.

@minValue(1)
@maxValue(12)
type month int

Längenbeschränkungen

Sie können die minimale und maximale Länge für die Zeichenfolge- und Array-Typen angeben. Sie können eine oder beide Einschränkungen festlegen. Bei Zeichenfolgen gibt die Länge die Anzahl der Zeichen an. Bei Arrays gibt die Länge die Anzahl der Elemente im Array an.

Im folgenden Beispiel werden zwei Typen deklariert. Ein Typ bezieht sich auf den Namen eines Speicherkontos, der 3 bis 24 Zeichen enthalten muss. Der andere Typ ist ein Array, das 1 bis 5 Elemente aufweisen muss.

@minLength(3)
@maxLength(24)
type storageAccountName string

@minLength(1)
@maxLength(5)
type appNames array

Metadaten

Wenn Sie benutzerdefinierte Eigenschaften haben, die Sie auf einen benutzerdefinierten Typ 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 den Datentyp 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.

Versiegelt

Siehe Erhöhen der Fehlerebene.

Sichere Typen

Sie können die benutzerdefinierten Datentypen „Zeichenfolge“ oder „Objekt“ als sicher markieren. Der Wert eines sicheren Typs wird weder im Bereitstellungsverlauf gespeichert noch protokolliert.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Erhöhen der Fehlerebene

Durch das Deklarieren eines Objekttyps in Bicep können standardmäßig weitere Eigenschaften eines beliebigen Typs akzeptiert werden. Beispielsweise ist der folgende Bicep-Code gültig, löst jedoch die folgende Warnung aus: [BCP089] – The property "otionalProperty" is not allowed on objects of type "{ property: string, optionalProperty: null | string }". Did you mean "optionalProperty"?:

type anObject = {
  property: string
  optionalProperty: string?
}
 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

Die Warnung informiert Sie darüber, dass der Typ anObject keine Eigenschaft mit dem Namen otionalProperty enthält. Obwohl während der Bereitstellung keine Fehler auftreten, geht der Bicep-Compiler davon aus, dass otionalProperty ein Tippfehler ist und Sie optionalProperty verwenden möchten und sich verschrieben haben. Bicep informiert Sie über die Inkonsistenz.

Um diese Warnungen auf Fehler heraufzustufen, wenden Sie das Decorator-Element @sealed() auf den Objekttyp an:

@sealed() 
type anObject = {
  property: string
  optionalProperty?: string
}

Sie erhalten die gleichen Ergebnisse, indem Sie das Decorator-Element @sealed() auf die param-Deklaration anwenden:

type anObject = {
  property: string
  optionalProperty: string?
}
 
@sealed() 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

Die Azure Resource Manager-Bereitstellungs-Engine überprüft auch versiegelte Typen auf andere Eigenschaften. Die Bereitstellung zusätzlicher Eigenschaften für versiegelte Parameter führt zu einem Überprüfungsfehler und dadurch zu einem Fehler bei der Bereitstellung. Zum Beispiel:

@sealed()
type anObject = {
  property: string
}

param aParameter anObject = {
  property: 'value'
  optionalProperty: 'value'
}

Markierter Union-Datentyp

Um einen benutzerdefinierten markierten Union-Datentyp in einer Bicep-Datei zu deklarieren, können Sie einen discriminator-Decorator über einer benutzerdefinierten Typdeklaration platzieren. Um dieses Decorator-Element nutzen zu können, ist Bicep CLI Version 0.21.X oder höher erforderlich. Das folgende Beispiel zeigt, wie Sie einen markierten Union-Datentyp deklarieren:

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
type ServiceConfig = FooConfig | BarConfig | { type: 'baz', *: string }

param serviceConfig ServiceConfig = { type: 'bar', value: true }

output config object = serviceConfig

Weitere Informationen finden Sie unter Benutzerdefinierter markierter Union-Datentyp.

Zugehöriger Inhalt

Eine Liste der Bicep-Datentypen finden Sie unter Datentypen.