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

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

استخدم هذا المرجع عندما تحتاج:

• ابحث عن الخصائص والأنواع والإعدادات الافتراضية الصالحة في ملف imagedefinition.yaml أو task.yaml .
• أكد المعايير التي تقبلها المدمجة في ، ~/powershell، والمهام ~/winget المدمجة~/gitclone.
• افهم كيف tasks، userTasks، parameters، variables، ويعمل buildProperties معا عندما يوفر صندوق المطور صورة أو يطبق تخصيصات على صندوق المطورين.

أنواع ملفات التخصيص

تستخدم تخصيصات صندوق المطورين ثلاثة أنواع ملفات YAML، لكل منها غرض وجمهور مختلف:

المهام المدمجة ~/gitclone، ~/powershell، والمهام ~/winget متاحة من أي مركز تطوير دون الحاجة لإرفاق كتالوج. لإضافة مهام مخصصة تتجاوز تلك المدمجات، عرفها في task.yaml ملفات في كتالوج واطلق عليها بالاسم من تعريف الصورة أو ملف تخصيص المستخدم. لمزيد من المعلومات، راجع تخصيصات صندوق تطوير Microsoft.

ملفات Imagedefinition.yaml

استخدم imagedefinition.yaml ذلك لتعريف الصورة، والمعلمات، والمغيرات، ومهام التخصيص التي يطبقها Dev Box عند إنشاء تعريف الصورة.

مثال على ملف imagedefinition.yaml

$schema: "1.0"
name: example-image-definition
description: Install core tools and clone the project repository.
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.
variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.
tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces
      branch: "{{repositoryBranch}}"
userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo
buildProperties:
  networkConnection: corp-westus3

خصائص Imagedefinition.yaml

$schema

(سلسلة أو رقم)

يحدد إصدار المخطط للملف. الأمثلة الحالية تستخدم 1.0.

$schema: "1.0"

name

(سلسلة نصية، مطلوبة، من 3 إلى 63 حرفا)

يحدد الاسم الصديق الذي يظهر عند اختيار تعريف الصورة. يتحكم هذا الإعداد في اسم تعريف الصورة المتوفر عند إنشاء التجمعات وتحديثها. لا يمكن أن يحتوي الاسم على /، "، [، ]|<:، >+=*&?,@;المسافة البيضاء، أو يبدأ ب _ أو .-

name: example-image-definition

description

(وتر)

يصف هدف تعريف الصورة.

description: Install core tools and clone the project repository.

image

(وتر، مطلوب)

يحدد الصورة الأساسية لاستخدامها لصورة صندوق التطوير. يمكن أن تكون الصورة صورة سوق أو صورة مخصصة من معرض Azure Compute المرفق بصيغة gallery-name/image-name@version.

الأمثلة:

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

image: my-gallery/my-image@0.0.1

لإرفاق معرض Azure Compute Gallery، انظر Configure Azure Compute Gallery for Microsoft Dev Box.

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

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

إذا لزم الأمر، قم بتثبيت إضافة Dev Center Azure CLI أولا:

az extension add --name devcenter

parameters

(الموضوع)

يحدد معلمات إدخال مسماة يمكنك الرجوع إليها في المهام باستخدام {{parameterName}} الصياغة.

parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.

خصائص كائنات المعلمات

type

(النص، مطلوب، القيم المسموح بها: النص، البولياني، العدد)

يحدد نوع بيانات المعاملات.

allowed

(مصفوفة من الوتر)

يقيد المعامل بمجموعة ثابتة من قيم السلاسل النصية المسموح بها.

default

(الوتر أو البوليان أو الرقم مطلوب)

يحدد القيمة الافتراضية للمعامل.

description

(وتر)

يصف المعامل الخاص بالمؤلفين والأدوات.

validationRegex

(وتر)

يعرف تعبيرا منتظما يجب أن تتطابق قيم السلاسل النصية.

minLength

(رقم صحيح)

يحدد الحد الأدنى لطول القيم النصية.

maxLength

(رقم صحيح)

يحدد الحد الأقصى لطول السلاسل النصية.

variables

(الموضوع)

يحدد المتغيرات المسماة التي يمكنك إعادة استخدامها في تعريف الصورة.

variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.

خصائص الكائنات المتغيرة

type

(النص، مطلوب، القيم المسموح بها: النص، البولياني، العدد)

يحدد نوع البيانات المتغير.

value

(الوتر أو البوليان أو الرقم مطلوب)

يحدد قيمة المتغير.

description

(وتر)

يصف المتغير للمؤلفين والأدوات.

tasks

(مصفوفة من كائنات المهام)

يسرد مهام التخصيص التي يجب تشغيلها في سياق النظام أثناء الإعداد (الإعداد الصحيح). تختلف قيم المدخلات المحددة التي تقدمها حسب المهمة. يجب أن يتضمن name كل إدخال مهمة ويمكن أيضا تعريف displayName، description، ، parametersو timeout.

tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    timeout: 1800
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces

الخاصية timeout اختيارية وتقاس بالثواني عند استخدامها في imagedefinition.yaml.

tasks:
  - name: ~/powershell
    timeout: 1800
    parameters:
      command: <command>

خصائص إدخال المهام

name

(وتر، مطلوب)

يحدد المهمة التي يجب تنفيذها. استخدم البادئة ~/ للمهام المدمجة، مثل ~/winget، ~/powershell، و ~/gitclone.

displayName

(وتر)

يوفر نص عرض قصير لأسطح واجهة المستخدم.

description

(وتر)

يصف ما تفعله المهمة في تعريف الصورة.

parameters

(الموضوع)

يحدد قيم الإدخال المرسلة إلى المهمة. تعتمد أسماء المعاملات وأنواع القيم على المهمة المختارة.

تتبع تعريفات المعلمات نفس المخطط الموضح لخصائص task.yaml المعلمات. للتفاصيل، انظر ، ، ، ، ، validationRegex، maxLengthminLength، و required. descriptiondefaultallowedtype

timeout

(رقم صحيح)

يتجاوز مهلة تنفيذ المهمة خلال ثوان.

userTasks

(مصفوفة من كائنات المهام)

يسرد مهام التخصيص التي ستنفذها في سياق المستخدم بعد تسجيل الدخول. userTasks يستخدم نفس مخطط إدخال المهمة كما tasksفي .

userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo

buildProperties

(الموضوع)

يحدد إعدادات بناء محددة لتخصيص عملية بناء الصور.

buildProperties:
  networkConnection: corp-westus3

خصائص كائنات البناء

networkConnection

(وتر)

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

buildProperties:
  networkConnection: my-westus3

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

استخدم المهام المدمجة عندما تحتاج إلى إجراءات تخصيص شائعة دون إرفاق كتالوج. استخدم البادئة ~/ لاستدعاء مهمة مدمجة، على سبيل المثال ~/winget، ~/powershell، أو ~/gitclone.

• مهمة GitClone المدمجة
• مهمة PowerShell المدمجة
• مهمة WinGet المدمجة

مهمة GitClone المدمجة

استخدم مهمة GitClone المدمجة لاستنساخ مستودع في صندوق المطورين.

مثال:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main

repositoryUrl

(وتر، مطلوب)

يحدد رابط المستودع للنسخة.

directory

(النص، الافتراضي: C:\Workspaces)

يضبط الدليل الذي يتم استنساخ المستودع تحته.

branch

(وتر)

يختار فرعا ليستنسخه.

pat

(وتر)

يوفر رمز وصول شخصي لعمليات النسخ المصادقة عليها. عندما pat لا يتم توفيرها، يتم انتظار النسخة لأول تسجيل دخول للمستخدم. عند تزويد المهمة بالتزود patبالتزويد، يمكن أن تستنسخ المهمة أثناء التزويد. استخدم مرجعا سريا ل Key Vault بدلا من القيمة السرية الخام.

تقوم مهمة GitClone المدمجة أيضا بتثبيت PowerShell 7 وGit وGit LFS أثناء التنفيذ.

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

استخدم مهمة PowerShell المدمجة لتشغيل أمر أو سكريبت.

مثال:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"

command

(وتر)

يشغل أمر داخلي. إذا قدمت command، يتم تجاهل المعلمات script، scriptArgs، و scriptExecutionPolicy المعلمات.

workingDirectory

(وتر)

يضبط الدليل العامل للأمر أو السكريبت.

script

(وتر)

يحدد المسار إلى سكريبت PowerShell محلي أو بعيد لتشغيله. يتم تجاهل هذا المعامل عند command توفيره.

scriptArgs

(وتر)

يقدم حججا للنص. يتم تجاهل هذا المعامل عند command توفيره.

scriptExecutionPolicy

(السلسلة النصية، الافتراضية: Bypass)

يحدد سياسة التنفيذ للسكريبت. يتم تجاهل هذا المعامل عند command توفيره.

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

استخدم مهمة WinGet المدمجة لتثبيت حزمة مباشرة أو تطبيق ملف تكوين WinGet الخاص بها.

مثال:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16

configurationFile

(وتر)

يشير إلى ملف YAML لتكوين WinGet على الجهاز المحلي.

downloadUrl

(وتر)

يحدد عنوان URL عام لملف YAML لتكوين WinGet. يتم تحميل الملف إلى المسار في configurationFile.

inlineConfigurationBase64

(وتر)

يوفر ملف YAML لتكوين WinGet المشفر على Base64. تقوم المهمة بفك ترميزها إلى configurationFile، أو إلى ملف مؤقت إذا configurationFile لم يكن مضبوطا.

package

(وتر)

يثبت الحزمة مباشرة بالاسم. إذا كنت تستخدم مصدر ملف الإعدادات، فلن تحتاج إلى توفير package.

version

(وتر)

يثبت نسخة حزمة محددة. إذا كنت تستخدم مصدر ملف الإعدادات، فلن تحتاج إلى توفير version.

ملفات task.yaml

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

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

مثال على ملف task.yaml

$schema: "1.0"
name: install-vsix-extension
description: Install a Visual Studio extension from a VSIX package.
author: Contoso Corporation
command: .\install-extension.ps1 -VsixPath {{vsixPath}}
documentationURL: https://contoso.example/devbox/install-vsix-extension
keywords:
  - visual-studio
  - extension
parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.
timeout: 30
rebootRequired: false
documentation:
  notes: Use a path that is available during task execution.
  examples:
    - name: install-vsix-extension
      parameters:
        vsixPath: .\extensions\contoso.vsix

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

$schema: "1.0"
name: powershell
description: Execute a PowerShell command.
author: Microsoft Corporation
command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}
parameters:
  command:
    type: string
    default: ""
    required: true
    description: The command to execute.
  workingDirectory:
    type: string
    default: ""
    required: false
    description: The working directory in which to execute the command.

خصائص Task.yaml

$schema

(وتر، مطلوب)

يحدد نسخة المخطط لتعريف المهمة. الأمثلة الحالية تستخدم 1.0.

name

(وتر، مطلوب)

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

استخدم نفس قيود التسمية مثل باقي أدوات تخصيص صندوق التطوير. يجب أن يكون الاسم بين 3 و63 حرفا، يبدأ بحرف أبجدي رقمي، ويحتوي فقط على الأحرف الأبجدية الرقمية مثل -، .، أو _. / الحرف محجوز.

name: install-vsix-extension

command

(وتر، مطلوب)

يحدد أمر PowerShell الذي ينفذ المهمة. يعمل الأمر في Windows PowerShell على الجهاز المحلي. استخدم {{parameterName}} الصياغة للإشارة إلى قيم المعلمات في سلسلة الأوامر.

command: .\install-extension.ps1 -VsixPath {{vsixPath}}

على سبيل المثال:

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

description

(وتر)

يصف هدف المهمة.

description: This task executes a PowerShell command.

author

(وتر)

يحدد كاتب المهمة للتدقيق وحل المشكلة.

author: Contoso Corporation

issueNotificationEmail

(وتر)

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

documentationURL

(وتر)

روابط لتوثيق المهمة.

documentationURL: https://link.to/documentation

licenseURL

(وتر)

روابط لرخصة المهمة.

licenseURL: https://link.to/license

keywords

(مصفوفة من الوتر)

يسرد الكلمات المفتاحية التي تساعد المستهلكين في العثور على المهمة.

parameters

(الموضوع)

يحدد معلمات إدخال مسماة للمهمة. يمثل كل عنصر فرعي اسم معلمة ويمكنه تحديد نوع المعامل، القيم المسموح بها، القيمة الافتراضية، الوصف، قواعد التحقق، حدود الطول، وما إذا كان المعامل مطلوبا.

parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.

خصائص تعريف المعلمات

type

(النص، مطلوب، القيم المسموح بها: النص، البولياني، العدد)

يحدد نوع بيانات الإدخال.

allowed

(مصفوفة من الوتر)

يقيد الإدخال إلى مجموعة ثابتة من قيم السلاسل النصية المسموح بها.

default

(وتر، بوليان، أو رقم)

يحدد القيمة الافتراضية للمدخل.

description

(وتر)

يصف الإدخال.

validationRegex

(وتر)

يعرف تعبيرا منتظما يجب أن تتطابق قيم السلاسل النصية.

minLength

(رقم صحيح)

يحدد الحد الأدنى لطول القيم النصية.

maxLength

(رقم صحيح)

يحدد الحد الأقصى لطول السلاسل النصية.

required

(بوليان)

يشير إلى ما إذا كان يجب توفير المدخل. إذا تمَّ حَذفُه، يكونُ false هو الإعدَاد الافتِرَاضي.

timeout

(العدد الصحيح، الافتراضي: 30)

يضبط مهلة المهمة الافتراضية بالدقائق. إذا لم تحدد قيمة، فإن الإعداد الافتراضي هو 30 دقيقة.

timeout: 30

documentation

(الموضوع)

يوفر ملاحظات وأمثلة استدعاء يمكن للمستهلكين استخدام المهام عند إضافة المهمة إلى تعريف الصورة.

خصائص كائن التوثيق

notes

(وتر)

يضيف إرشادات أو تحفظات لمستهلكي المهمة.

examples

(مصفوفة من كائنات المهام)

يعرض أمثلة على استدعاءات المهام باستخدام نفس المخطط الذي تدخله المهام في imagedefinition.yaml.

rebootRequired

(بولي، افتراضي: خطأ)

يشير إلى ما إذا كانت المهمة تتطلب إعادة تشغيل بعد التنفيذ.

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

• تكوين تخصيصات الفريق - أنشئ imagedefinition.yaml ملفات وطبقها على مجموعة صناديق التطوير.
• قم بتكوين ملف تخصيص المستخدم لصندوق التطوير الخاص بك - قم بكتابة ورفع ملف شخصي devbox.yaml .
• قم بتكوين المهام لتخصيص صندوق التطوير - قم بتأليف task.yaml الملفات ونشرها من خلال كتالوج.
• Connect to Azure resources أو Clone Private Repositories