أداة إنشاء حزم الحلول

إن SolutionPackager عبارة عن أداة يمكنها أن تقوم بشكل عكسي بتفكي حل مضغوط من Microsoft Dataverse إلى ملفات XML وملفات أخرى متعددة. يمكنك بعد ذلك إدارة هذه الملفات بسهولة باستخدام نظام التحكم بالمصدر. توضح الأقسام التالية كيفية تشغيل الأداة وكيفيه استخدامها مع الحلول المُدارة وغير المُدارة.

أين يمكن العثور على الأداة SolutionPackager

يتم توزيع الأداة SolutionPackager كجزء من حزمة Microsoft.CrmSdk.CoreTools NuGet. لتثبيت البرنامج، اتبع الخطوات التالية.

1. قم بتنزيل حزمة NuGet.
2. أعد تسمية ملحق اسم ملف الحزمة من nupkg. إلى zip.
3. استخرج محتويات الملف المضغوط (zip).

ستعثر على الملف القال للتنفيذ SolutionPackager.exe في المجلد <extracted-folder-name>/contents/bin/coretools. قم بتشغيل البرنامج من مجلد coretools أو أضف هذا المجلد إلى PATH الخاص بك.

وسيطات سطر أوامر SolutionPackager

إن SolutionPackager عبارة عن أداة سطر أوامر يمكن استدعاؤها مع المعلمات المحددة في الجدول التالي.

الوسيطة	الوصف
/action: {Extract|Pack}	مطلوب. الإجراء المطلوب تنفيذه. بإمكان الإجراء أن يكون استخراج ملف الحل zip. إلى مجلد، أو حزم مجلد إلى ملف zip.
/zipfile: <file path>	مطلوب. مسار واسم ملف zip. الخاص بالحل. عند الاستخراج، يجب أن يكون الملف موجودًا وقابلاً للقراءة. عند الحزم، يتم استبدال الملف.
/folder: <folder path>	مطلوب. المسار إلى مجلد. عند الاستخراج، يتم إنشاء هذا المجلد وتعبئته بملفات المكونات. عند الحزم، يلزم وجود هذا الملف وأن يحتوي على ملفات المكونات المستخرجة في السابق.
/packagetype: {Unmanaged|Managed|Both}	اختياري. نوع الحزمة التي يجب معالجتها. القيمة الافتراضية هي Unmanaged. قد يتم حذف هذه الوسيطة في معظم الحالات لأنه يمكن قراءة نوع الحزمة من داخل ملف zip. أو ملفات المكونات. عند الاستخراج وإذا كان الخيار Both محددًا، يلزم وجود ملفات zip. المُدارة وغير المُدارة وتتم معالجتها في مجلد واحد. عند إنشاء الحزمة، وإذا كان الخيار "كلاهما" محددًا، سيتم إنتاج ملفات zip. المُدارة وغير المُدارة من مجلد واحد. لمزيد من المعلومات، راجع القسم الخاص بالعمل مع الحلول المُدارة وغير المُدارة لاحقًا في هذا الموضوع.
/allowWrite:{Yes|No}	اختياري. القيمة الافتراضية هي نعم. يتم استخدام هذه الوسيطة فقط أثناء الاستخراج. عند تحديد /allowWrite:No، تقوم الأداة بتنفيذ جميع العمليات ولكنها تُمنع من الكتابة فوق أي ملفات أو حذفها. يمكن تقييم عملية الاستخراج بأمان بدون الكتابة فوق أي ملفات موجودة أو حذفها.
/allowDelete:{Yes|No|Prompt}	اختياري. القيمة الافتراضية هي Prompt. يتم استخدام هذه الوسيطة فقط أثناء الاستخراج. عند تحديد /allowDelete:Yes، تُحذف بشكل تلقائي الملفات الموجودة في المجلد المحدد بواسطة المعلمة /folder وغير المتوقعة. عند تحديد /allowDelete:No، لا تحدث أي عمليات حذف. عند تحديد /allowDelete:Prompt، تتم مطالبة المستخدم عبر وحدة التحكم للسماح بجميع عمليات الحذف أو رفضها. إذا تم تحديد /allowWrite:No، فلن تحدث أي عمليات حذف حتى لو تم أيضًا تحديد /allowDelete:Yes.
/clobber	اختياري. يتم استخدام هذه الوسيطة فقط أثناء الاستخراج. عند تحديد /clobber، تتم الكتابة فوق الملفات التي تم فيها تعيين سمة القراءة فقط أو يتم حذفها. عند عدم تحديد هذه المعلمة،لا تتم الكتابة فوق الملفات التي تم فيها تعيين سمة القراءة فقط أو لا يتم حذفها.
/errorlevel: {Off|Error|Warning|Info|Verbose}	اختياري. القيمة الافتراضية هي Info. تشير هذه الوسيطة إلى مستوى معلومات التسجيل إلى مخرجات.
/map: <file path>	اختياري. مسار واسم ملف xml. يحتوي على توجيهات تعيين الملفات. عند استخدامه أثناء الاستخراج، تتم قراءة الملفات التي تتم قراءتها عادةً من داخل المجلد المحدد بواسطة المعلمة /folder من مواقع بديلة كما حددها ملف التعيين. أثناء عملية الحزم، لا تتم كتابة الملفات التي تتطابق مع التوجيهات.
/nologo	اختياري. منع الشعار في وقت التشغيل.
/log: <file path>	اختياري. مسار واسم لملف السجل. إذا كان الملف موجودًا، يتم إلحاق معلومات التسجيل الجديدة بالملف.
@ <file path>	اختياري. مسار واسم ملف يحتوي على وسائط سطر الأوامر للأداة.
/sourceLoc: <string>	اختياري. هذه الوسيطة تقوم بإنشاء ملف موارد القالب، وهي صالحة فقط عند الاستخراج. القيم المحتملة هي auto أو كود LCID/ISO للغة التي تريد تصديرها. عند استخدام هذه الوسيطة، يتم استخراج موارد السلسلة من الإعدادات المحلية المعينة كملف resx. محايد. إذا تم تحديد auto أو النموذج الطويل أو القصير فقط لمفتاح التبديل، فسيتم استخدام الإعدادات المحلية الأساسية أو الحل فقط. يمكنك استخدام النموذج القصير للأمر: /src.
/localize	اختياري. استخراج أو دمج كافة موارد السلسلة في ملفات resx. يمكنك استخدام النموذج القصير للأمر: /loc. يدعم خيار الترجمة المكونات المشتركة لملفات .resx. مزيد من المعلومات: استخدام موارد ويب RESX

استخدم وسيطة الأمر /map

تفصل المناقشة التالية استخدام الوسيطة /map في الأداة SolutionPackager.

لا يتم عادةً التحقق من الملفات المُنشأة في نظام إنشاء تلقائي، مثل ملفات xap Silverlight. وتجميعات المكونات الإضافية في عنصر تحكم المصدر. قد تكون موارد الويب موجودة بالفعل في نظام التحكم بالمصدر في المواقع التي لا تتوافق مباشرةً مع الأداة SolutionPackager. ومن خلال تضمين المعلمة /map، يمكن توجيه الأداة SolutionPackager لقراءة هذه الملفات وحزمها من مواقع بديلة وليس من داخل مجلد الاستخراج كما يتم عادةً. يجب أن تحدد معلمة /map الاسم والمسار إلى ملف XML الذي يحتوي على توجيهات التعيين. وترشد هذه التوجيهات SolutionPackager لمطابقة الملفات حسب اسمها ومسارها، وتشير إلى الموقع البديل للعثور على الملف المطابق. تنطبق المعلومات التالية على كافة توجيهات بالتساوي.

• قد يتم إدراج توجيهات متعددة بما في ذلك تلك التي ستطابق ملفات مماثلة. التوجيهات المدرجة سابقًا في الملف ستكون لها الأسبقية على تلك المدرجة لاحقًا.

• إذا تطابق ملف مع أي توجيه، يجب العثور عليه في موقع بديل واحد على الأقل. إذا لم يتم العثور على بدائل مطابقه، فسيصدر SolutionPackager رسالة خطأ.

• قد تكون مسارات المجلد والملفات مطلقة أو نسبية. يتم تقييم المسارات النسبية دائمًا من المجلد المحدد بواسطة المعلمة /folder.

• يمكن تحديد متغيرات البيئة باستخدام بناء جملة %variable%.

• قد يتم استخدام حرف بدل المجلد "**" بحيث يعني “في أي مجلد فرعي”. ويمكن استخدامه فقط كجزء أخير من مسار، على سبيل المثال: “c:\folderA\**”.

• يمكن استخدام أحرف البدل في اسم الملف فقط في النماذج “*.ext” أو “*.*”. لا يوجد نمط آخر مدعوم.

  تم هنا وصف الأنواع الثلاثة لتعيينات التوجيهات، إلى جانب مثال يوضح كيفية استخدامها.

تعيين المجلد

توفر المعلومات التالية معلومات تفصيلية حول تعيين المجلد.

تنسيق Xml

<Folder map="folderA" to="folderB" />

الوصف

يتم تبديل مسارات الملفات التي تطابق "folderA" إلى "folderB".

• يجب أن يتطابق التدرج الهرمي للمجلدات الفرعية تحت كل واحد منها بشكل تام.

• أحرف بدل المجلد غير مدعومة.

• لا يمكن تحديد أي أسماء ملفات.

  الأمثلة

  <Folder map="folderA" to="folderB" />  
  <Folder map="folderA\folderB" to="..\..\folderC\" />  
  <Folder map="WebResources\subFolder" to="%base%\WebResources" />  
  

تعيين من ملف إلى ملف

توفر المعلومات التالية المزيد من التفاصيل حول التعيين من ملف إلى ملف.

تنسيق Xml

<FileToFile map="path\filename.ext" to="path\filename.ext" />

الوصف

ستتم قراءة أي ملف يطابق المعلمة map من الاسم والمسار المحددين في المعلمة to.

فيما يتعلق بالمعلمة map:

• يجب تحديد اسم ملف. المسار اختياري. إذا لم يتم تحديد أي مسار، قد تتم مطابق ملفات من أي مجلد.

• أحرف بدل اسم الملف غير مدعومة.

• حرف بدل المجلد مدعوم.

  فيما يتعلق بالمعلمة to:

• يجب تحديد اسم ملف ومسار.

• قد يختلف اسم الملف عن الاسم الموجود في المعلمة map.

• أحرف بدل اسم الملف غير مدعومة.

• حرف بدل المجلد مدعوم.

الأمثلة

  <FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />  
  <FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />  
  <FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />  

  <FileToFile
    map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
    to="myplg\bin\Debug\myplg.1.0.0.nupkg" /> 

في المثال السابق حول الحزمة، NuGet لا تتم الكتابة فوق cr886_PluginPackageTest.nupkg إذا كان الملف موجودًا في الموقع المحدد.

تعيين من ملف إلى مسار

يوفر التالي معلومات تفصيلية حول التعيين من ملف إلى مسار.

تنسيق Xml

<FileToPath map="path\filename.ext" to="path" />

الوصف

تتم قراءة أي ملف يطابق المعلمة map من الاسم والمسار المحددين في المعلمة to.

فيما يتعلق بالمعلمة map:

• يجب تحديد اسم ملف. المسار اختياري. إذا لم يتم تحديد أي مسار، قد تتم مطابق ملفات من أي مجلد.

• أحرف بدل اسم الملف مدعومة.

• حرف بدل المجلد مدعوم.

فيما يتعلق بالمعلمة to:

• يجب تحديد مسار.

• حرف بدل المجلد مدعوم.

• يجب عدم تحديد اسم ملف.

  الأمثلة

  <FileToPath map="assembly.dll" to="c:\path\folder" />  
  <FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />  
  <FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />  
  <FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />  

مثال على التعيين

تعرض عينة التعليمات البرمجية XML التالية ملف تعيين كاملاً يمكّن الأداة SolutionPackager من قراءة أي مورد ويب والتجميعين الافتراضيين الناشئين من مشروع مجموعة أدوات المطور المسماة CRMDevTookitSample.

<?xml version="1.0" encoding="utf-8"?>  
<Mapping>  
       <!-- Match specific named files to an alternate folder -->  
       <FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />  
       <FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />  
       <!-- Match any file in and under WebResources to an alternate set of sub-folders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>  

الحلول المُدارة وغير المُدارة

يمكن تصدير ملف الحل المضغوط (zip.) في Dataverse إلى أحد النوعين كما هو موضح هنا.

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

الحل غير المُدار
حل مفتوح بدون قيود على ما يمكن إضافته أو إزالته أو تعديله. ينصح بهذا أثناء تطوير أحد الحلول.

سيختلف تنسيق ملف الحل المضغوط استنادًا إلى نوعه، إما مُدار أو غير مُدار. بإمكان SolutionPackager معالجة ملفات الحلول المضغوطة من أي نوع ومع ذلك، لا يمكن للأداة تحويل نوع إلى آخر. الطريقة الوحيدة لتحويل ملفات الحلول إلى نوع مختلف، على سبيل المثال من غير مُدار إلى مُدار، هي استيراد ملف zip. الخاص بالحل غير المُدار إلى خادم Dataverse ثم تصدير الحل كحل مُدار.

بإمكان SolutionPackager معالجة ملفات zip. للحل المُدار وغير المُدار كمجموعة مدمجة عبر المعلمة /PackageType:Both. لتنفيذ هذه العملية، من الضروري تصدير حلك مرتين ككل نوع، وتسمية ملفات zip. كما يلي.

ملف zip. غير مُدار: AnyName.zip	ملف zip. مُدار: AnyName_managed.zip

ستفترض الأداة وجود ملف zip المُدار في نفس المجلد حيث الملف غير المُدار وستستخرج الملفين إلى مجلد واحد للحفاظ على الاختلافات حيث توجد مكونات مُدارة وغير مُدارة.

وبعد استخراج حل كمُدار وغير مُدار، من الممكن، من هذا المجلد الفردي إنشاء حزمة من النوعين أو كل نوع بشكل فردي باستخدام المعلمة /PackageType لتحديد النوع الذي يجب إنشاؤه. عند تحديد الملفين، سيتم إنتاج ملفي zip باستخدام اصطلاح التسمية كما هو موضح أعلاه. في حال عدم وجود المعلمة /PackageType عند إنشاء الحزمة من مجلد مزدوج مُدار وغير مُدار، فسينتج المجلد ملف zip. واحدًا غير مُدار.

استكشاف الأخطاء وإصلاحها

إذا استخدمت Visual Studio لتحرير ملفات الموارد التي تم إنشاؤها بواسطة أداة إنشاء حزم الحلول‬، فقد تتلقي رسالة عندما تعيد إنشاء الحزم مماثلة للرسالة التالية: “Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process.” يحدث ذلك لأن Visual Studio يحل محل علامات بيانات تعريف ملف الموارد بواسطة علامات البيانات.

الطرق البديلة

1. افتح ملف الموارد في محرر النصوص المفضل وحدد موقع العلامات التالية وقم بتحديثها:

   <data name="Source LCID" xml:space="preserve">  
   <data name="Source file" xml:space="preserve">  
   <data name="Source package type" xml:space="preserve">  
   <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">  
   
   

2. قم بتغيير اسم العقدة من <data> إلى <metadata>.

   على سبيل المثال، هذه السلسلة:

   <data name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </data>  
   
   

   تتغير إلى:

   <metadata name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </metadata>  
   
   

   يسمح هذا الأمر لأداة إنشاء حزم الحلول بقراءة ملف الموارد واستيراده. تمت ملاحظة هذه المشكلة فقط عند استخدام محرر الموارد في Visual Studio.

راجع أيضًا

استخدام عنصر التحكم بالمصدر مع ملفات الحلول

مفاهيم الحلول