Door de gebruiker gedefinieerde gegevenstypen in Bicep

Informatie over het maken van door de gebruiker gedefinieerde gegevenstypen in Bicep. Zie Gegevenstypen voor door het systeem gedefinieerde gegevenstypen. Als u door de gebruiker gedefinieerde gegevenstypen gebruikt, wordt taalversie 2.0-code automatisch gegenereerd.

Bicep CLI versie 0.12.X of hoger is vereist voor het gebruik van deze functie.

Typen definiëren

U kunt de instructie gebruiken om door de type gebruiker gedefinieerde gegevenstypen te maken. U kunt op sommige plaatsen ook typeexpressies gebruiken om aangepaste typen te definiëren.

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

De @allowed decorator is alleen toegestaan op param instructies. Als u een type wilt declareren met een set vooraf gedefinieerde waarden in een type, gebruikt u de syntaxis van het samenvoegtype.

De geldige typeexpressies zijn onder andere:

• Symbolische verwijzingen zijn id's die verwijzen naar een omgevingstype (zoals string of int) of een door de gebruiker gedefinieerd typesymbool dat in een type instructie is gedeclareerd:

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

• Primitieve letterlijke waarden, waaronder tekenreeksen, gehele getallen en Booleaanse waarden, zijn geldige typeexpressies. Voorbeeld:

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

• U kunt matrixtypen declareren door een geldige typeexpressie toe te [] voegen:

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

• Objecttypen bevatten nul of meer eigenschappen tussen accolades:

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  Elke eigenschap in een object bestaat uit een sleutel en een waarde gescheiden door een dubbele punt :. De sleutel kan elke tekenreeks zijn, met niet-id-waarden tussen aanhalingstekens. De waarde kan elk type expressie zijn.

  Eigenschappen zijn vereist, tenzij ze een optionele markering ? hebben na de eigenschapswaarde. De sku eigenschap in het volgende voorbeeld is bijvoorbeeld optioneel:

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

  U kunt decorators gebruiken voor eigenschappen. U kunt een sterretje (*) gebruiken om ervoor te zorgen dat alle waarden een beperking vereisen. U kunt meer eigenschappen definiëren met behulp van *. In dit voorbeeld wordt een object gemaakt waarvoor een sleutel van het type int met de naam idis vereist. Alle andere vermeldingen in het object moeten een tekenreekswaarde van ten minste 10 tekens lang zijn.

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

  In het volgende voorbeeld ziet u hoe u de syntaxis van het samenvoegtype gebruikt om een set vooraf gedefinieerde waarden weer te geven:

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

• Objecttypen kunnen directe of indirecte recursie gebruiken als ten minste het been van het pad naar het recursiepunt optioneel is. De definitie in het volgende voorbeeld is bijvoorbeeld myObjectType geldig omdat de rechtstreeks recursieve recursiveProp eigenschap optioneel is:

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

  De volgende typedefinitie is niet geldig omdat geen vanlevel1, level2, level3of level4level5 optioneel is.

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

• U kunt Bicep unaire operatoren gebruiken met geheel getal- en Booleaanse letterlijke waarden of verwijzingen naar geheel getal- of Booleaanse letterlijke symbolen:

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

• Samenvoegingen kunnen een willekeurig aantal letterlijk getypte expressies bevatten. Samenvoegtypen worden omgezet in de beperking voor toegestane waarden in Bicep, zodat alleen letterlijke waarden zijn toegestaan als leden.

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

U kunt typeexpressies in de type instructie gebruiken en u kunt ook typeexpressies gebruiken om door de gebruiker gedefinieerde gegevenstypen te maken, zoals wordt weergegeven op de volgende plaatsen:

• Als de typecomponent van een param instructie. Voorbeeld:

  param storageAccountConfig {
    name: string
    sku: string
  }
  

• Volg de : eigenschap in een objecttype. Voorbeeld:

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

• Voorafgaande aan de [] expressie van een matrixtype. Voorbeeld:

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

Een typisch Bicep-bestand voor het maken van een opslagaccount ziet er als volgt uit:

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

Met door de gebruiker gedefinieerde gegevenstypen kan deze er als volgt uitzien:

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

Decorators gebruiken

Decorators worden geschreven in de indeling @expression en worden boven de declaraties van het door de gebruiker gedefinieerde gegevenstype geplaatst. In de volgende tabel ziet u de beschikbare decorators voor door de gebruiker gedefinieerde gegevenstypen.

Decorateur	Van toepassing op	Argument	Beschrijving
beschrijving	Alles	tekenreeks	Geef beschrijvingen op voor het door de gebruiker gedefinieerde gegevenstype.
Discriminator	object	tekenreeks	Gebruik deze decorator om ervoor te zorgen dat de juiste subklasse wordt geïdentificeerd en beheerd.
exporteren	Alles	Geen	Geeft aan dat het door de gebruiker gedefinieerde gegevenstype beschikbaar is voor importeren door een ander Bicep-bestand.
maxLength	matrix, tekenreeks	int	De maximale lengte voor tekenreeks- en matrixgegevenstypen. De waarde is inclusief.
maxValue	int	int	De maximumwaarde voor de gegevenstypen geheel getal. Deze waarde is inclusief.
metagegevens	Alles	object	Aangepaste eigenschappen die moeten worden toegepast op de gegevenstypen. Kan een beschrijvingseigenschap bevatten die gelijk is aan de beschrijvingsdecorator.
minLength	matrix, tekenreeks	int	De minimale lengte voor tekenreeks- en matrixgegevenstypen. De waarde is inclusief.
minValue	int	int	De minimumwaarde voor de gegevenstypen voor gehele getallen. Deze waarde is inclusief.
Verzegeld	object	Geen	Verhoog BCP089 van een waarschuwing naar een fout wanneer een eigenschapsnaam van een door de gebruiker gedefinieerd gegevenstype waarschijnlijk een typefout is. Zie Foutniveau verhogen voor meer informatie.
veilig	tekenreeks, object	Geen	Markeert de typen als veilig. De waarde voor een beveiligd type wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd. Zie Beveiligde tekenreeksen en objecten voor meer informatie.

Decorators bevinden zich in de sys-naamruimte. Als u een decorator wilt onderscheiden van een ander item met dezelfde naam, moet u de decorator vooraf laten gaan door sys. Als uw Bicep-bestand bijvoorbeeld een variabele met de naam descriptionbevat, moet u de sys naamruimte toevoegen wanneer u de description decorator gebruikt.

Discriminator

Zie Gegevenstype Gelabelde samenvoeging.

Beschrijving

Voeg een beschrijving toe aan het door de gebruiker gedefinieerde gegevenstype. U kunt decorators gebruiken voor eigenschappen. Voorbeeld:

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

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

U kunt markdown-opgemaakte tekst gebruiken voor de beschrijvingstekst.

Export

Gebruik @export() dit om het door de gebruiker gedefinieerde gegevenstype te delen met andere Bicep-bestanden. Zie Variabelen, typen en functies exporteren voor meer informatie.

Beperkingen voor gehele getallen

U kunt minimum- en maximumwaarden instellen voor het type geheel getal. U kunt een of beide beperkingen instellen.

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

Lengtebeperkingen

U kunt minimum- en maximumlengten opgeven voor tekenreeks- en matrixtypen. U kunt een of beide beperkingen instellen. Voor tekenreeksen geeft de lengte het aantal tekens aan. Voor matrices geeft de lengte het aantal items in de matrix aan.

In het volgende voorbeeld worden twee typen declareren. Eén type is voor een opslagaccountnaam die 3 tot 24 tekens moet bevatten. Het andere type is een matrix die van één tot vijf items moet bevatten.

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

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

Metagegevens

Als u aangepaste eigenschappen hebt die u wilt toepassen op een door de gebruiker gedefinieerd gegevenstype, voegt u een decorator voor metagegevens toe. Definieer binnen de metagegevens een object met de aangepaste namen en waarden. Het object dat u definieert voor de metagegevens kan eigenschappen van elke naam en elk type bevatten.

U kunt deze decorator gebruiken om informatie bij te houden over het gegevenstype dat niet zinvol is om aan de beschrijving toe te voegen.

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

Wanneer u een @metadata() decorator verstrekt met een eigenschap die conflicteert met een andere decorator, heeft die decorator altijd voorrang op iets in de @metadata() decorator. De conflicterende eigenschap in de @metadata() waarde is dus redundant en wordt vervangen. Zie Geen conflicterende metagegevens voor meer informatie.

Verzegeld

Zie Foutniveau verhogen.

Beveiligde typen

U kunt een door de gebruiker gedefinieerd gegevenstype voor een tekenreeks of object als veilig markeren. De waarde van een beveiligd type wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Foutniveau verhogen

Standaard kan het declareren van een objecttype in Bicep meer eigenschappen van elk type accepteren. De volgende Bicep is bijvoorbeeld geldig, maar geeft een waarschuwing van [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'
}

De waarschuwing geeft aan dat het anObject type geen eigenschap met de naam otionalPropertybevat. Hoewel er geen fouten optreden tijdens de implementatie, gaat de Bicep-compiler ervan uit dat dit otionalProperty een typefout is en dat u deze wilt gebruiken optionalProperty , maar verkeerd gespeld. Bicep waarschuwt u voor de inconsistentie.

Als u deze waarschuwingen wilt escaleren op fouten, past u de @sealed() decorator toe op het objecttype:

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

U krijgt dezelfde resultaten door de @sealed() decorator toe te passen op de param declaratie:

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

De Implementatie-engine van Azure Resource Manager controleert ook verzegelde typen voor andere eigenschappen. Als u extra eigenschappen voor verzegelde parameters opgeeft, treedt er een validatiefout op, waardoor de implementatie mislukt. Voorbeeld:

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

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

Gegevenstype gelabelde samenvoeging

Als u een aangepast getagd gegevenstype in een Bicep-bestand wilt declareren, kunt u een discriminator decorator plaatsen boven een door de gebruiker gedefinieerde typedeclaratie. Bicep CLI versie 0.21.X of hoger is vereist voor het gebruik van deze decorator. In het volgende voorbeeld ziet u hoe u een getagd gegevenstype voor een samenvoeging declareert:

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

Zie Aangepast gegevenstype voor getagde samenvoeging voor meer informatie.

Gerelateerde inhoud

Zie Gegevenstypen voor een lijst met de Bicep-gegevenstypen.