Refaktoryzacja pliku Bicep

5 min

Po fazie konwersji i migracji konwersji szablonu na Bicep należy ulepszyć plik. Ten proces jest nazywany refaktoryzowaniem. Trzecią fazą zalecanego przepływu pracy migracji szablonu usługi ARM JSON i zasobów platformy Azure do Bicep jest faza refaktoryzacji:

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

Głównym celem fazy refaktoryzacji jest zwiększenie jakości kodu Bicep. Ulepszenia mogą obejmować zmiany, takie jak dodawanie komentarzy do kodu, które są zgodne z szablonem zgodnie ze standardami szablonu.

Faza refaktoryzacji składa się z ośmiu kroków, które można wykonać w dowolnej kolejności:

Przejrzyj wersje interfejsu API zasobów.
Przejrzyj sugestie linter w nowym pliku Bicep.
Popraw parametry, zmienne i nazwy symboliczne.
Upraszczanie wyrażeń.
Przejrzyj zasoby podrzędne i rozszerzenia.
Modularyzowanie.
Dodawanie komentarzy.
Postępuj zgodnie z najlepszymi rozwiązaniami dotyczącymi Bicep.

Poniższy przykład przedstawia dane wyjściowe polecenia Bicep decompile szablonu JSON, który tworzy plan usługi 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@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Jeśli wdrożysz ten szablon Bicep zgodnie z rzeczywistym działaniem, wdrożenie zakończy się pomyślnie, ale możesz ulepszyć szablon, aby dopasować go do standardów szablonu.

Przeglądanie wersji interfejsu API zasobów

W przypadku korzystania z aplikacji Bicep do interakcji z zasobami platformy Azure należy określić wersję interfejsu API do użycia. W miarę zmiany i ulepszania produktów platformy Azure nowsze wersje interfejsu API są wydawane w celu zapewnienia dostępu do nowych funkcji. Podczas eksportowania zasobów platformy Azure wyeksportowany szablon może nie mieć najnowszej wersji interfejsu API dla typu zasobu. Jeśli potrzebujesz określonych właściwości dla przyszłych wdrożeń, zaktualizuj interfejs API do odpowiedniej wersji. Dobrym rozwiązaniem jest przejrzenie wersji interfejsu API dla każdego wyeksportowanego zasobu.

Dokumentacja szablonu usługi Azure ARM może pomóc w zweryfikowaniu odpowiednich wersji interfejsu API i właściwości zasobów dla szablonu.

Przejrzyj sugestie linter w nowym pliku Bicep

Podczas tworzenia plików Bicep przy użyciu rozszerzenia Bicep dla programu Visual Studio Code linter jest uruchamiany automatycznie i wyróżnia błędy w kodzie i zawiera sugestie. Wiele sugestii i błędów zawiera opcję zastosowania szybkiego rozwiązania problemu. Przejrzyj te zalecenia i dostosuj plik Bicep.

Poprawianie parametrów, zmiennych i nazw symbolicznych

Jeśli infrastruktura obsługuje wiele środowisk, takich jak produkcja i programowanie, utwórz parametry, które obsługują te środowiska. Dobra konwencja nazewnictwa parametrów ułatwia dostosowywanie wdrożeń na środowisko.

Nazwy parametrów, zmiennych i nazw symbolicznych generowanych przez dekompiler mogą nie odpowiadać standardowej konwencji nazewnictwa. Przejrzyj wygenerowane nazwy i w razie potrzeby wprowadź korekty.

W poniższym przykładzie zmienna o nazwie appServicePlanName_var została _var dołączona na końcu oryginalnej nazwy zmiennej:

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

Aby uzyskać jasność, dobrym pomysłem jest usunięcie _var z nazwy zmiennej. Jednak po zmianie nazwy zmiennej nowa nazwa powoduje konflikt z symboliczną nazwą zasobu planu usługi App Service. Warto więc najpierw zmienić nazwę zasobów, a następnie zmienić nazwy zmiennych używanych w ich definicjach.

Napiwek

Podczas zmieniania nazw identyfikatorów pamiętaj, aby stale zmieniać ich nazwy we wszystkich częściach szablonu. Jest to szczególnie ważne w przypadku parametrów, zmiennych i zasobów, które odwołujesz się do całego szablonu.

Program Visual Studio Code oferuje wygodny sposób zmiany nazwy symboli: wybierz identyfikator, którego nazwę chcesz zmienić, wybierz klawisz F2, wprowadź nową nazwę, a następnie wybierz klawisz Enter:

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

Te kroki powodują zmianę nazwy identyfikatora i automatyczne aktualizowanie wszystkich odwołań do niego.

Upraszczanie wyrażeń

Proces dekompilowania może nie zawsze korzystać z niektórych funkcji Bicep. Przejrzyj wszystkie wyrażenia wygenerowane w konwersji i uprość je. Na przykład dekompilowany szablon może zawierać concat() funkcję lub format() , którą można uprościć przy użyciu interpolacji ciągów. Przejrzyj wszelkie sugestie z linter i w razie potrzeby wprowadź korekty.

Przeglądanie zasobów podrzędnych i rozszerzeń

Bicep zapewnia wiele sposobów deklarowania zasobów podrzędnych i rozszerzeń, w tym łączenia nazw zasobów, używania parent właściwości i używania zasobów zagnieżdżonych.

Rozważ przejrzenie tych zasobów po dekompilacji, aby upewnić się, że struktura spełnia Twoje standardy. Upewnij się na przykład, że nie używasz łączenia ciągów do tworzenia nazw zasobów podrzędnych. Zamiast tego użyj parent właściwości lub zagnieżdżonego zasobu. Podobnie można odwoływać się do podsieci jako właściwości sieci wirtualnej lub jako oddzielne zasoby.

Modularyzacja

Jeśli konwertujesz szablon zawierający wiele zasobów, rozważ podzielenie poszczególnych typów zasobów na moduły dla uproszczenia. Korzystanie z modułów w środowisku Bicep pomaga zmniejszyć złożoność wdrożeń szablonów.

Uwaga

Szablony JSON można używać jako modułów we wdrożeniu Bicep. Bicep może rozpoznawać moduły JSON i odwoływać się do nich podobnie do sposobu używania modułów Bicep.

Dodawanie komentarzy i opisów

Dobry kod Bicep jest dokumentowaniem własnym. W aplikacji Bicep możesz dodawać komentarze i opisy do kodu w celu dokumentowania infrastruktury. Komentarze i opisy mogą pomóc kolegom z zespołu zrozumieć kod i zwiększyć pewność podczas wprowadzania zmian. Komentarze i opisy są widoczne podczas pracy z plikiem Bicep w programie Visual Studio Code, tak jak w przypadku konieczności określenia wartości parametru dla modułu. Jednak podczas wdrażania pliku Bicep na platformie Azure komentarze są ignorowane.

Komentarze jednowierszowe można dodawać przy użyciu // sekwencji znaków. W przypadku komentarzy wielowierszowych zacznij od elementu /* i na końcu .*/ Możesz dodać komentarze, które mają zastosowanie do określonych wierszy w kodzie lub do sekcji kodu.

Na początku pliku można dodać komentarz wielowierszowy:

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

Możesz dodać komentarze jednowierszowe jako nagłówki dla sekcji kodu lub w poszczególnych wierszach, aby opisać kod:

// 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 udostępnia @description dekorator, którego można użyć do dokumentowania przeznaczenia parametrów, zmiennych, zasobów, modułów i danych wyjściowych. Opis można dodać w wierszu powyżej opisywanych elementów:

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

Postępuj zgodnie z najlepszymi rozwiązaniami dotyczącymi Bicep

Upewnij się, że plik Bicep jest zgodny ze standardowymi zaleceniami. Zapoznaj się z najlepszymi rozwiązaniami dotyczącymi Bicep, aby poznać wszystkie elementy, które mogły zostać pominięte.

Przekonwertowany szablon

Po wprowadzeniu odpowiednich ulepszeń przejrzyj ostateczny szablon przed jego wdrożeniem. Zaktualizowany szablon zawiera zmienione nazwy, wersje interfejsu API, opisy i dodane komentarze:

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