Refaktorovat soubor Bicep

  • 5 min

Po fázích převodu a migrace vaší šablony na Bicep je třeba soubor vylepšit. Tento proces se nazývá refaktoring. Třetí fází doporučeného pracovního postupu pro migraci šablony JSON ARM a prostředků Azure do Bicep je fáze refaktoringu:

Diagram znázorňující fázi refaktoringu doporučeného pracovního postupu pro migraci prostředků Azure do Bicep

Hlavním cílem fáze refaktoringu je zlepšit kvalitu kódu Bicep. Vylepšení můžou zahrnovat změny, jako je přidání komentářů ke kódu, které odpovídají šabloně standardům šablony.

Fáze refaktoringu se skládá z osmi kroků, které můžete provést v libovolném pořadí:

  • Zkontrolujte verze rozhraní API zdrojů.
  • Projděte si návrhy linteru v novém souboru Bicep.
  • Revidují parametry, proměnné a symbolické názvy.
  • Zjednodušte výrazy.
  • Zkontrolujte podřízené a rozšiřující prostředky.
  • Modularizovat.
  • Přidejte komentáře.
  • Postupujte podle osvědčených postupů Bicep.

Následující příklad ukazuje výstup příkazu bicep decompile šablony JSON, která vytvoří plán služby App Service:

@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

Pokud nasadíte tuto šablonu Bicep as-is, nasazení bude úspěšné, ale šablonu můžete vylepšit tak, aby odpovídala standardům šablony.

Kontrola verzí prostředků rozhraní API

Když použijete Bicep k interakci s prostředky Azure, zadáte verzi rozhraní API, kterou chcete použít. S tím, jak se produkty Azure mění a vylepšují, vydáváme novější verze rozhraní API, které poskytují přístup k novým funkcím. Při exportu prostředků Azure nemusí mít exportovaná šablona nejnovější verzi rozhraní API pro typ prostředku. Pokud potřebujete konkrétní vlastnosti pro budoucí nasazení, aktualizujte rozhraní API na příslušnou verzi. Doporučujeme zkontrolovat verze rozhraní API pro každý exportovaný prostředek.

Referenční informace k šabloně Azure ARM vám můžou pomoct s ověřením vhodných verzí rozhraní API a vlastností prostředků pro vaši šablonu.

Projděte si návrhy linteru v novém souboru Bicep.

Při vytváření souborů Bicep pomocí rozšíření Bicep pro Visual Studio Codese linter spustí automaticky a zvýrazní chyby v kódu a nabídne návrhy. Mnoho návrhů a chyb obsahuje možnost použít pro tento problém rychlou opravu. Projděte si tato doporučení a upravte soubor Bicep.

Revize parametrů, proměnných a symbolických názvů

Pokud vaše infrastruktura podporuje více prostředí, jako je produkční a vývoj, vytvořte parametry, které tato prostředí podporují. Dobrá konvence vytváření názvů parametrů usnadňuje přizpůsobení nasazení pro každé prostředí.

Názvy parametrů, proměnných a symbolických názvů vygenerovaných dekompilerem nemusí odpovídat vaší standardní konvenci pojmenování. Zkontrolujte vygenerované názvy a podle potřeby proveďte úpravy.

V následujícím příkladu má proměnná s názvem appServicePlanName_var_var připojena na konec původního názvu proměnné:

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

Pro přehlednost je vhodné odebrat _var z názvu proměnné. Když ale proměnnou přejmenujete, její nový název je v konfliktu s symbolickým názvem prostředku plánu služby App Service. Proto je vhodné nejprve přejmenovat prostředky a pak přejmenovat proměnné, které se používají v jejich definicích.

Spropitné

Při přejmenování identifikátorů nezapomeňte je trvale přejmenovat ve všech částech šablony. To je zvlášť důležité pro parametry, proměnné a prostředky, na které odkazujete v celé šabloně.

Visual Studio Code nabízí pohodlný způsob, jak přejmenovat symboly: vyberte identifikátor, který chcete přejmenovat, vyberte F2, zadejte nový název a pak vyberte Enter:

snímek obrazovky z editoru Visual Studio Code, který ukazuje, jak přejmenovat symbol.

Tento postup přejmenuje identifikátor a automaticky aktualizuje všechny odkazy na něj.

Zjednodušení výrazů

Proces dekompilu nemusí vždy využívat některé funkce Bicep. Zkontrolujte všechny výrazy vygenerované v převodu a zjednodušte je. Dekompilovaná šablona může například obsahovat concat() nebo format() funkci, kterou můžete zjednodušit pomocí interpolace řetězců. Projděte si případné návrhy z linteru a podle potřeby proveďte úpravy.

Prohlédnout zdroje podřízené a rozšíření

Bicep nabízí různé způsoby deklarace podřízených a rozšiřujících prostředků, včetně zřetězení názvů prostředků, použití vlastnosti parent a použití vnořených prostředků.

Zvažte kontrolu těchto prostředků po dekompilace a ujistěte se, že struktura splňuje vaše standardy. Například se ujistěte, že k vytváření názvů podřízených prostředků nepoužíváte zřetězování řetězců. Místo toho použijte vlastnost parent nebo vnořený prostředek. Podobně můžete podsítě odkazovat buď jako vlastnosti virtuální sítě, nebo jako samostatné prostředky.

Modularizovat

Pokud převádíte šablonu, která obsahuje mnoho prostředků, zvažte rozdělení jednotlivých typů prostředků na moduly kvůli jednoduchosti. Použití modulů v Bicep pomáhá snížit složitost nasazení šablony.

Poznámka

Šablony JSON je možné použít jako moduly v nasazení Bicep. Bicep dokáže rozpoznat moduly JSON a odkazovat na ně podobně jako na to, jak používáte moduly Bicep.

Přidání komentářů a popisů

Dobrý kód Bicep je samodokumentování. V Bicep můžete do kódu přidat komentáře a popisy, které dokumentují infrastrukturu. Komentáře a popisy můžou vašim členům týmu pomoct pochopit kód a zvýšit spolehlivost při provedení změn. Komentáře a popisy jsou viditelné, když pracujete se souborem Bicep v editoru Visual Studio Code, například když potřebujete zadat hodnotu parametru pro modul. Když ale nasadíte soubor Bicep do Azure, komentáře se ignorují.

Jednořádkové komentáře můžete přidat pomocí sekvence znaků //. U víceřádkových komentářů začněte s /* a skončete s */. Můžete přidat komentáře, které se vztahují na konkrétní řádky v kódu nebo do oddílů kódu.

Na začátek souboru můžete přidat víceřádkový komentář:

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

Jako záhlaví můžete přidat jednořádkové komentáře pro oddíly kódu nebo na jednotlivé řádky, které kód popisují:

// 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 poskytuje @description dekorátor, který můžete použít pro zdokumentování účelu parametrů, proměnných, prostředků, modulů a výstupů. Popis můžete přidat na řádek nad položkou, kterou popisujete:

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

Dodržujte osvědčené postupy Bicep.

Ujistěte se, že váš soubor Bicep dodržuje standardní doporučení. Projděte si osvědčené postupy pro Bicep pro případ, že vám něco uniklo.

Převedená šablona

Po provedení vhodných vylepšení si před nasazením prohlédněte konečnou šablonu. Aktualizovaná šablona obsahuje revidované názvy, verze rozhraní API, popisy a přidané komentáře:

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