Användardefinierade datatyper i Bicep

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.

Linterregeln use-user-defined-types uppmuntrar till användning av användardefinierade datatyper i stället för de allmänna object eller array typerna.

Definiera typer

Använd -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 är endast tillåten på param satser. Om du vill deklarera en typ med en uppsättning fördefinierade värden i en typeanvänder du syntax för unionstyp.

Giltiga typuttryck är:

Symboliska referenser

Symboliska referenser är identifierare som refererar till en omgivande typ (t.exstring. 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 litteraler

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

Matristyper

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

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

Union-typer

Med en unionstyp kan du skapa en kombinerad typ som består av en uppsättning undertyper. Ett värde matchar typen om det matchar någon av undertyperna. Använd röroperatorn (|) för att separera de enskilda medlemstyperna. Bicep översätter unionstyper till begränsningen för tillåtna värden, så endast literaler tillåts som element. Unioner kan innehålla valfritt antal literaltypade uttryck.

type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}

Du kan deklarera unionstyper direkt, och en medlem kan vara en referens till en annan symbol med literaltyp.

Unioner av blandad typ

Medlemstyperna behöver inte vara samma typ av literal. En union kan kombinera strängar, heltal, booleska objekt och null literaler.

type mixedType = 'fizz' | 42 | { an: 'object' } | null

Objekttyper

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 är obligatoriska om de inte följs av markeringen för valfrihet ? efter egenskapsvärdet. Egenskapen i följande exempel är till exempel sku valfri:

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

Du kan använda dekoratorer 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 lista en uppsättning fördefinierade värden:

type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}

Rekursion

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 är inte giltig eftersom ingen av level1, level2, level3, level4eller level5 är valfri.

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

Unary-operatorer

Använd Bicep unary-operatorer med heltal och booleska literaler eller referenser till heltal eller booleska literaltypade symboler.

type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral

Unioner kan innehålla valfritt antal literaltypade uttryck. Bicep översätter unionstyper till begränsningen för tillåtna värden, vilket innebär att endast literaler tillåts som medlemmar.

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

Använd typuttryck i type-satsen. Du kan också använda typuttryck för att skapa användardefinierade datatyper, som du ser på följande platser.

• Som typvillkoret i en param-sats. 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 matristypsuttryck. 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@2025-06-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@2025-06-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Använd dekoratörer

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

Dekoratörer finns i sys-namnområdet. Om du behöver skilja en dekoratör från ett annat objekt med samma namn, föregå 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 .

Diskriminator

Se Taggad union-datatyp.

beskrivning

Lägg till en beskrivning i den användardefinierade datatypen. Du kan använda dekoratorer 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

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

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

Längdbegränsningar

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

Metainformation

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.

Använd 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 anger en @metadata() dekoratör med en egenskap som står i konflikt med en annan dekoratör, är den motstridiga egenskapen i @metadata() värdet redundant och ersatt. Mer information finns i Inga motstridiga metadata.

Stängd

Se Höj felnivån.

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. Till exempel är den följande Bicep giltig men ger upphov till varningen [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 unionsdatatyp

Om du vill deklarera en anpassad taggad unionsdatatyp i en Bicep-fil kan du placera en discriminator-dekorator 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 unionsdatatyp.

Resursbaserade typer

Bicep gör det möjligt att härleda typer direkt från Azure-resursscheman genom att använda konstruktionerna resourceInput<> och resourceOutput<>. Genom att använda resursbaserade typer kan du kontrollera parametrar och variabler mot en del av en resurstext i stället för att använda en anpassad typ. Om du vill använda dessa konstruktioner behöver du Bicep CLI version 0.34.1 eller senare.

Mallar kan återanvända resurstyper där en typ förväntas.

resourceInput<'type@version'>

• resourceInput<>: Representerar skrivbara egenskaper för en resurstyp och tar bort alla egenskaper som har markerats som ReadOnly i ARM-mallschemat. Den använder den typ som du behöver ange i resursdeklarationen.

resourceOutput<'type@version'>

• resourceOutput<>: Representerar de läsbara egenskaperna för en resurstyp och tar bort alla egenskaper som markerats som WriteOnly i ARM-mallschemat. Den matchar den typ av värde som returneras när resursen har tillhandahållits.

Du kan bara använda resourceInput<> eller resourceOutput<> extrahera en del av ett resursschema. Om du till exempel vill skriva en variabel eller parameter baserat på bara kind eller properties för ett lagringskonto:

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

Föregående exempel motsvarar:

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

I följande exempel visas hur du använder resourceInput<> för att skapa en typad parameter baserat på properties en lagringskontoresurs. Den här metoden definierar en parameter som matchar de skrivbara egenskaperna för ett lagringskonto, till exempel accessTier, minimumTlsVersionoch andra egenskaper:

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

I följande exempel visas hur du använder resourceOutput<> för att skapa ett typat utdata baserat på primaryEndPoints för en lagringskontoresurs.

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

Till skillnad från användardefinierade datatyper kontrollerar Bicep resursbaserade typer när du redigerar eller kompilerar en fil, men ARM-tjänsten kontrollerar dem inte.

Relaterat innehåll

En lista över Bicep-datatyperna finns i Datatyper.