Het Bicep-bestand herstructureren

  • 5 minuten

Na de conversie- en migratiefasen van het converteren van uw sjabloon naar Bicep, moet u het bestand verbeteren. Dit proces wordt herstructureren genoemd. De derde fase van de aanbevolen werkstroom voor het migreren van uw JSON ARM-sjabloon en Azure-resources naar Bicep is de herstructureringsfase:

Diagram that shows the refactor phase of the recommended workflow for migrating Azure resources to Bicep.

De belangrijkste focus van de herstructureringsfase is het verbeteren van de kwaliteit van uw Bicep-code. Verbeteringen kunnen wijzigingen bevatten, zoals het toevoegen van codeopmerkingen die de sjabloon afstemmen op uw sjabloonstandaarden.

De herfactorfase bestaat uit acht stappen, die u in elke gewenste volgorde kunt uitvoeren:

  • Resource-API-versies controleren.
  • Bekijk de linter-suggesties in uw nieuwe Bicep-bestand.
  • Wijzig parameters, variabelen en symbolische namen.
  • Vereenvoudig expressies.
  • Bekijk onderliggende en extensiebronnen.
  • Modulariseer.
  • Opmerkingen toevoegen.
  • Volg de best practices van Bicep.

In het volgende voorbeeld ziet u de uitvoer van de Bicep-opdracht decompile van een JSON-sjabloon waarmee een App Service-plan wordt gemaakt:

@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@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Als u deze Bicep-sjabloon als zodanig implementeert, slaagt de implementatie, maar kunt u de sjabloon verbeteren om deze af te stemmen op uw sjabloonstandaarden.

Resource-API-versies controleren

Wanneer u Bicep gebruikt om te communiceren met uw Azure-resources, geeft u een API-versie op die moet worden gebruikt. Naarmate Azure-producten veranderen en verbeteren, worden nieuwere API-versies uitgebracht om toegang te bieden tot nieuwe functionaliteit. Wanneer u Azure-resources exporteert, heeft de geëxporteerde sjabloon mogelijk niet de meest recente API-versie voor een resourcetype. Als u specifieke eigenschappen nodig hebt voor toekomstige implementaties, werkt u de API bij naar de juiste versie. Het is een goed idee om de API-versies voor elke geëxporteerde resource te bekijken.

De naslaginformatie over Azure ARM-sjablonen kan u helpen bij het controleren van de juiste API-versies en resource-eigenschappen voor uw sjabloon.

Bekijk de lintersuggesties in uw nieuwe Bicep-bestand

Wanneer u Bicep-bestanden maakt met behulp van de Bicep-extensie voor Visual Studio Code, wordt de linter automatisch uitgevoerd en worden fouten in uw code gemarkeerd en worden suggesties gedaan. Veel van de suggesties en fouten bevatten een optie om een snelle oplossing voor het probleem toe te passen. Bekijk deze aanbevelingen en pas uw Bicep-bestand aan.

Parameters, variabelen en symbolische namen herzien

Als uw infrastructuur meerdere omgevingen ondersteunt, zoals productie en ontwikkeling, maakt u parameters die deze omgevingen ondersteunen. Een goede naamgevingsconventie voor parameters maakt het eenvoudig om uw implementaties per omgeving aan te passen.

De namen van parameters, variabelen en symbolische namen die door de decompiler worden gegenereerd, komen mogelijk niet overeen met uw standaardnaamconventie. Controleer de gegenereerde namen en breng indien nodig wijzigingen aan.

In het volgende voorbeeld is _var de benoemde appServicePlanName_var variabele toegevoegd aan het einde van de oorspronkelijke variabelenaam:

@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@2020-12-01' = {

Voor de duidelijkheid is het een goed idee om de naam van de variabele te verwijderen _var . Maar wanneer u de naam van de variabele wijzigt, conflicteert de nieuwe naam met de symbolische naam van de Resource van het App Service-plan. Het is dus een goed idee om eerst de naam van resources te wijzigen en vervolgens de variabelen te wijzigen die in hun definities worden gebruikt.

Tip

Wanneer u de naam van id's wijzigt, moet u de naam consistent wijzigen in alle onderdelen van uw sjabloon. Dit is met name belangrijk voor parameters, variabelen en resources waarnaar u in uw sjabloon verwijst.

Visual Studio Code biedt een handige manier om de naam van symbolen te wijzigen: selecteer de id die u wilt wijzigen, selecteer F2, voer een nieuwe naam in en selecteer vervolgens Enter:

Screenshot from Visual Studio Code that shows how to rename a symbol.

Met deze stappen wijzigt u de naam van de id en werkt u automatisch alle verwijzingen ernaar bij.

Expressies vereenvoudigen

Het decompileringsproces maakt mogelijk niet altijd gebruik van enkele Bicep-functies. Controleer alle expressies die in de conversie worden gegenereerd en vereenvoudig deze. De gedecompileerde sjabloon kan bijvoorbeeld een concat() of format() functie bevatten die u kunt vereenvoudigen door tekenreeksinterpolatie te gebruiken. Bekijk eventuele suggesties van de linter en breng indien nodig aanpassingen aan.

Onderliggende en extensiebronnen controleren

Bicep biedt meerdere manieren om onderliggende en extensiebronnen te declareren, waaronder het samenvoegen van de namen van uw resources, het gebruik van de parent eigenschap en het gebruik van geneste resources.

Overweeg deze resources na decompilatie te controleren om ervoor te zorgen dat de structuur voldoet aan uw standaarden. Zorg er bijvoorbeeld voor dat u geen tekenreekssamenvoeging gebruikt om onderliggende resourcenamen te maken. Gebruik in plaats daarvan de parent eigenschap of een geneste resource. Op dezelfde manier kunt u verwijzen naar subnetten als eigenschappen van een virtueel netwerk of als afzonderlijke resources.

Modulariseren

Als u een sjabloon met veel resources converteert, kunt u overwegen om de afzonderlijke resourcetypen te verbreken in modules voor het gemak. Het gebruik van modules in Bicep helpt de complexiteit van uw sjabloonimplementaties te verminderen.

Notitie

U kunt uw JSON-sjablonen gebruiken als modules in een Bicep-implementatie. Bicep kan JSON-modules herkennen en ernaar verwijzen zoals u Bicep-modules gebruikt.

Opmerkingen en beschrijvingen toevoegen

Goede Bicep-code is zelfdocumenterend. In Bicep kunt u opmerkingen en beschrijvingen toevoegen aan uw code om uw infrastructuur te documenteren. Opmerkingen en beschrijvingen kunnen uw teamleden helpen de code te begrijpen en het vertrouwen te vergroten wanneer er wijzigingen worden aangebracht. Opmerkingen en beschrijvingen zijn zichtbaar wanneer u met een Bicep-bestand in Visual Studio Code werkt, bijvoorbeeld wanneer u een parameterwaarde voor een module moet opgeven. Maar wanneer u een Bicep-bestand in Azure implementeert, worden de opmerkingen genegeerd.

U kunt opmerkingen met één regel toevoegen met behulp van de // tekenreeks. Voor opmerkingen met meerdere regels begint u met een /* en eindigt u met een */. U kunt opmerkingen toevoegen die van toepassing zijn op specifieke regels in uw code of op secties met code.

U kunt aan het begin van het bestand een opmerking met meerdere regels toevoegen:

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

U kunt opmerkingen met één regel toevoegen als kopteksten voor codesecties of op afzonderlijke regels om de code te beschrijven:

// 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 biedt een @description decorator die u kunt gebruiken om het doel van uw parameters, variabelen, resources, modules en uitvoer te documenteren. U kunt de beschrijving toevoegen op de regel boven het item dat u beschrijft:

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

Best practices voor Bicep volgen

Zorg ervoor dat uw Bicep-bestand de standaardaankopen volgt. Bekijk de best practices van Bicep voor alles wat u mogelijk hebt gemist.

De geconverteerde sjabloon

Nadat u de juiste verbeteringen hebt aangebracht, controleert u de uiteindelijke sjabloon voordat u deze implementeert. De bijgewerkte sjabloon bevat herziene namen, API-versies, beschrijvingen en opmerkingen toegevoegd:

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