Användardefinierade datatyper i Bicep

Artikel
10/29/2024

Lär dig hur du skapar användardefinierade datatyper i Bicep. Information om systemdefinierade datatyper finns i Datatyper. Om du använder användardefinierade datatyper aktiveras automatiskt språkversion 2.0-kodgenerering .

Bicep CLI version 0.12.X eller senare krävs för att använda den här funktionen.

Definiera typer

Du kan använda -instruktionen type för att skapa användardefinierade datatyper. Du kan också använda typuttryck på vissa platser för att definiera anpassade typer.

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

Dekoratören @allowed tillåts endast på param instruktioner. Om du vill deklarera en typ med en uppsättning fördefinierade värden i en typeanvänder du syntax för unionstyp.

De giltiga typuttrycken är:

Symboliska referenser är identifierare som refererar till en omgivande typ (som string eller int) eller en användardefinierad typsymbol som deklareras i en type instruktion:
```
// Bicep data type reference
type myStringType = string

// user-defined type reference
type myOtherStringType = myStringType
```

Primitiva literaler, inklusive strängar, heltal och booleska, är giltiga typuttryck. Till exempel:

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

Du kan deklarera matristyper genom att lägga [] till valfritt giltigt typuttryck:

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

Objekttyper innehåller noll eller fler egenskaper mellan klammerparenteser:
```
type storageAccountConfigType = {
  name: string
  sku: string
}
```
Varje egenskap i ett objekt består av en nyckel och ett värde avgränsat med ett kolon :. Nyckeln kan vara valfri sträng, med värden som inte är identifierade inom citattecken. Värdet kan vara vilken typ av uttryck som helst.

Egenskaper krävs om de inte har en valfrihetsmarkör ? efter egenskapsvärdet. Egenskapen i följande exempel är till exempel sku valfri:
```
type storageAccountConfigType = {
  name: string
  sku: string?
}
```
Du kan använda dekoratörer på egenskaper. Du kan använda en asterisk (*) för att göra så att alla värden kräver en begränsning. Du kan definiera fler egenskaper med hjälp *av . Det här exemplet skapar ett objekt som kräver en nyckel av typen int med namnet id. Alla andra poster i objektet måste vara ett strängvärde som är minst 10 tecken långt.
```
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}
```
Följande exempel visar hur du använder syntaxen för unionstyp för att visa en uppsättning fördefinierade värden:
```
type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}
```
Objekttyper kan använda direkt eller indirekt rekursion om åtminstone delen av sökvägen till rekursionspunkten är valfri. Definitionen i följande exempel är till exempel myObjectType giltig eftersom den direkt rekursiva recursiveProp egenskapen är valfri:
```
type myObjectType = {
  stringProp: string
  recursiveProp: myObjectType?
}
```
Följande typdefinition skulle inte vara giltig eftersom ingen av level1, level2, level3, level4eller level5 är valfri.
```
type invalidRecursiveObjectType = {
  level1: {
    level2: {
      level3: {
        level4: {
          level5: invalidRecursiveObjectType
        }
      }
    }
  }
}
```

Du kan använda Bicep unary-operatorer med heltal och booleska literaler eller referenser till heltal eller boolesk literaltypade symboler:

type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral

Unioner kan innehålla valfritt antal literaltypade uttryck. Union-typer översätts till villkoret allowed-value i Bicep, så endast literaler tillåts som medlemmar.
```
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
```

Du kan använda typuttryck i -instruktionen type och du kan också använda typuttryck för att skapa användardefinierade datatyper, som du ser på följande platser:

Som typsatsen för en param -instruktion. Till exempel:

param storageAccountConfig {
  name: string
  sku: string
}

: Följ egenskapen i en objekttyp. Till exempel:

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

[] Före i ett matristyputtryck. Till exempel:

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

En typisk Bicep-fil för att skapa ett lagringskonto ser ut så här:

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

Med användardefinierade datatyper kan det se ut så här:

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

Använda dekoratörer

Dekoratörer skrivs i formatet @expression och placeras ovanför deklarationerna för den användardefinierade datatypen. I följande tabell visas tillgängliga dekoratörer för användardefinierade datatyper.

Dekoratör	Tillämpa på	Argument	beskrivning
beskrivning	alla	sträng	Ange beskrivningar för den användardefinierade datatypen.
diskriminerande	objekt	sträng	Använd den här dekoratören för att säkerställa att rätt underklass identifieras och hanteras.
export	alla	inget	Anger att den användardefinierade datatypen är tillgänglig för import av en annan Bicep-fil.
maxLength	matris, sträng	heltal	Maximal längd för sträng- och matrisdatatyper. Värdet är inkluderande.
maxValue	heltal	heltal	Det maximala värdet för heltalsdatatyperna. Det här värdet är inkluderande.
metadata	alla	objekt	Anpassade egenskaper som ska tillämpas på datatyperna. Kan innehålla en beskrivningsegenskap som motsvarar beskrivningsdekoratören.
minLength	matris, sträng	heltal	Minsta längd för sträng- och matrisdatatyper. Värdet är inkluderande.
minValue	heltal	heltal	Minsta värde för heltalsdatatyperna. Det här värdet är inkluderande.
stängd	objekt	inget	Höj BCP089 från en varning till ett fel när ett egenskapsnamn för en användardefinierad datatyp sannolikt är ett skrivfel. Mer information finns i Höja felnivån.
säker	sträng, objekt	inget	Markerar typerna som säkra. Värdet för en säker typ sparas inte i distributionshistoriken och loggas inte. Mer information finns i Skydda strängar och objekt.

Dekoratörer finns i sys-namnområdet. Om du behöver skilja en dekoratör från ett annat objekt med samma namn, förorda dekoratören med sys. Om din Bicep-fil till exempel innehåller en variabel med namnet descriptionmåste du lägga till sys namnområdet när du använder dekoratören description .

Diskriminerande

Se Taggad union-datatyp.

beskrivning

Lägg till en beskrivning i den användardefinierade datatypen. Du kan använda dekoratörer på egenskaper. Till exempel:

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

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

Du kan använda Markdown-formaterad text för beskrivningstexten.

Export

Använd @export() för att dela den användardefinierade datatypen med andra Bicep-filer. Mer information finns i Exportera variabler, typer och funktioner.

Heltalsbegränsningar

Du kan ange lägsta och högsta värden för heltalstyp. Du kan ange en eller båda begränsningarna.

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

Längdbegränsningar

Du kan ange minsta och högsta längd för sträng- och matristyper. Du kan ange en eller båda begränsningarna. För strängar anger längden antalet tecken. För matriser anger längden antalet objekt i matrisen.

I följande exempel deklareras två typer. En typ är för ett lagringskontonamn som måste innehålla 3 till 24 tecken. Den andra typen är en matris som måste ha mellan ett och fem objekt.

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

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

Metadata

Om du har anpassade egenskaper som du vill tillämpa på en användardefinierad datatyp lägger du till en metadatadekoratör. I metadata definierar du ett objekt med anpassade namn och värden. Objektet som du definierar för metadata kan innehålla egenskaper för valfritt namn och typ.

Du kan använda den här dekoratören för att spåra information om den datatyp som inte är lämplig att lägga till i beskrivningen.

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

När du ger en @metadata() dekoratör en egenskap som står i konflikt med en annan dekoratör, har den dekoratören alltid företräde framför allt i dekoratören @metadata() . Därför är den motstridiga egenskapen i @metadata() värdet redundant och ersätts. Mer information finns i Inga metadata i konflikt.

Stängd

Mer information finns i Höja felnivå.

Säkra typer

Du kan markera en sträng eller objekt som användardefinierad datatyp som säker. Värdet för en säker typ sparas inte i distributionshistoriken och loggas inte.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Höja felnivån

Om du deklarerar en objekttyp i Bicep kan den som standard acceptera fler egenskaper av vilken typ som helst. Följande Bicep är till exempel giltigt men genererar en varning om [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'
}

Varningen informerar dig om att anObject typen inte innehåller en egenskap med namnet otionalProperty. Även om inga fel uppstår under distributionen förutsätter Bicep-kompilatorn att det otionalProperty är ett stavfel och att du avsåg att använda optionalProperty men felstavade det. Bicep varnar dig för inkonsekvensen.

Om du vill eskalera dessa varningar till fel använder du dekoratören @sealed() på objekttypen:

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

Du får samma resultat genom att tillämpa dekoratören @sealed() på deklarationen param :

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

Azure Resource Manager-distributionsmotorn kontrollerar också förseglade typer för andra egenskaper. Om du anger eventuella extra egenskaper för förseglade parametrar resulterar det i ett valideringsfel som gör att distributionen misslyckas. Till exempel:

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

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

Taggad union-datatyp

Om du vill deklarera en anpassad taggad union-datatyp i en Bicep-fil kan du placera en discriminator dekoratör ovanför en användardefinierad typdeklaration. Bicep CLI version 0.21.X eller senare krävs för att använda den här dekoratören. I följande exempel visas hur du deklarerar en taggad unionsdatatyp:

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

Mer information finns i Anpassad taggad union-datatyp.

En lista över Bicep-datatyperna finns i Datatyper.

Dela via

Användardefinierade datatyper i Bicep

Definiera typer

Använda dekoratörer

Diskriminerande

beskrivning

Export

Heltalsbegränsningar

Längdbegränsningar

Metadata

Stängd

Säkra typer

Höja felnivån

Taggad union-datatyp

Feedback

Ytterligare resurser

Dela via

Användardefinierade datatyper i Bicep

Definiera typer

Använda dekoratörer

Diskriminerande

beskrivning

Export

Heltalsbegränsningar

Längdbegränsningar

Metadata

Stängd

Säkra typer

Höja felnivån

Taggad union-datatyp

Relaterat innehåll

Feedback

Ytterligare resurser