Omstrukturera Bicep-filen

  • 5 minuter

När du har gått igenom konverterings- och migreringsfaserna för att omvandla din mall till Bicep behöver du förbättra filen. Den här processen kallas refaktorisering. Den tredje fasen i det rekommenderade arbetsflödet för migrering av din JSON ARM-mall och Azure-resurser till Bicep är refaktorfasen:

diagram som visar refaktorfasen för det rekommenderade arbetsflödet för migrering av Azure-resurser till Bicep.

Huvudfokus för refaktorfasen är att förbättra kvaliteten på din Bicep-kod. Förbättringar kan omfatta ändringar som att lägga till kodkommentorer som justerar mallen med dina mallstandarder.

Refaktorfasen består av åtta steg, vilket du kan göra i valfri ordning:

  • Granska resurs-API-versioner.
  • Granska linterförslagen i din nya Bicep-fil.
  • Ändra parametrar, variabler och symboliska namn.
  • Förenkla uttryck.
  • Granska underordnade resurser och tilläggsresurser.
  • Modularisera.
  • Lägg till kommentarer.
  • Följ Biceps bästa praxis.

I följande exempel visas utdata från kommandot Bicep decompile för en JSON-mall som skapar en App Service-plan:

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2024-04-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Om du distribuerar den här Bicep-mallen as-islyckas distributionen, men du kan förbättra mallen så att den överensstämmer med dina mallstandarder.

Granska resurs-API-versioner

När du använder Bicep för att interagera med dina Azure-resurser anger du en API-version att använda. Allt eftersom Azure-produkter ändras och förbättras släpps nyare API-versioner för att ge åtkomst till nya funktioner. När du exporterar Azure-resurser kanske den exporterade mallen inte har den senaste API-versionen för en resurstyp. Om du behöver specifika egenskaper för framtida distributioner uppdaterar du API:et till rätt version. Det är en bra idé att granska API-versionerna för varje exporterad resurs.

Referensen Azure ARM-mallen kan hjälpa dig att verifiera lämpliga API-versioner och resursegenskaper för mallen.

Granska linterförslagen i din nya Bicep-fil

När du skapar Bicep-filer med hjälp av Bicep-tillägget för Visual Studio Codekörs lintern automatiskt och markerar fel i koden och ger förslag. Många av förslagen och felen innehåller ett alternativ för att tillämpa en snabbkorrigering för problemet. Granska de här rekommendationerna och justera Bicep-filen.

Ändra parametrar, variabler och symboliska namn

Om din infrastruktur stöder flera miljöer, till exempel produktion och utveckling, skapar du parametrar som stöder dessa miljöer. En bra namngivningskonvention för parametrar gör det enkelt att anpassa dina distributioner per miljö.

Namnen på parametrar, variabler och symboliska namn som genereras av dekompileraren kanske inte matchar din standardnamnkonvention. Granska de genererade namnen och gör justeringar efter behov.

I följande exempel har variabeln med namnet appServicePlanName_var_var lagts till i slutet av det ursprungliga variabelnamnet:

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2024-04-01' = {

För tydlighetens skull är det en bra idé att ta bort _var från variabelnamnet. Men när du byter namn på variabeln står det nya namnet i konflikt med det symboliska namnet på App Service-planresursen. Därför är det en bra idé att byta namn på resurser först och sedan byta namn på de variabler som används i deras definitioner.

Tips

När du byter namn på identifierare måste du byta namn på dem konsekvent i alla delar av mallen. Detta är särskilt viktigt för parametrar, variabler och resurser som du refererar till i hela mallen.

Visual Studio Code är ett praktiskt sätt att byta namn på symboler: välj den identifierare som du vill byta namn på, välj F2, ange ett nytt namn och välj sedan Ange:

Skärmbild från Visual Studio Code som visar hur du byter namn på en symbol.

De här stegen byter namn på identifieraren och uppdaterar automatiskt alla referenser till den.

Förenkla uttryck

Dekompileringsprocessen kanske inte alltid drar nytta av vissa Bicep-funktioner. Granska alla uttryck som genereras i konverteringen och förenkla dem. Den dekompilerade mallen kan till exempel innehålla en concat()- eller format() funktion som du kan förenkla med hjälp av stränginterpolation. Granska eventuella förslag från lintern och gör justeringar efter behov.

Granska underordnade resurser och utökningsresurser

Bicep tillhandahåller flera sätt att deklarera underordnade resurser och tilläggsresurser, inklusive att sammanfoga namnen på dina resurser, använda egenskapen parent och använda kapslade resurser.

Överväg att granska dessa resurser efter dekompileringen för att se till att strukturen uppfyller dina standarder. Kontrollera till exempel att du inte använder strängsammanfogning för att skapa underordnade resursnamn. Använd i stället egenskapen parent eller en kapslad resurs. På samma sätt kan du referera till undernät som egenskaper för ett virtuellt nätverk eller som separata resurser.

Modularisera

Om du konverterar en mall som har många resurser kan du överväga att dela upp de enskilda resurstyperna i moduler för enkelhetens skull. Med hjälp av moduler i Bicep kan du minska komplexiteten i dina malldistributioner.

Obs

Du kan använda dina JSON-mallar som moduler i en Bicep-distribution. Bicep kan känna igen JSON-moduler och referera till dem på samma sätt som du använder Bicep-moduler.

Lägga till kommentarer och beskrivningar

Bra Bicep-kod är självdokumenterande. I Bicep kan du lägga till kommentarer och beskrivningar i koden för att dokumentera infrastrukturen. Kommentarer och beskrivningar kan hjälpa dina teammedlemmar att förstå koden och öka förtroendet när ändringar görs. Kommentarer och beskrivningar visas när du arbetar med en Bicep-fil i Visual Studio Code, till exempel när du behöver ange ett parametervärde för en modul. Men när du distribuerar en Bicep-fil till Azure ignoreras kommentarerna.

Du kan lägga till enradskommentarer med hjälp av // teckensekvensen. För flerradskommentarer börjar du med en /* och slutar med en */. Du kan lägga till kommentarer som gäller för specifika rader i koden eller i kodavsnitt.

Du kan lägga till en kommentar med flera rader i början av filen:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

Du kan lägga till enradskommentarer som rubriker för kodavsnitt eller på enskilda rader för att beskriva koden:

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

Bicep tillhandahåller en @description dekoratör som du kan använda för att dokumentera syftet med dina parametrar, variabler, resurser, moduler och utdata. Du kan lägga till beskrivningen på raden ovanför det objekt som du beskriver:

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Följ metodtipsen för Bicep

Kontrollera att Bicep-filen följer standardrekommendationerna. Gå igenom bästa praxis för Bicep för att se om det är något du kanske har missat.

Den konverterade mallen

När du har slutfört lämpliga förbättringar granskar du den slutliga mallen innan du distribuerar den. Den uppdaterade mallen innehåller ändrade namn, API-versioner, beskrivningar och tillagda kommentarer:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.