Bicepmoduler

Med Bicep kan du organisera distributioner i moduler. En modul är en Bicep-fil som en annan Bicep-fil distribuerar. En modul kan också vara en Azure Resource Manager-mall (ARM-mall) för JSON. Med hjälp av moduler kan du förbättra läsbarheten för dina Bicep filer genom att kapsla in komplex information om distributionen. Du kan också enkelt återanvända moduler för olika distributioner.

Om du vill dela moduler med andra personer i din organisation skapar du en mallspecifikation eller ett privat register. Mallspecifikationer och moduler i registret är endast tillgängliga för användare med rätt behörigheter.

Bicep-moduler konverteras till en enda ARM-mall med kapslade mallar. Mer information om hur Bicep löser konfigurationsfiler och hur Bicep sammanfogar en användardefinierad konfigurationsfil med standardkonfigurationsfilen finns i Konfigurationsfilmatchningsprocess och Sammanslagningsprocess för konfigurationsfiler.

Definiera moduler

Den grundläggande syntaxen för att definiera en modul är:

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Ett enkelt, verkligt exempel ser ut så här:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Du kan också använda en ARM-mall för JSON som en modul:

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Använd det symboliska namnet för att referera till modulen i en annan del av Bicep-filen. Du kan till exempel använda det symboliska namnet för att hämta utdata från en modul. Det symboliska namnet kan innehålla a-z, A-Z, 0-9 och understreck (_). Namnet kan inte börja med ett tal. En modul kan inte ha samma namn som en parameter, variabel eller resurs.

Sökvägen kan vara antingen en lokal fil eller en fil i ett register. Den lokala filen kan vara antingen en Bicep-fil eller en ARM-mall för JSON. Mer information finns i Sökväg till en modul.

Egenskapen name är valfri. Det blir namnet på den kapslade distributionsresursen i den genererade mallen. Om inget namn anges genereras ett GUID som namn på den kapslade distributionsresursen.

Om du distribuerar en modul med ett statiskt namn samtidigt till samma omfång kan en distribution störa utdata från den andra distributionen. Om två Bicep-filer till exempel använder samma modul med samma statiska namn (examplemodule) och är riktade till samma resursgrupp kan en distribution visa fel utdata. Om du är orolig för samtidiga distributioner till samma omfång ger du modulen ett unikt namn. Ett annat sätt att säkerställa unika modulnamn är att utelämna egenskapen name; då genereras ett unikt modulnamn automatiskt. Linterregeln no-module-name är utformad för att framtvinga den här renare kodningspraxis genom att flagga alla moduler som fortfarande innehåller en explicit name egenskap.

I följande exempel sammanfogas distributionsnamnet till modulnamnet. Om du anger ett unikt namn för distributionen är modulnamnet också unikt.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

Det är också giltigt att inte ange något modulnamn. Ett GUID genereras som modulnamnet.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Om du behöver ange ett omfång som skiljer sig från omfånget för huvudfilen lägger du till omfångsegenskapen. Mer information finns i Ange modulomfång.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Om du vill distribuera en modul villkorligt lägger du till ett if uttryck. Detta liknar villkorlig distribution av en resurs.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Om du vill distribuera mer än en instans av en modul lägger du till uttrycket for . Använd dekoratören batchSize för att ange om instanserna ska distribueras seriellt eller parallellt. För mer information, se Iterativa loopar i Bicep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

Precis som resurser distribueras moduler parallellt såvida de inte är beroende av andra moduler eller resurser. Vanligtvis behöver du inte ange beroenden eftersom de bestäms implicit. Om du behöver ange ett explicit beroende lägger du till dependsOn moduldefinitionen. Mer information om beroenden finns i Resursberoenden i Bicep.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Sökväg till en modul

Du kan använda antingen en lokal fil eller en extern fil för modulen. Du hittar den externa filen i en mallspecifikation eller ett Bicep modulregister.

Lokal fil

Om modulen är en lokal fil anger du en relativ sökväg till filen. I Bicep måste du använda katalogavgränsaren för snedstreck (/) för alla sökvägar för att säkerställa konsekvent kompilering mellan plattformar. Windows-backslash (\) stöds inte. Sökvägar kan innehålla blanksteg.

Om du vill distribuera en fil som är en nivå upp i katalogen från huvudfilen använder du följande exempel:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Fil i registret

Det finns offentliga och privata modulregister.

Register över offentliga moduler

Azure-verifierade moduler är fördefinierade, förtestade och förverifierade moduler som du kan använda för att distribuera resurser i Azure. Microsoft-anställda har skapat och äger dessa moduler. De förenklar och påskyndar distributionsprocessen för vanliga Azure resurser och konfigurationer. Modulerna överensstämmer också med metodtips som Azure Well-Architected Framework.

Bläddra Bicep moduler för att se listan över tillgängliga moduler. Välj de markerade numren i följande skärmbild för att gå direkt till den filtrerade vyn:

Modullistan visar den senaste versionen. Välj versionsnumret för att se en lista över tillgängliga versioner.

Om du vill länka till en offentlig modul anger du modulsökvägen med följande syntax:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

• br/public: Det här är aliaset för offentliga moduler. Du kan anpassa det här aliaset i Bicep-konfigurationsfilen.
• filsökväg: Detta kan innehålla segment som du separerar med / tecknet.
• tag: Detta anger en version för modulen.

Till exempel:

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Privat modulregister

Om du har publicerat en modul till ett register kan du länka till den modulen. Ange namnet på Azure-containerregistret och en sökväg till modulen. Ange modulsökvägen med följande syntax:

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

• br: Det här är ett schemanamn för ett Bicep-register.
• filsökväg: Detta anropas repository i Azure Container Registry. Filsökvägen kan innehålla segment som avgränsas med / tecknet.
• tag: Detta anger en version för modulen.

Till exempel:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

När du refererar till en modul i ett register anropar bicep restore Bicep-tillägget i Visual Studio Code automatiskt för att kopiera den externa modulen till den lokala cachen. Det tar en stund att återställa den externa modulen. Om IntelliSense för modulen inte fungerar omedelbart väntar du tills återställningen har slutförts.

Den fullständiga sökvägen för en modul i ett register kan vara lång. I stället för att ange den fullständiga sökvägen varje gång du vill använda modulen konfigurerar du alias i filen bicepconfig.json. Aliasen gör det enklare att referera till modulen. Med ett alias kan du till exempel förkorta sökvägen till:

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Det offentliga modulregistret har ett fördefinierat alias:

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Du kan åsidosätta det offentliga aliaset i filenbicepconfig.json .

Från och med Bicep CLI v0.43.1 blockerar Bicep uttryckligen användningen av anpassade domäner när du refererar till eller återställer moduler från en Azure Container Registry (ACR). Det här skyddet förhindrar användning av konfigurationer som inte stöds och som annars skulle orsaka efterlevnadsproblem.

Om du försöker referera till en anpassad domän, till exempel moduleStore.myCompany.com, returnerar Bicep CLI diagnostikfelet BCP446. Till exempel:

module foo 'br:moduleStore.myCompany.com/networking/hub:1.0.0' = { ... }

Bicep verifierar alla värdnamn för register mot en inbyggd tillåtelselista. För närvarande är endast följande domäner tillåtna:

• *.azurecr.io
• *.azurecr.cn
• *.azurecr.us
• mcr.microsoft.com
• mcr.azure.cn
• ghcr.io

Om din organisation använder anpassade domäner uppdaterar du dina Bicep filer så att de uppfyller dessa begränsningar:

• Återgå till interna värdnamn: Uppdatera alla Bicep-modulreferenser för att använda den interna .azurecr.io (eller relevanta molnspecifika) domänen.
• Rensa lokal cache: När du har uppdaterat dina referenser kan du behöva rensa cacheminnet för den lokala modulen. Kör bicep restore igen för att hämta modulerna med hjälp av de korrigerade interna värdnamnen.

Fil i mallspecifikation

När du har skapat en mallspecifikation länkar du till mallspecifikationen i en modul. Ange mallspecifikationen i följande format:

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

För att förenkla Bicep-filen skapar du ett alias för resursgruppen som innehåller mallspecifikationerna. När du använder ett alias blir syntaxen:

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

Följande modul distribuerar en mallspecifikation för att skapa ett lagringskonto. Prenumerationen och resursgruppen för mallspecifikationen definieras i aliaset med namnet ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Använda dekoratörer

Skriv dekoratörer i formatet @expression och placera dem ovanför moduldeklarationer. I följande tabell visas tillgängliga dekoratörer för moduler:

Dekoratorer finns i sys-namnområdet. Om du behöver särskilja en dekoratör från ett annat objekt med samma namn, prefixet dekoratören med sys. Om din Bicep-fil till exempel innehåller en parameter med namnet descriptionmåste du lägga till sys namnområdet när du använder dekoratören description .

BatchSize

Du kan använda @batchSize() på en resurs- eller moduldefinition som använder ett for-uttryck.

Som standard distribuerar distributionsmotorn moduler parallellt. När du lägger till dekoratören @batchSize(int) distribuerar du instanser seriellt.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Mer information finns i Distribuera i batchar.

Description

Lägg till en förklaring genom att lägga till en beskrivning i moduldeklarationer. Till exempel:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

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

Parameters

De parametrar som du anger i moduldefinitionen matchar parametrarna i Bicep-filen.

Följande Bicep-exempel har tre parametrar: storagePrefix, storageSKUoch location. Parametern storageSKU har ett standardvärde, så du behöver inte ange något värde för parametern under distributionen.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Om du vill använda föregående exempel som en modul anger du värden för dessa parametrar.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Ange modulomfång

När du deklarerar en modul anger du ett omfång för modulen som skiljer sig från omfånget för den Bicep fil som innehåller den. Använd egenskapen scope för att ange modulens omfång. När du inte anger egenskapen scope, distribueras modulen till den överordnade resursens målomfång.

Följande Bicep-fil skapar en resursgrupp och ett lagringskonto i den resursgruppen. Filen distribueras till en prenumeration, men modulen är begränsad till den nya resursgruppen.

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2025-04-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

I nästa exempel distribueras lagringskonton till två olika resursgrupper. Båda dessa resursgrupper måste redan finnas.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

Ange egenskapen scope till ett giltigt omfångsobjekt. Om din Bicep fil distribuerar en resursgrupp, prenumeration eller hanteringsgrupp anger du omfånget för en modul till det symboliska namnet på resursen. Eller använd omfattningsfunktionerna för att få en giltig omfattning.

De här funktionerna är:

• resourceGroup
• subscription
• managementGroup
• tenant

I följande exempel används managementGroup funktionen för att ange omfånget.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Output

Du kan hämta värden från en modul och använda dem i huvudfilen för Bicep. Om du vill hämta ett utdatavärde från en modul använder du outputs egenskapen för modulobjektet.

Det första exemplet skapar ett lagringskonto och returnerar de primära slutpunkterna:

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

När du använder egenskapen som en modul kan du hämta utdatavärdet:

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Genom att använda Bicep version 0.35.1 eller senare kan du använda dekoratören @secure() på modulutdata för att markera dem som känsliga, vilket säkerställer att deras värden inte exponeras i loggar eller distributionshistorik. Den här metoden är användbar när en modul behöver returnera känsliga data, till exempel en genererad nyckel eller reťazec pripojenia, till den överordnade Bicep filen utan att riskera exponering. Mer information finns i Säkra utdata.

Modulidentitet

Från och med Bicep version 0.36.1 kan du tilldela en användartilldelad hanterad identitet till en modul. Den här identiteten är tillgänglig i modulen , till exempel för att få åtkomst till en Key Vault. Serverdelstjänster har dock ännu inte stöd för den här funktionen.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

Relaterat innehåll

• Om du vill skicka ett känsligt värde till en modul använder du getSecret funktionen.