أنشئ تشوهات مخصصة لأجهزة DevTest Labs الافتراضية

القطع الأثرية هي أدوات أو إجراءات أو برامج يمكنك إضافتها إلى أجهزة Azure DevTest Labs. على سبيل المثال، يمكن للمصنوعات تشغيل السكريبتات النصية، تثبيت الأدوات، أو اتخاذ إجراءات مثل الانضمام إلى نطاق. يمكن لمستخدمي DevTest Labs إضافة تشوهات إلى آلاتهم الافتراضية، ويمكن لمسؤولي المختبر تحديد القطع الإلزامية التي يجب إضافتها إلى جميع أجهزة المختبر.

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

المتطلبات الأساسية

• لإنشاء والعمل مع ملفات تعريف القطع الأثرية، تحتاج إلى محرر JSON. يتوفر كود فيجوال ستوديو لأنظمة ويندوز ولينكس وماك أو إس.
• لتخزين تعريف القطعة الأثرية وملفات السكريبت، تحتاج إلى حساب GitHub.

فهم ملفات تعريف القطع الأثرية

يتكون ملف تعريف القطع الأثرية من تعبير JSON يحدد الإجراء الذي يجب اتخاذه على آلة افتراضية. يحدد الملف اسم الأداة الأثرية، وأمرا يجب تشغيله، ومعلمات متاحة للأمر المتاح. إذا كان الأثر يحتوي على ملفات سكريبت أخرى، يمكنك الرجوع إلى الملفات بالاسم في ملف تعريف القطعة.

المثال التالي يوضح البنية الأساسية لملف تعريف artifactfile.json الأثر.

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "<title>",
    "description": "<description>",
    "iconUri": "",
    "targetOsType": "<os>",
    "parameters": {
      "<paramName>": {
        "type": "<type>",
        "displayName": "<display name>",
        "description": "<description>"
      }
    },
    "runCommand": {
      "commandToExecute": "<command>"
    }
  }

يحتوي التعريف على العناصر المطلوبة والاختيارية التالية:

اسم العنصر	Description
$schema	موقع ملف مخطط JSON، والذي يمكن أن يساعدك في اختبار صحة ملف التعريف.
title	اسم قطعة أثرية مطلوب للعرض.
description	وصف القطعة الأثرية مطلوب.
iconUri	أيقونة القطعة أثرية (URI) للعرض.
targetOsType	نظام التشغيل مطلوب للتثبيت. القيم المدعومة هي Windows أو Linux.
parameters	تخصيصات القطع الأثرية المتاحة أثناء التثبيت.
runCommand	أمر مطلوب لتثبيت الأداة على الجهاز الافتراضي.

معلمات القطع الأثرية

parameters يحدد قسم ملف التعريف الخيارات والقيم التي يمكن للمستخدمين تحديدها عند تثبيت التشكيلة. يمكنك الرجوع إلى هذه المعاملات في .runCommand

الهيكل التالي يعرف معاملة:

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

كل معلمة تتطلب اسما، وتعريف المعامل يتطلب العناصر التالية:

اسم العنصر	Description
type	نوع قيمة المعلمة المطلوبة. يمكن أن يكون النوع أي JSON stringصالح، أو عدد intصحيح، أو بوليان bool، أو array.
displayName	اسم المعلمة المطلوبة لعرضه للمستخدم.
description	وصف المعلمة المطلوبة.

معلمات السلاسل الآمنة

لإدراج الأسرار في تعريف الأداة الأثرية، أعلن عن الأسرار كسلاسل نصية آمنة باستخدام النحو secureStringParam الموجود في parameters قسم ملف التعريف. يسمح العنصر description بأي سلسلة نصية، بما في ذلك المسافات، ويعرض السلسلة في واجهة المستخدم كرموز مقنعة.

    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

فيما يلي runCommand يستخدم سكريبت PowerShell الذي يأخذ السلسلة الآمنة التي تم إنشاؤها باستخدام ConvertTo-SecureString الأمر. السكربت يلتقط الإخراج للتصحيح، لذا من أجل الأمان لا تسجل الإخراج إلى وحدة التحكم.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

تعبيرات الدوال والمصنوعات

يمكنك استخدام التعبيرات والدوال لبناء أمر تثبيت الأداة (artifact install). تقيم التعبيرات متى يتم تركيب القطعة الأثرية.

يمكن أن تظهر التعبيرات في أي مكان ضمن قيمة سلسلة JSON، ودائما ترجع قيمة JSON أخرى. أرفق التعبيرات مع الأقواس . [ ] إذا كنت بحاجة لاستخدام وتر حرفي يبدأ بحامل، استخدم حواسين [[.

عادة ما تستخدم تعبيرات ذات دوال لبناء قيمة. يتم تنسيق استدعاءات الدوال ك .functionName(arg1, arg2, arg3)

تشمل الوظائف الشائعة:

الوظيفة	Description
parameters(parameterName)	يرجع قيمة معلمة لاستخدامها عند تشغيل أمر الأداة (artifact).
concat(arg1, arg2, arg3, ...)	يجمع بين عدة قيم نصية ويمكنه أخذ موسيط مختلفة.

يستخدم المثال التالي تعبيرات مع concat الدالة لبناء قيمة.

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

أنشئ قطعة أثرية مخصصة

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

1. قم بتنزيل ملف التعريفartifactfile.json و artifact.ps1 سكريبت PowerShell من https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

2. قم بتعديل ملف تعريف القطع الأثرية لإجراء بعض التغييرات الصحيحة على العناصر والقيم. في كود Visual Studio، يمكنك استخدام IntelliSense لرؤية العناصر الصالحة وخيارات القيم. على سبيل المثال، عند تعديل العنصر targetOsType ، يعرض لك Windows IntelliSense أو Linux خيارات.

3. خزن قطعتك الأثرية في مستودع أثري عام أو خاص لجهاز Git.

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

   تظهر لقطة الشاشة التالية مجلد تشويش مثالي:

   

   Note

   لإضافة القطع المخصصة الخاصة بك إلى مستودع القطع العامة في مختبرات DevTest، افتح طلب سحب ضد المستودع.

الخطوات التالية

• إضافة تشويش إلى أجهزة DevTest Labs الافتراضية
• حدد التشويهات الإلزامية التي يجب إضافتها إلى جميع أجهزة المختبر الافتراضية
• إضافة مستودع قطع أثرية إلى مختبر

المحتويات ذات الصلة

• تشخيص فشل القطع الأثرية في المختبر
• استكشاف المشكلات عند تطبيق التشويش