إعادة بناء التعليمات البرمجية لملف Bicep

  • 5 دقائق

بعد مراحل التحويل والترحيل لتحويل القالب إلى Bicep، تحتاج إلى تحسين الملف. وتسمى هذه العملية إعادة بناء التعليمات البرمجية. المرحلة الثالثة من سير العمل الموصى به لترحيل قالب JSON ARM وموارد Azure إلى Bicep هي مرحلة إعادة بناء التعليمات البرمجية:

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

التركيز الرئيسي لمرحلة إعادة بناء التعليمات البرمجية هو تحسين جودة تعليمة Bicep البرمجية. يمكن أن تتضمن التحسينات تغييرات مثل إضافة تعليقات التعليمات البرمجية التي محاذاة القالب مع معايير القالب.

تتكون مرحلة إعادة بناء التعليمات البرمجية من ثماني خطوات، والتي يمكنك القيام بها بأي ترتيب:

  • مراجعة إصدارات واجهة برمجة التطبيقات للمورد.
  • مراجعة اقتراحات linter في ملف Bicep الجديد.
  • مراجعة المعلمات، والمتغيرات، والأسماء الرمزية.
  • تبسيط التعبيرات.
  • مراجعة الموارد الفرعية وملحقاتها.
  • النمذجة.
  • إضافة تعليقات.
  • اتبع أفضل ممارسات Bicep.

يوضح المثال التالي الإخراج من أمر Bicep decompile لقالب JSON الذي ينشئ خطة 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

إذا قمت بنشر قالب Bicep هذا كما هو، فسينجح النشر، ولكن يمكنك تحسين القالب لمحاذاته مع معايير القالب.

مراجعة إصدارات واجهة برمجة التطبيقات للمورد

عند استخدام Bicep للتفاعل مع موارد Azure، يمكنك تحديد إصدار واجهة برمجة التطبيقات المراد استخدامه. مع تغير منتجات Azure وتحسينها، تُطرح إصدارات أحدث من واجهة برمجة التطبيقات من شأنها توفير الوصول إلى وظائف جديدة. عند تصدير موارد Azure قد لا يكون القالب الذي صدر هو أحدث إصدار من واجهة برمجة التطبيقات لنوع المورد. إذا كنت تحتاج خصائص معينة لعمليات التوزيع المستقبلية فحدِّث واجهة برمجة التطبيقات إلى الإصدار المناسب. من الممارسات الجيدة مراجعة إصدارات واجهة برمجة التطبيقات لكل مورد تم تصديره.

يمكن أن يساعدك مرجع قالب Azure ARM في التحقق من إصدارات واجهة برمجة التطبيقات المناسبة وخصائص الموارد للقالب الخاص بك.

مراجعة اقتراحات linter في ملف Bicep

عند إنشاء ملفات Bicep باستخدام ملحق Bicep ل Visual Studio Code، يتم تشغيل linter تلقائيا ويسلط الضوء على الأخطاء في التعليمات البرمجية الخاصة بك ويوفر اقتراحات. تتضمن العديد من الاقتراحات والأخطاء خيارا لتطبيق حل سريع للمشكلة. راجع هذه التوصيات واضبط ملف Bicep.

مراجعة المعلمات والمتغيرات والأسماء الرمزية

إذا كانت البنية الأساسية تدعم بيئات متعددة، مثل الإنتاج والتطوير، فقم بإنشاء معلمات تدعم هذه البيئات. يسهل اصطلاح تسمية المعلمات الجيد تخصيص عمليات التوزيع الخاصة بك لكل بيئة.

قد لا تتطابق أسماء المعلمات والمتغيرات والأسماء الرمزية التي تم إنشاؤها بواسطة إلغاء التحويل البرمجي مع اصطلاح التسمية القياسي. راجع الأسماء التي تم إنشاؤها وإجراء التعديلات حسب الضرورة.

في المثال التالي، تم _var إلحاق المتغير المسمى appServicePlanName_var بنهاية اسم المتغير الأصلي:

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

من أجل الوضوح، تعد هذه فكرة جيدة لإزالة _var من الاسم المتغير. ولكن عند إعادة تسمية المتغير، يتعارض اسمه الجديد مع الاسم الرمزي لمورد خطة App Service. لذلك من الجيد إعادة تسمية الموارد أولا، ثم إعادة تسمية المتغيرات المستخدمة في تعريفاتها.

تلميح

عند إعادة تسمية المعرفات، تأكد من إعادة تسميتها باستمرار في كافة أجزاء القالب. فذلك بغاية الأهمية للمعلمات والمتغيرات والموارد التي تشير إليها في القالب.

يُوفر Visual Studio Code طريقة ملائمة لإعادة تسمية الرموز: اختر المعرف الذي تريد إعادة تسميته واختر F2وأدخل اسمًا جديدًا، ثم اختر Enter:

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

تعيد هذه الخطوات تسمية المعرف وتحديث كافة المراجع إليه تلقائيًا.

تبسيط التعبيرات

قد لا تستفيد عملية إلغاء التحويل البرمجي دائما من بعض ميزات Bicep. راجع أي تعبيرات أنشئت في التحويل وبسطها. على سبيل المثال، قد يتضمن القالب وظيفة concat() أو format() يمكن تبسيطها باستخدام استنتاج السلسلة. مراجعة أي اقتراحات من linter وإجراء تعديلات حسب الضرورة.

مراجعة الموارد التابعة والملحقة

يوفر Bicep طرقا متعددة للإعلان عن الموارد التابعة والملحقة، بما في ذلك تسلسل أسماء الموارد واستخدام الخاصية parent واستخدام الموارد المتداخلة.

ضع في اعتبارك مراجعة هذه الموارد بعد إلغاء التحويل البرمجي، وتأكد من أن البنية تفي بالمعايير الخاصة بك. على سبيل المثال، تأكد من أنك لا تستخدم تسلسل السلسلة لإنشاء أسماء موارد فرعية. بدلا من ذلك، استخدم خاصية parent أو مورد متضمن. وبالمثل، يمكن الرجوع إلى الشبكات الفرعية كخصائص لشبكة ظاهرية أو كمورد منفصل.

التعبير في شكل وحدات

إذا كنت تقوم بتحويل قالب يحتوي على العديد من الموارد، ففكر في تقسيم أنواع الموارد الفردية إلى وحدات نمطية للبساطة. تساعد استخدام الوحدات في Bicep على تقليل تعقيد عمليات توزيع القوالب.

إشعار

من الممكن استخدام قوالب JSON كوحدات في توزيع Bicep. يمكن ل Bicep التعرف على وحدات JSON والإشارة إليها بشكل مشابه لكيفية استخدام وحدات Bicep النمطية.

إضافة تعليقات وأوصاف

التعليمات البرمجية لـ Bicep الجيدة هي توثيق ذاتي. يمكنك في Bicep إضافة تعليقات وأوصاف إلى تعليماتك البرمجية لتوثيق البنية الأساسية لديك. يمكن أن تساعد هذه التعليقات زملاءك في الفريق على فهم التعليمات البرمجية وإجراء التغييرات بثقة أكبر. تظهر التعليقات والأوصاف عند العمل مع ملف Bicep في Visual Studio Code، مثل عندما تحتاج إلى تحديد قيمة معلمة لوحدة نمطية. ولكن عند نشر ملف Bicep إلى Azure، يتم تجاهل التعليقات.

يمكنك إضافة تعليقات من سطر واحد باستخدام تسلسل الأحرف // . بالنسبة للتعليقات متعددة الأسطر، ابدأ ب /* و ينتهي ب */. يمكنك إضافة تعليقات تنطبق على أسطر معينة في التعليمات البرمجية أو على أقسام التعليمات البرمجية.

يمكنك إضافة تعليق متعدد الأسطر في بداية الملف:

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

يمكنك إضافة تعليقات من سطر واحد كعناوين لأقسام التعليمات البرمجية أو على أسطر فردية لوصف التعليمات البرمجية:

// 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 مصمما @description يمكنك استخدامه لتوثيق الغرض من المعلمات والمتغيرات والموارد والوحدات النمطية والمخرجات. يمكنك إضافة الوصف على السطر أعلى العنصر الذي تصفه:

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

اتباع أفضل ممارسات Bicep

تأكد من أن ملف Bicep الخاص بك يتبع التوصيات القياسية. راجع أفضل ممارسات Bicep لمعرفة ما فاتك.

القالب المحول

راجع بعد إجراء التحسينات المناسبة القالب النهائي قبل التوزيع. يتضمن القالب المحدث الأسماء المنقحة وإصدارات واجهة برمجة التطبيقات والأوصاف والتعليقات المضافة:

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