مرجع مخطط التخصيصات

توفر هذه المقالة المرجعية معلومات مفصلة حول الملفات imagedefinition.yaml و task.yaml المستخدمة لتخصيص Microsoft Dev Box. يمكن للمطورين استخدام ملفات YAML هذه لتحديد المهام لتوفير مربعات التطوير وتكوينها. تساعد الملفات على ضمان الاتساق والكفاءة عبر بيئات التطوير. تتناول هذه المقالة المخطط والسمات المطلوبة والأمثلة لكلا نوعي الملفات، إلى جانب المهام المضمنة مثل PowerShell وWinGet.

ملفات Imagedefinition.yaml

يمكنك استخدام ملف Dev Box YAML لتعريف مهام التخصيص التي يجب تشغيلها أثناء إنشاء Dev Box. devbox.yaml قد يعيش الملف في نفس المستودع مثل المصدر الأساسي الذي يستخدمه فريق التطوير، أو قد يكون الملف في مستودع مركزي للتكوينات.

مثال على تعريف الصورة YAML:

$schema: 1.0
name: project-sample-1
image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365
tasks:
- name: "powershell"
  inputs:
    command:

الاسم

مطلوب: يرتبط هذا الاسم المألوف لتعريف الصورة بهذا devbox.yaml الملف. يتحكم هذا الإعداد في اسم تعريف الصورة المتوفر عند إنشاء التجمعات وتحديثها.

name: myVSDevBox

صورة

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

image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365

أو يمكن أن تكون صورة مخصصة من مثيل معرض حساب Azure المرفق:

image: galleryname/imagename@version

لمعرفة كيفية إرفاق مثيل Azure Compute Gallery بمركز التطوير الخاص بك، راجع تكوين Azure Compute Gallery ل Microsoft Dev Box.

للحصول على قائمة بالصور التي يمكن لمركز التطوير الوصول إليها، استخدم هذا az cli الأمر:

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

تحتاج إلى ملحق مركز az cli التطوير:

az extension add --name devcenter

خصائص البناء

تتكون مجموعة الكائنات هذه من خصائص البناء التي يمكن استخدامها لتخصيص عملية الإنشاء للصورة.

اتصال الشبكة

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

مثال:

buildProperties:
    networkConnection: "my-westus3"

المهام

مطلوب: تتكون مجموعة الكائنات هذه من مهام تخصيص Dev Box لتشغيلها عند توفير مربع تطوير. تختلف المدخلات المحددة التي يتم توفيرها لمهمة حسب المهمة.

مثال:

tasks:
- name: winget
  parameters:
    package: GitHub.GitHubDesktop

تدعم كافة المهام الخاصية timeout ، وهي اختيارية.

مثال:

tasks:
- name: powershell
  timeout: 1800 # in seconds
  parameters:
    command: <command>

المهام المضمنة

يتوفر PowerShell وWinGet كمهام مضمنة. يمكنك استدعاؤها مباشرة دون إرفاق كتالوج على مستوى مركز التطوير الذي يحدد تنفيذ هذه المهام.

مهمة WinGet المضمنة

تطبق هذه المهمة المضمنة تكوين WinGet على مربع التطوير.

البارامترات:

• configurationFile:

  • نوع: string
  • المسار إلى ملف تكوين WinGet YAML. يجب أن يكون الملف موجودا في الجهاز المحلي.
  • مطلوب: false

• downloadUrl:

  • نوع: string
  • عنوان URL يمكن الوصول إليه بشكل عام حيث يتم تخزين ملف تكوين YAML. يتم تنزيل الملف إلى المسار الذي configurationFile يحدده.
  • مطلوب: false

• inlineConfigurationBase64:

  • نوع: string
  • سلسلة ترميز Base64 لملف تكوين WinGet YAML. يتم فك ترميز الملف إلى المسار الذي configurationFile يحدد أو إلى ملف مؤقت إذا لم يتم تحديده.
  • مطلوب: false

• package:

  • نوع: string
  • اسم الحزمة المراد تثبيتها.
  • إذا تم توفير ملف تكوين YAML ضمن معلمات أخرى، فلن تكون هناك حاجة إلى اسم الحزمة.
  • مطلوب: false

• version

  • نوع: string
  • إصدار الحزمة المراد تثبيتها.
  • إذا تم توفير ملف تكوين YAML ضمن معلمات أخرى، فلا حاجة لإصدار الحزمة.
  • مطلوب: false

مهمة PowerShell المضمنة

تقوم هذه المهمة المضمنة بتشغيل أمر PowerShell.

البارامترات:

• command:
  • نوع: string
  • الأمر الذي يجب تشغيله.
  • مطلوب: true

ملفات task.yaml

مهام التخصيص هي وحدات قابلة لإعادة الاستخدام من التعليمات البرمجية للتثبيت أو تكوين البيئة. يستخدم المطورون برامج PowerShell النصية لكتابتها واستخدام task.yaml ملف بيانات تعريف لوصفها. يستخدم المطورون هذه المهام لتخصيص مربع تطوير عن طريق الرجوع إليها من devbox.yaml ملف.

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

يقوم المثال التالي لتعريف مهمة بتشغيل أمر PowerShell في دليل عمل معين:

name: powershell
description: Execute a powershell command
author: Microsoft Corporation
command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"
inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute
  workingDirectory:
    type: string
    defaultValue: ""
    required: false
    description: The working directory to execute the command in

السمات

الاسم

مطلوب: يستخدم هذا المعرف الفريد للإشارة إلى مهمة من devbox.yaml. يجب أن يكون الاسم فريدا في سياق الكتالوج حيث توجد المهمة.

يجب أن تتطابق التسمية مع قيود موارد Azure الموجودة. يجب أن يتراوح الاسم بين 3 و63 حرفا. يجب أن يبدأ بحرف أبجدي رقمي. يجب أن يتكون الاسم من أحرف أبجدية رقمية فقط و"-" أو "." أو "_". الحرف "/" محجوز.

name: powershell

وصف

اختياري: تصف هذه السمة المهمة.

description: This task executes a powershell command

إدخال

مطلوب: تسرد هذه السمة المعلمات التي تأخذها هذه المهمة كمدخل من devbox.yaml ملف وتستخدمها أثناء تشغيل الأمر. يمثل كل عنصر أصل اسم معلمة ويدعم هذه المفاتيح:

• type (مطلوب): نوع بيانات الإدخال لهذه المعلمة. يمكن أن يكون string، أو int.
• defaultValue (مطلوب): القيمة الافتراضية التي تأخذها هذه المعلمة.
• required (مطلوب): المفتاح الذي يحدد ما إذا كانت هذه المعلمة اختيارية أو مطلوبة.
• description (مطلوب): وصف لما تمثله هذه المعلمة.

inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute

الأمر

مطلوب: يتم استخدام هذا الأمر لتنفيذ هذه المهمة. يتم تشغيل سلسلة الأوامر المتوفرة في Windows PowerShell على الجهاز المحلي.

command: ".\runcommand.ps1

المتغيرات المرجعية في الأوامر

للإشارة إلى المعلمات في أمر، حدد اسم المتغير في أقواس مزدوجة، على سبيل المثال، {{parameter_name}}. يتم استنتاج قيم هذه المتغيرات قبل تشغيل الأمر الخاص بك.

command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"

المهلة

اختياري: يحدد هذا المتغير الحد الأقصى لمقدار الوقت (بالدقائق) للانتظار حتى يكتمل تنفيذ المهمة قبل انتهاء مهلة المهمة. الإعداد الافتراضي هو 30 دقيقة.

timeout: 30

كاتب

اختياري: يحدد هذا المتغير كاتب المهمة للمساعدة في عمليات التدقيق واستكشاف الأخطاء وإصلاحها.

author: Contoso Corporation

عنوان URL للتوثيق

اختياري: يرتبط هذا المتغير بوثائق هذه المهمة.

documentationURL: "https://link.to/documentation"

عنوان URL للترخيص

اختياري: يرتبط هذا المتغير بترخيص هذه المهمة.

licenseURL: "https://link.to/license"