مرجع تنسيق التحكم في مصدر YAML للحل

هذه المقالة هي مرجع لتنسيق التحكم بالمصادر المستند إلى YAML المستخدم عند:

• تنفيذ الحلول باستخدام تكامل Dataverse Git الأصلي في Power Apps.
• استخراج الحلول باستخدام pac solution clone أو pac solution sync.
• تشغيل SolutionPackager يدويا مقابل مجلد يحتوي على ملفات بيان YAML.

يختلف تنسيق YAML عن تخطيط XML الكلاسيكي. يعد فهم البنية أمرا مهما عندما تريد حزم مجلد YAML يدويا مرة أخرى في .zip ملف يمكن ل Dataverse استيراده.

مهم

يتطلب دعم تنسيق عنصر تحكم مصدر YAML في pac CLI Microsoft. PowerApps.CLI الإصدار 2.4.1 أو أحدث. قم بتنزيل أحدث إصدار من NuGet أو تحديثه عبر pac install latest. يدعم SolutionPackager.exe، الذي يتم شحنه مع حزمة NuGet، تنسيق YAML من نفس الإصدار.

نظرة عامة على بنية المجلد

يحتوي جذر مستودع بتنسيق YAML على الدلائل التالية ذات المستوى الأعلى:

<repositoryRoot>/
├── solutions/
│   └── <SolutionUniqueName>/       (one subfolder per solution)
│       ├── solution.yml
│       ├── solutioncomponents.yml
│       ├── rootcomponents.yml
│       └── missingdependencies.yml
├── publishers/
│   └── <PublisherUniqueName>/      (one subfolder per publisher)
│       └── publisher.yml
├── entities/                        (entity components, if any)
│   └── <entity_schema_name>/
│       ├── attributes/
│       ├── formxml/
│       ├── savedqueries/
│       └── ...
├── workflows/                       (classic workflow definitions, if any)
├── modernflows/                     (Power Automate cloud flows, if any)
├── canvasapps/                      (canvas app .msapp files, if any)
│   └── <canvas_app_schema_name>/
│       └── <name>.msapp
├── environmentvariabledefinitions/  (environment variable definitions, if any)
├── connectors/                      (custom connectors, if any)
└── [other component folders]/

الدليلان solutions/ و publishers/ مطلوبان. جميع مجلدات المكونات في الجذر اختيارية وتعتمد على ما يحتوي عليه الحل.

مهم

يجب وضع جميع ملفات بيان YAML (solution.yml، publisher.ymlو، وما إلى ذلك) ضمن الدلائل الفرعية الخاصة بها (solutions/<name>/، publishers/<name>/). يؤدي وضعها في جذر المستودع إلى منع اكتشاف التنسيق ويؤدي إلى عودة أداة SolutionPackager إلى تنسيق XML — ما ينتج عنه خطأ مضلل حول مفقود Customizations.xml. مزيد من المعلومات: استكشاف أخطاء أداة SolutionPackager وإصلاحها

تنسيق الكشف التلقائي

SolutionPackager (و pac solution pack) الكشف التلقائي عن التنسيق كما يلي:

الشرط	التنسيق المكتشف	السلوك
solutions/*/solution.yml found — حل واحد	YAML	تم استنتاج اسم الحل من اسم المجلد الفرعي
solutions/*/solution.yml تم العثور على — حلول متعددة	YAML	/SolutionName الوسيطة المطلوبة لتحديد الحل المطلوب حزمه
لا يوجد solutions/ دليل فرعي	XML (قديم)	يتوقع و Other\Solution.xmlOther\Customizations.xml

ملفات البيان

solution.yml

يقع في solutions/<SolutionUniqueName>/solution.yml. يحتوي على بيانات تعريف الحل ذات المستوى الأعلى — أي ما يعادل solution.xml YAML بتنسيق XML.

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

solutioncomponents.yml

يقع في solutions/<SolutionUniqueName>/solutioncomponents.yml. يسرد المسارات النسبية لكافة ملفات المكونات المضمنة في هذا الحل. يقرأ SolutionPackager هذا الملف أثناء الحزمة لتحديد موقع مصادر المكونات.

مثال مقتطف:

- Path: entities/account
- Path: entities/contact
- Path: canvasapps/myapp_<guid>
- Path: publishers/MyPublisher

rootcomponents.yml

يقع في solutions/<SolutionUniqueName>/rootcomponents.yml. يسرد مكونات مستوى الجذر (عادة الجداول وعناصر المستوى الأعلى الأخرى) التي تنتمي إلى هذا الحل.

ملحوظة

إذا تم الإعلان عن مكون في rootcomponents.yml ولكن ملفاته المصدر غير موجودة من المجلد (على سبيل المثال، ملف تطبيق .msapp اللوحة ضمن canvasapps/<name>/)، يصدر SolutionPackager تحذيرا ويحذف هذا المكون من الحزمة .zip. لا تزال عملية الحزمة تكتمل بنجاح مع رمز الخروج 0.

لا يضمن نجاح الحزمة نجاح الاستيراد. إذا solutioncomponents.yml حذف مسارات التبعية المطلوبة — مثل مجلدات الكيان الأصل أو تعريفات العلاقات ضمن entityrelationships/ — حزم الحل دون خطأ ولكنها تفشل في الاستيراد مع رسالة مثل: "السمات مفقودة تعريفات العلاقة المقترنة." تأكد دائما من solutioncomponents.yml تضمين جميع الكيانات والعلاقات التابعة، وليس فقط الكيانات المملوكة للحل.

missingdependencies.yml

يقع في solutions/<SolutionUniqueName>/missingdependencies.yml. يسجل أي تبعيات حل لم تكن موجودة عند آخر تصدير للحل. يستخدم لأغراض إعلامية وللتحقق من اكتمال الاستيراد.

publisher.yml

يقع في publishers/<PublisherUniqueName>/publisher.yml. يحتوي على تعريف الناشر — الاسم الفريد واسم العرض وبادئة التخصيص وبادئة قيمة الخيار.

الحد الأدنى من البنية المطلوبة:

Publisher:
  UniqueName: mypublisher
  LocalizedNames:
    LocalizedName:
      '@description': My Publisher
      '@languagecode': '1033'
  Descriptions:
  EMailAddress:
    '@xsi:nil': 'true'
    '@xmlns:xsi': http://www.w3.org/2001/XMLSchema-instance
  SupportingWebsiteUrl:
    '@xsi:nil': 'true'
    '@xmlns:xsi': http://www.w3.org/2001/XMLSchema-instance
  CustomizationPrefix: myp
  CustomizationOptionValuePrefix: '12345'
  Addresses:

دعم نوع المكون

يسرد الجدول التالي كيفية معالجة كل نوع مكون بتنسيق YAML.

نوع المكون	بتنسيق YAML	الملاحظات
الكيانات (الجداول) والسمات والنماذج وطرق العرض	✓ ملفات YAML	مخزنة كملفات YAML فردية لكل أداة فرعية
مهام سير العمل (الكلاسيكية)	✓ ملفات YAML	تحت workflows/
التدفقات الحديثة (Power Automate تدفقات السحابة)	✓ — تنسيق YAML فقط	ضمن modernflows/؛ غير معتمد في تنسيق XML
تَطبِيقَات اللوحة	✓ — تنسيق YAML فقط	.msapp ثنائي ضمن canvasapps/<name>/؛ غير معتمد بتنسيق XML
تعريفات متغير البيئة	✓ ملفات XML	الملفات الفردية .xml ضمن environmentvariabledefinitions/
قيم متغيرات البيئة	✓ ملف JSON	مخزن ك environment_variable_values.json
الموصلات المخصصة	✓	تحت connectors/
تجميعات المكونات الإضافية	✓	أسماء الأنواع المؤهلة بالكامل التي تم إعادة تعيينها بشكل افتراضي (/remapPluginTypeNames)
موارد الويب	✓	تحت webresources/
أدوار الأمان	✓	مخزنة ك XML داخليا؛ تمت تصفيته لكل حل
مجموعات الخيارات (عمومية)	✓	مخزنة ك XML؛ تمت تصفيته لكل حل
Dashboards	✓	مخزنة ك XML؛ تمت تصفيته لكل حل
خرائط المواقع	✓	مخزنة ك XML؛ تمت تصفيته لكل حل
تخصيصات الشريط	✓	مخزنة ك XML؛ تمت تصفيته لكل حل
علاقات الكيان	✓	تحت entityrelationships/

ملحوظة

يتم تحويل المكونات المخزنة ك XML داخليا تلقائيا بين XML وYAML أثناء عمليات الحزم وفك الحزم. يمكنك تأليفها كملفات YAML؛ تعالج الأداة التحويل.

مستودعات الحلول المتعددة

يمكن أن يحتوي جذر مستودع واحد على حلول متعددة. تشترك جميع الحلول في نفس مجلدات المكونات؛ solutioncomponents.yml في كل حل يتحكم في مسارات المكونات التي تنتمي إلى هذا الحل.

مثال على البنية مع حلين:

<repositoryRoot>/
├── solutions/
│   ├── SolutionA/
│   │   ├── solution.yml
│   │   ├── solutioncomponents.yml    ← references entities/account, entities/contact
│   │   ├── rootcomponents.yml
│   │   └── missingdependencies.yml
│   └── SolutionB/
│       ├── solution.yml
│       ├── solutioncomponents.yml    ← references entities/lead, workflows/myflow
│       ├── rootcomponents.yml
│       └── missingdependencies.yml
├── publishers/
│   └── SharedPublisher/
│       └── publisher.yml
├── entities/
│   ├── account/
│   ├── contact/
│   └── lead/
└── workflows/
    └── myflow/

حزم حل معين من مجلد متعدد الحلول

استخدام SolutionPackager.exe:

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

استخدام pac solution pack (مجلدات حل واحد فقط — للحلول المتعددة، استخدم SolutionPackager.exe مباشرة مع /SolutionName):

pac solution pack --zipfile SolutionA.zip --folder C:\repos\myrepo

ملحوظة

عند استخدام تكامل Dataverse Git الأصلي مع ربط البيئة، تشترك جميع الحلول في البيئة في جذر مستودع واحد باستخدام تخطيط الحلول المتعددة. عند استخدام ربط الحل، يمكن ربط كل حل بمجلد منفصل.

استخدام مجلدات تنسيق YAML

حزم مجلد YAML في ملف .zip

# Using pac CLI (single solution in folder)
pac solution pack --zipfile C:\output\MySolution.zip --folder C:\repos\myrepo

# Using SolutionPackager.exe directly (also works for multi-solution with /SolutionName)
SolutionPackager.exe /action:Pack /zipfile:C:\output\MySolution.zip /folder:C:\repos\myrepo

الحصول على مجلد YAML كامل من Dataverse

الطريقة الموصى بها للحصول على مجلد YAML كامل ومعبأة هي استخدام pac solution clone:

pac solution clone --name MySolutionUniqueName --outputDirectory C:\repos\myrepo

هذا يستخرج الحل في تنسيق YAML، بما في ذلك جميع ملفات مصدر المكونات. بدلا من ذلك، استخدم تكامل Git الأصلي للتثبيت من Power Apps — الملفات الملتزم بها بتنسيق YAML وقابلة للتعبئة بالكامل.

تحقق من المجلد قبل التعبئة

تحقق من وجود solutions/<name>/ المجلد ومن حل كافة المسارات solutioncomponents.yml إلى الملفات الفعلية. تؤدي أي مسارات مفقودة إلى تحذيرات أثناء الحزمة ويتم حذف هذه المكونات.

العلاقة ب تكامل Dataverse Git

تنسيق التحكم في مصدر YAML هو التنسيق المتعارف عليه المستخدم من قبل تكامل Dataverse Git. عندما يلتزم المصنعون بحلول من Power Apps، تستخدم الملفات المكتوبة إلى موفر Git هذا التنسيق. يمكن لمطوري التعليمات البرمجية أولا العمل مع نفس المستودع باستخدام أدوات CLI الموضحة هنا.

للحصول على معلومات حول توصيل البيئات ب Git، راجع إعداد تكامل Dataverse Git.

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

• أداة إنشاء حزم الحلول
• التحكم بالمصادر باستخدام ملفات الحل
• حزمة حلول pac
• فك حزمة حل pac
• نظرة عامة على تكامل Dataverse Git