Refatore o arquivo Bicep

Concluído

Após as fases de conversão e migração de conversão do modelo para Bicep, você precisa melhorar o arquivo. Esse processo é chamado de refatoração. A terceira fase do fluxo de trabalho recomendado para migrar seu modelo JSON ARM e recursos do Azure para o Bicep é a fase de refatoramento:

O foco principal da fase de refatoração é melhorar a qualidade do seu código Bicep. As melhorias podem incluir alterações, como a adição de comentários de código que alinham o modelo com seus padrões de modelo.

A fase de refatoração consiste em oito etapas, que você pode fazer em qualquer ordem:

• Revise as versões da API de recursos.
• Reveja as sugestões de linter no seu novo ficheiro Bicep.
• Revise parâmetros, variáveis e nomes simbólicos.
• Simplifique expressões.
• Analise os recursos filho e de extensão.
• Modularizar.
• Adicionar comentários.
• Siga as melhores práticas do Bicep.

O exemplo a seguir mostra a saída do comando Bicep decompile de um modelo JSON que cria um plano do Serviço de Aplicativo:

@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 você implantar esse modelo Bicep como está, a implantação será bem-sucedida, mas você poderá melhorá-lo para alinhá-lo com seus padrões de modelo.

Revisar versões da API de recursos

Ao usar o Bicep para interagir com seus recursos do Azure, você especifica uma versão de API a ser usada. À medida que os produtos do Azure mudam e melhoram, versões mais recentes da API são lançadas para fornecer acesso a novas funcionalidades. Quando você exporta recursos do Azure, o modelo exportado pode não ter a versão mais recente da API para um tipo de recurso. Se você precisar de propriedades específicas para implantações futuras, atualize a API para a versão apropriada. É uma boa prática revisar as versões da API para cada recurso exportado.

A referência de modelo ARM do Azure pode ajudá-lo a verificar as versões de API apropriadas e as propriedades de recursos para seu modelo.

Reveja as sugestões linter no seu novo ficheiro Bicep

Quando você cria arquivos Bicep usando a extensão Bicep para Visual Studio Code, o linter é executado automaticamente e destaca erros em seu código e fornece sugestões. Muitas das sugestões e erros incluem uma opção para aplicar uma solução rápida para o problema. Reveja estas recomendações e ajuste o seu ficheiro Bicep.

Revisar parâmetros, variáveis e nomes simbólicos

Se a sua infraestrutura suportar vários ambientes, como produção e desenvolvimento, crie parâmetros que suportem esses ambientes. Uma boa convenção de nomenclatura de parâmetros facilita a personalização de suas implantações por ambiente.

Os nomes de parâmetros, variáveis e nomes simbólicos gerados pelo descompilador podem não corresponder à sua convenção de nomenclatura padrão. Revise os nomes gerados e faça os ajustes necessários.

No exemplo a seguir, a variável nomeada appServicePlanName_var foi _var acrescentada ao final do nome da variável original:

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

Para maior clareza, é uma boa ideia remover _var do nome da variável. Mas, quando você renomeia a variável, seu novo nome entra em conflito com o nome simbólico do recurso de plano do Serviço de Aplicativo. Portanto, é uma boa ideia renomear os recursos primeiro e, em seguida, renomear as variáveis que são usadas em suas definições.

Gorjeta

Ao renomear identificadores, certifique-se de renomeá-los consistentemente em todas as partes do modelo. Isso é especialmente importante para parâmetros, variáveis e recursos aos quais você se refere em todo o modelo.

O Visual Studio Code oferece uma maneira conveniente de renomear símbolos: selecione o identificador que você deseja renomear, selecione F2, insira um novo nome e selecione Enter:

Essas etapas renomeiam o identificador e atualizam automaticamente todas as referências a ele.

Simplifique expressões

O processo de descompilação nem sempre pode tirar proveito de alguns recursos do Bicep. Analise todas as expressões geradas na conversão e simplifique-as. Por exemplo, o modelo descompilado pode incluir uma concat() ou format() função que você pode simplificar usando interpolação de cadeia de caracteres. Analise todas as sugestões do linter e faça os ajustes necessários.

Rever recursos filho e de extensão

O Bicep fornece várias maneiras de declarar recursos filho e de extensão, incluindo concatenar os nomes de seus recursos, usar a parent propriedade e usar recursos aninhados.

Considere revisar esses recursos após a descompilação para garantir que a estrutura atenda aos seus padrões. Por exemplo, certifique-se de não usar concatenação de cadeia de caracteres para criar nomes de recursos filho. Em vez disso, use a parent propriedade ou um recurso aninhado. Da mesma forma, você pode fazer referência a sub-redes como propriedades de uma rede virtual ou como recursos separados.

Modularizar

Se você estiver convertendo um modelo que tenha muitos recursos, considere dividir os tipos de recursos individuais em módulos para simplificar. O uso de módulos no Bicep ajuda a reduzir a complexidade de suas implantações de modelo.

Nota

É possível usar seus modelos JSON como módulos em uma implantação do Bicep. O Bicep pode reconhecer módulos JSON e fazer referência a eles de forma semelhante à forma como você usa os módulos Bicep.

Adicionar comentários e descrições

Um bom código Bicep é auto-documentável. No Bicep, você pode adicionar comentários e descrições ao seu código para documentar sua infraestrutura. Comentários e descrições podem ajudar seus colegas de equipe a entender o código e aumentar a confiança quando as alterações são feitas. Comentários e descrições são visíveis quando você trabalha com um arquivo Bicep no Visual Studio Code, como quando você precisa especificar um valor de parâmetro para um módulo. Mas quando você implanta um arquivo Bicep no Azure, os comentários são ignorados.

Você pode adicionar comentários de linha única usando a sequência de // caracteres. Para comentários com várias linhas, comece com um e termine com um /* */arquivo . Você pode adicionar comentários que se aplicam a linhas específicas em seu código ou a seções de código.

Você pode adicionar um comentário de várias linhas no início do arquivo:

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

Você pode adicionar comentários de linha única como cabeçalhos para seções de código ou em linhas individuais para descrever o código:

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

O Bicep fornece um @description decorador que você pode usar para documentar a finalidade de seus parâmetros, variáveis, recursos, módulos e saídas. Você pode adicionar a descrição na linha acima do item que está descrevendo:

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

Siga as melhores práticas do Bicep

Certifique-se de que o seu ficheiro Bicep segue as recomendações padrão. Analise as práticas recomendadas do Bicep para qualquer coisa que você possa ter perdido.

O modelo convertido

Depois de fazer as melhorias apropriadas, revise o modelo final antes de implantá-lo. O modelo atualizado inclui nomes revisados, versões de API, descrições e comentários adicionados:

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