Effettuare il refactoring del file Bicep

  • 5 minuti

Dopo le fasi di conversione e migrazione del modello in Bicep, è necessario migliorare il file. Questo processo è denominato refactoring. La terza fase del flusso di lavoro consigliato per la migrazione del modello di ARM JSON e delle risorse di Azure a Bicep è la fase di refactoring:

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

L'obiettivo principale della fase di refactoring è migliorare la qualità del codice Bicep. I miglioramenti possono includere modifiche, ad esempio l'aggiunta di commenti al codice, per allineare il modello agli standard.

La fase di refactoring è costituita da otto passaggi, che puoi eseguire in qualsiasi ordine:

  • Verificare le versioni delle API delle risorse.
  • Esaminare i suggerimenti del linter nel nuovo file Bicep.
  • Rivedere parametri, variabili e nomi simbolici.
  • Semplificare le espressioni.
  • Verificare le risorse figlio e le risorse di estensione.
  • Modularizzare.
  • Aggiungere commenti.
  • Seguire le procedura consigliate per Bicep.

Nell'esempio seguente viene illustrato l'output dal comando Bicep decompile di un modello JSON che crea un piano di servizio app:

@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

Se si distribuisce questo modello Bicep così com'è, la distribuzione avrà esito positivo. È tuttavia possibile apportare miglioramenti per allineare il modello agli standard.

Verificare le versioni delle API delle risorse

Quando si usa Bicep per interagire con le risorse di Azure, si specifica una versione di API da usare. Man mano che i prodotti di Azure cambiano e migliorano, vengono rilasciate versioni più recenti delle API che forniscono l'accesso alle nuove funzionalità. Quando si esportano le risorse di Azure, il modello esportato potrebbe non disporre della versione più recente dell'API per un tipo di risorsa. Se sono necessarie proprietà specifiche per le distribuzioni future, aggiornare l'API alla versione appropriata. È buona norma verificare le versioni dell'API per ogni risorsa esportata.

Le informazioni di riferimento sui modelli di ARM di Azure consentono di verificare le versioni delle API e le proprietà delle risorse appropriate per il modello.

Esaminare i suggerimenti del linter nel nuovo file Bicep

Quando si creano i file Bicep usando l'estensione Bicep per Visual Studio Code, il linter viene eseguito automaticamente, evidenzia gli errori nel codice e vengono forniti suggerimenti. Molti suggerimenti ed errori includono un'opzione per applicare una correzione rapida al problema. Esaminare queste raccomandazioni e modificare il file Bicep.

Rivedere parametri, variabili e nomi simbolici

Se l'infrastruttura supporta più ambienti, ad esempio produzione e sviluppo, creare parametri che supportano questi ambienti. Una buona convenzione di denominazione dei parametri semplifica la personalizzazione delle distribuzioni per ogni ambiente.

I nomi di parametri, variabili e nomi simbolici generati dal decompilatore potrebbero non corrispondere alla convenzione di denominazione standard. Verificare i nomi generati e apportare le modifiche necessarie.

Nell'esempio seguente la variabile denominata appServicePlanName_var è stato aggiunto _var alla fine del nome della variabile originale:

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

Per maggiore chiarezza, è consigliabile rimuovere _var dal nome della variabile. Tuttavia, quando si rinomina la variabile, il nuovo nome è in conflitto con il nome simbolico della risorsa del piano di servizio app. È quindi consigliabile rinominare prima le risorse e poi le variabili usate nelle relative definizioni.

Suggerimento

Quando si rinominano gli identificatori, assicurarsi di farlo in modo coerente in tutte le parti del modello. È importante soprattutto per i parametri, le variabili e le risorse a cui si fa riferimento in tutto il modello.

Visual Studio Code offre un modo pratico per rinominare i simboli: selezionare l'identificatore che si vuole rinominare, premere F2, immettere un nuovo nome e quindi premere INVIO:

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

Questi passaggi consentono di rinominare l'identificatore e aggiornare automaticamente tutti i riferimenti.

Semplificare le espressioni

Il processo di decompilazione potrebbe non sempre sfruttare alcune funzionalità di Bicep. Esaminare le espressioni generate nella conversione e semplificarle. Ad esempio, il modello decompilato potrebbe includere una funzione concat() o format() che può essere semplificata usando l'interpolazione di stringhe. Esaminare i suggerimenti del linter e apportare le modifiche necessarie.

Verificare le risorse figlio e le risorse di estensione

Bicep offre diversi modi per dichiarare le risorse figlio e di estensione, tra cui la concatenazione dei nomi delle risorse, l’uso della proprietà parent e l'uso di risorse annidate.

Valutare la possibilità di verificare queste risorse dopo la decompilazione per assicurarsi che la struttura soddisfi gli standard previsti. Ad esempio, assicurarsi di non usare la concatenazione di stringhe per creare nomi di risorse figlio. È consigliabile usare invece la proprietà parent o una risorsa annidata. Allo stesso modo, è possibile fare riferimento alle subnet come proprietà di una rete virtuale o come risorse separate.

Modularizzare

Se si converte un modello con molte risorse, valutare la possibilità di suddividere i singoli tipi di risorse in moduli per semplicità. L'uso dei moduli in Bicep consente di ridurre la complessità delle distribuzioni dei modelli.

Nota

È possibile usare i modelli JSON come moduli in una distribuzione Bicep. Bicep può riconoscere i moduli JSON e di fare riferimento a essi in modo simile a come si usano i moduli Bicep.

Aggiungere commenti e descrizioni

Il codice Bicep è autodocumentato. In Bicep è possibile aggiungere commenti e descrizioni al codice per documentare l'infrastruttura. Grazie a questi elementi, i membri del team possono comprendere il codice e apportare modifiche con maggiore tranquillità. I commenti e le descrizioni sono visibili quando si usa un file Bicep in Visual Studio Code, ad esempio quando è necessario specificare un valore di parametro per un modulo. Ma quando si distribuisce un file Bicep in Azure, i commenti vengono ignorati.

È possibile aggiungere commenti a riga singola usando la sequenza di caratteri //. Per i commenti su più righe, inizia con un /* e termina con un oggetto */. È possibile aggiungere commenti che si applicano a righe specifiche nel codice o a sezioni di codice.

È possibile aggiungere un commento su più righe all'inizio del file, come mostrato:

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

È possibile aggiungere commenti a riga singola come intestazioni per sezioni di codice o su singole righe per descrivere il codice:

// 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 fornisce un elemento Decorator @description, che è possibile usare per documentare lo scopo di parametri, variabili, risorse, moduli e output. È possibile aggiungere la descrizione nella riga precedente all'elemento descritto:

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

Seguire le procedure consigliate per Bicep

Assicurarsi che il file Bicep segua le raccomandazioni standard. Consultare le procedure consigliate per Bicep per accertarsi di non avere dimenticato qualcosa.

Modello convertito

Dopo aver apportato i miglioramenti appropriati, verificare il modello finale prima della distribuzione. Il modello aggiornato include nomi modificati, versioni dell'API, descrizioni e commenti aggiunti:

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