Planera strukturen för din Bicep-fil

  • 7 minuter

Bicep ger dig flexibiliteten att bestämma hur koden ska struktureras. I den här lektionen får du lära dig mer om hur du kan strukturera din Bicep-kod och vikten av ett konsekvent format och en tydlig, begriplig Bicep-kod.

Vilken ordning ska din Bicep-kod följa?

Dina Bicep-mallar kan innehålla många element, inklusive parametrar, variabler, resurser, moduler, utdata och en targetScope för hela mallen. Bicep framtvingar inte en order för dina element att följa. Det är dock viktigt att tänka på ordningen på dina element för att säkerställa att mallen är tydlig och begriplig.

Det finns två huvudsakliga metoder för att beställa koden:

  • Gruppera element efter elementtyp
  • Gruppera element efter resurs

Du och ditt team bör komma överens om en och använda den konsekvent.

Gruppera element efter elementtyp

Du kan gruppera alla element av samma typ tillsammans. Alla parametrar skulle gå på ett ställe, vanligtvis överst i filen. Variablerna kommer härnäst, följt av resurser och moduler, och utdata finns längst ned. Du kan till exempel ha en Bicep-fil som distribuerar en Azure SQL-databas och ett lagringskonto.

När du grupperar dina element efter typ kan de se ut så här:

Diagram som visar element grupperade efter elementtyp. Parametrar grupperas tillsammans, sedan variabler, sedan resurser och sedan utdata.

Dricks

Om du följer den här konventionen bör du överväga att placera targetScope längst upp i filen.

Den här ordningen är lämplig när du är van vid annan infrastruktur som kodspråk (till exempel språket i Azure Resource Manager-mallar). Det kan också göra mallen lätt att förstå eftersom det är tydligt var du ska leta efter specifika typer av element. I längre mallar kan det dock vara svårt att navigera och hoppa mellan elementen.

Du måste fortfarande bestämma hur du ska sortera elementen inom dessa kategorier. Det är en bra idé att gruppera relaterade parametrar tillsammans. Till exempel hör alla parametrar som handlar om ett lagringskonto ihop och inom det hör lagringskontots SKU-parametrar ihop.

På samma sätt kan du gruppera relaterade resurser tillsammans. Det hjälper alla som använder mallen att snabbt navigera i den och förstå de viktiga delarna i mallen.

Ibland skapar du en mall som distribuerar en primär resurs med flera sekundära stödresurser. Du kan till exempel skapa en mall för att distribuera en webbplats som finns i Azure App Service. Den primära resursen är App Service-appen. Sekundära resurser i samma mall kan innehålla App Service-planen, lagringskontot, Application Insights-instansen och andra. När du har en mall som den här är det en bra idé att placera den primära resursen eller resurserna högst upp i resursavsnittet i mallen, så att alla som öppnar mallen snabbt kan identifiera mallens syfte och hitta viktiga resurser.

Gruppera element efter resurs

Du kan också gruppera dina element baserat på vilken typ av resurser du distribuerar. Om du fortsätter med föregående exempel kan du gruppera alla parametrar, variabler, resurser och utdata som är relaterade till Azure SQL-databasresurserna. Du kan sedan lägga till parametrar, variabler, resurser och utdata för lagringskontot enligt följande:

Diagram som visar element grupperade efter resurs. Lagringskontoelement grupperas, följt av Azure SQL-databaselement.

Gruppering efter resurs kan göra det enklare att läsa mallen eftersom alla element som du behöver för en specifik resurs finns på ett och samma ställe. Det gör det dock svårare att snabbt kontrollera hur specifika elementtyper deklareras när du till exempel vill granska alla parametrar.

Du måste också överväga hur du ska hantera parametrar och variabler som är gemensamma för flera resurser, till exempel en environmentType parameter när du använder en konfigurationskarta. Vanliga parametrar och variabler bör placeras tillsammans, vanligtvis överst i Bicep-filen.

Dricks

Fundera på om det kan vara mer meningsfullt att skapa moduler för grupper av relaterade resurser och sedan använda en enklare mall för att kombinera modulerna. Vi går igenom Bicep-moduler i detalj i utbildningsvägarna för Bicep.

Hur kan tomt utrymme bidra till att skapa struktur?

Tomma rader eller tomt utrymme kan hjälpa dig att lägga till visuell struktur i mallen. Genom att använda blanksteg eftertänksamt kan du gruppera avsnitten i din Bicep-kod logiskt, vilket i sin tur kan hjälpa till att klargöra relationerna mellan resurser. Det gör du genom att lägga till en tom rad mellan huvudavsnitt, oavsett vilket grupperingsformat du föredrar.

Hur definierar du flera liknande resurser?

Med Bicep kan du använda loopar för att distribuera liknande resurser från en enda definition. Genom att använda nyckelordet for för att definiera resursloopar kan du göra din Bicep-kod renare och minska onödig duplicering av resursdefinitioner. I framtiden, när du behöver ändra definitionen av dina resurser, uppdaterar du bara en plats. När Azure Resource Manager distribuerar dina resurser distribueras som standard alla resurser i loopen samtidigt, så att distributionen är så effektiv som möjligt.

Leta efter platser där du definierar flera resurser som är identiska eller som har få skillnader i deras egenskaper. Lägg sedan till en variabel för att lista de resurser som ska skapas, tillsammans med de egenskaper som skiljer sig från de andra resurserna. I följande exempel används en loop för att definiera en uppsättning Azure Cosmos DB-containrar, som var och en har sitt eget namn och sin partitionsnyckel:

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Hur distribuerar du endast resurser till vissa miljöer?

Ibland definierar du resurser som endast ska distribueras till specifika miljöer eller under vissa förhållanden. Genom att använda nyckelordet if kan du selektivt distribuera resurser baserat på ett parametervärde, en konfigurationsmappningsvariabel eller ett annat villkor. I följande exempel används en konfigurationskarta för att distribuera loggningsresurser för produktionsmiljöer, men inte för testmiljöer:

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Hur uttrycker du beroenden mellan dina resurser?

I alla komplexa Bicep-mallar måste du uttrycka beroenden mellan dina resurser. När Bicep förstår beroendena mellan dina resurser distribueras de i rätt ordning.

Med Bicep kan du uttryckligen ange ett beroende med hjälp dependsOn av egenskapen . I de flesta fall är det dock möjligt att låta Bicep automatiskt identifiera beroenden. När du använder det symboliska namnet på en resurs i en egenskap för en annan identifierar Bicep relationen. Det är bättre att låta Bicep hantera dessa själv när du kan. På så sätt ser Bicep till att beroendena alltid är korrekta när du ändrar mallen och att du inte lägger till onödig kod som gör mallen mer besvärlig och svårare att läsa.

Hur uttrycker du relationer mellan överordnade och underordnade?

Azure Resource Manager och Bicep har begreppet underordnade resurser, vilket bara är meningsfullt när de distribueras inom ramen för deras överordnade. En Azure SQL-databas är till exempel underordnad en SQL Server-instans. Det finns flera sätt att definiera underordnade resurser, men i de flesta fall är det en bra idé att använda egenskapen parent . Detta hjälper Bicep att förstå relationen så att den kan tillhandahålla validering i Visual Studio Code och gör relationen tydlig för alla andra som läser mallen.

Hur ställer du in resursegenskaper?

Du måste ange värdena för resursegenskaper i dina Bicep-filer. Det är en bra idé att tänka på när du hårdkodar värden i dina resursdefinitioner. Om du vet att värdena inte ändras kan hårdkodning vara bättre än att använda en annan parameter som gör mallen svårare att testa och arbeta med. Om värdena kan ändras kan du dock överväga att definiera dem som parametrar eller variabler för att göra din Bicep-kod mer dynamisk och återanvändbar.

När du gör hårdkodade värden är det bra att se till att de är begripliga för andra. Om en egenskap till exempel måste anges till ett visst värde för att resursen ska fungera korrekt för din lösning kan du överväga att skapa en väl namngiven variabel som ger en förklaring och sedan tilldela värdet med hjälp av variabeln. För situationer där ett variabelnamn inte berättar hela historien kan du överväga att lägga till en kommentar. Du får lära dig mer om kommentarer senare i den här modulen.

För vissa resursegenskaper måste du skapa komplexa uttryck som innehåller funktioner och stränginterpolation för att skapa värden automatiskt. Din Bicep-kod är vanligtvis tydligare när du deklarerar variabler och refererar till dem i resurskodblocken.

Dricks

När du skapar utdata kan du försöka använda resursegenskaper där du kan. Undvik att införliva dina egna antaganden om hur resurser fungerar, eftersom dessa antaganden kan ändras över tid.

Om du till exempel behöver mata ut URL:en för en App Service-app bör du undvika att skapa en URL:

output hostname string = '${app.name}.azurewebsites.net'

Föregående metod bryts om App Service ändrar hur de tilldelar värdnamn till appar, eller om du distribuerar till Azure-miljöer som använder olika URL:er.

Använd defaultHostname i stället egenskapen för appresursen:

output hostname string = app.properties.defaultHostname

Hur använder du versionskontroll effektivt?

Versionskontrollsystem som Git kan förenkla ditt arbete när du omstrukturerar kod.

Eftersom versionskontrollsystem är utformade för att hålla reda på ändringarna i dina filer kan du använda dem för att enkelt återgå till en äldre version av koden om du gör ett misstag. Det är en bra idé att genomföra ditt arbete ofta så att du kan gå tillbaka till den exakta tidpunkt som du behöver.

Versionskontrollen hjälper dig också att ta bort gammal kod från dina Bicep-filer. Vad händer om din Bicep-kod innehåller en resursdefinition som du inte behöver längre? Du kan behöva definitionen igen i framtiden, och det är frestande att bara kommentera ut den och behålla den i filen. Men egentligen, att hålla det där bara röra upp din Bicep-fil, vilket gör det svårt för andra att förstå varför de kommenterade resurserna fortfarande finns där.

Ett annat övervägande är att det är möjligt för någon att oavsiktligt avkommentera definitionen, med oförutsägbara eller potentiellt negativa resultat. När du använder ett versionskontrollsystem kan du helt enkelt ta bort den gamla resursdefinitionen. Om du behöver definitionen igen i framtiden kan du hämta den från filhistoriken.