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.

Die "use-user-defined-types"- Regel empfiehlt die Verwendung benutzerdefinierter Datentypen anstelle der generischen object Typen oder array Typen.

Definieren von Typen

Verwenden Sie die type Anweisung, 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 Kontexttyp (wie string oder int) oder auf ein benutzerdefiniertes Typsymbol verweisen, das in einer type-Anweisung deklariert ist.

  // 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. 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 jeden gültigen Typausdruck anhängen. Beispiel:

  // 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 ist ungültig, da keines von level1, level2, , level3, level4oder level5 optional ist.

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

• Sie können unäre Bicep-Operatoren mit Ganzzahl- und booleschen Literalen oder mit Verweisen auf Symbole mit Ganzzahl- oder booleschem Literaltyp verwenden.

  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)[]
  

Verwenden Sie Typausdrücke in der type-Anweisung. Sie können auch Typausdrücke verwenden, um benutzerdefinierte Datentypen zu erstellen, wie in 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@2025-06-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@2025-06-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Verwenden von Decorator-Elementen

Schreiben Sie Dekoratoren im Format @expression, und platzieren Sie sie über den Deklarationen des benutzerdefinierten Datentyps. In der folgenden Tabelle werden die für benutzerdefinierte Datentypen verfügbaren Decorator-Elemente gezeigt.

Decorators befinden sich im sys-Namespace. Wenn Sie einen Dekorator von einem anderen Element mit dem gleichen Namen unterscheiden müssen, stellen Sie dem Dekorator 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. 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

Legen Sie mindeste und maximale Werte für den ganzzahligen Typ fest. Sie können eine oder beide Einschränkungen festlegen.

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

Längenbeschränkungen

Geben Sie mindeste und maximale Längen für Zeichenfolgen- und Arraytypen an. 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.

Verwenden Sie diesen Decorator, um Informationen über den Datentyp zu erfassen, deren Hinzufügen zu description keinen Sinn ergibt.

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

Wenn Sie einen @metadata() Dekorateur mit einer Eigenschaft bereitstellen, die mit einem anderen Dekorateur in Konflikt steht, ist die widersprüchliche Eigenschaft innerhalb des @metadata() Werts redundant und ersetzt. Weitere Informationen finden Sie unter Keine widersprüchlichen Metadaten.

Versiegelt

Weitere Informationen finden Sie unter 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. 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.

ressourcen-abgeleitete Typen

Mit Bicep können Sie Typen mithilfe der Konstrukte resourceInput<> und resourceOutput<> direkt aus Azure-Ressourcenschemas ableiten. Mithilfe von ressourcen abgeleiteten Typen können Sie Parameter und Variablen anhand eines Teils eines Ressourcentexts überprüfen, anstatt einen benutzerdefinierten Typ zu verwenden. Um diese Konstrukte zu verwenden, benötigen Sie Bicep CLI Version 0.34.1 oder höher.

Vorlagen können Ressourcentypen überall wiederverwenden, wo ein Typ erwartet wird.

resourceInput<'type@version'>

• resourceInput<>: Stellt die beschreibbaren Eigenschaften eines Ressourcentyps dar, wobei alle Eigenschaften entfernt werden, die im ARM-Vorlagenschema als "ReadOnly" gekennzeichnet sind. Es verwendet den Typ, den Sie bei der Ressourcendeklaration angeben müssen.

resourceOutput<'type@version'>

• resourceOutput<>: Stellt die lesbaren Eigenschaften eines Ressourcentyps dar, wobei alle Eigenschaften entfernt werden, die im ARM-Vorlagenschema als WriteOnly gekennzeichnet sind. Sie entspricht dem Typ des Werts, der nach der Bereitstellung der Ressource zurückgegeben wird.

Sie können resourceInput<> oder resourceOutput<> anwenden, um nur einen Teil eines Ressourcenschemas zu extrahieren. Um beispielsweise eine Variable oder einen Parameter basierend auf nur dem kind oder properties eines Speicheraccounts einzugeben:

type accountKind = resourceInput<'Microsoft.Storage/storageAccounts@2024-01-01'>.kind

Das vorangehende Beispiel entspricht folgendem Beispiel:

type accountKind = 'BlobStorage' | 'BlockBlobStorage' | 'FileStorage' | 'Storage' | 'StorageV2'

Das folgende Beispiel zeigt, wie Sie mit resourceInput<> einen typierten Parameter basierend auf der Ressource properties eines Speicherkontos erstellen. Dieser Ansatz definiert einen Parameter, der den schreibbaren Eigenschaften eines Speicherkontos entspricht, wie z. B. accessTier, minimumTlsVersion und andere Eigenschaften:

// Typed parameter using the .properties path of a storage account
param storageAccountProps resourceInput<'Microsoft.Storage/storageAccounts@2023-01-01'>.properties = {
  accessTier: 'Hot'
  minimumTlsVersion: 'TLS1_2'
  allowBlobPublicAccess: false
  supportsHttpsTrafficOnly: true
}

// Resource declaration using the typed parameter
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'mystorageacct123'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: storageAccountProps
}

Das folgende Beispiel zeigt, wie Sie resourceOutput<> verwenden, um eine typisierte Ausgabe basierend auf der Ressource primaryEndPoints eines Speicherkontos zu erstellen.

output storageEndpoints resourceOutput<'Microsoft.Storage/storageAccounts@2024-01-01'>.properties.primaryEndpoints = ...

Im Gegensatz zu benutzerdefinierten Datentypen überprüft Bicep beim Bearbeiten oder Kompilieren einer Datei ressourcenbasierte Typen, aber der ARM-Dienst überprüft sie nicht.

Verwandte Inhalte

Eine Liste der Bicep-Datentypen finden Sie unter Datentypen.