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

Utbildningsresurser

Om du vill lära dig mer om moduler via stegvis vägledning kan du läsa Skapa komposterbara Bicep-filer med hjälp av moduler.

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 en modul med ett statiskt namn distribueras samtidigt till samma omfång finns det potential att en distribution stör 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; ett unikt modulnamn genereras automatiskt.

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 modulnamn.

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

Filen för modulen kan vara antingen en lokal fil eller en extern fil. Den externa filen kan finnas i en mallspecifikation eller i ett Bicep-modulregister.

Lokal fil

Om modulen är en lokal fil anger du en relativ sökväg till filen. Alla sökvägar i Bicep måste specificeras med snedstreck (/) som katalogavgränsare för att säkerställa konsekvent kompilering över olika plattformar. Windows-backslash (\) stöds inte. Sökvägar kan innehålla blanksteg.

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

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 har utformats för att förenkla och påskynda distributionsprocessen för vanliga Azure-resurser och konfigurationer. Modulerna överensstämmer också med metodtips som Azure Well-Architected Framework.

Bläddra bland 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 kan separera med / tecknet.
• tag: Detta används för att ange 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: Används för att ange 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 .

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

Dekoratörer är skrivna i formatet @expression och placeras 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 skilja en dekoratör från ett annat objekt med samma namn, ange dekoratören med sys först. 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 distribueras 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-01-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 egenskapen scope inte anges distribueras modulen i det överordnade målområdet.

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 kan du ange omfånget för en modul till det symboliska namnet för resursen. Eller så kan du använda omfångsfunktionerna för att få ett giltigt omfång.

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-01-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

När egenskapen används 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

Med Bicep version 0.35.1 och senare @secure() kan dekoratören tillämpas på modulutdata för att markera dem som känsliga, vilket säkerställer att deras värden inte exponeras i loggar eller distributionshistorik. Detta är användbart när en modul behöver returnera känsliga data, till exempel en genererad nyckel eller anslutningssträng, 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. Detta gör identiteten tillgänglig i modulen, till exempel för att få åtkomst till ett Key Vault. Den här funktionen är dock avsedd för framtida användning och stöds ännu inte av serverdelstjänster.

param identityId string

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

Relaterat innehåll

• För en handledning, se Skapa din första Bicep-fil.
• Om du vill skicka ett känsligt värde till en modul använder du getSecret funktionen.