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

تسمح الأداة Package Deployer للمسؤولين بنشر الحزم على مثيلات Microsoft Dataverse. بإمكان Package Deployer الحزمة أن تتكون من أي أو من كل ما يلي:

• ملف حلول Dataverse واحدًا أو أكثر.
• ملفات ثابتة أو ملفات بيانات تم تصديرها من أداة ترحيل التكوين‬. لمزيد من المعلومات حول الإدارة، راجع نقل بيانات التكوين عبر المثيلات والمؤسسات باستخدام أداة ترحيل التكوين.
• التعليمات البرمجية المخصصة التي يمكن تشغيلها قبل نشر الحزمة أو أثناء أو بعد نشر الحزمة إلى مثيل Dataverse.
• محتوى HTML المحدد للحزمة والذي يمكن عرضه في بداية عملية نشر الحزمة ونهايتها. قد يكون هذا المحتوى مفيداً لتوفير وصف للحلول والملفات التي يتم نشرها في الحزمة.

المتطلبات

• تأكد من أن لديك كل الحلول والملفات الأخرى الجاهزة التي تريد تضمينها في الحزمة.
• Visual Studio 2019 أو احدثا Visual Studio Code.

نظرة عامة على العملية

لانشاء Package Deployer الحزمة، قم بالخطوات التالية.

يتم وصف هذه الخطوات بالتفصيل في هذه المقالة.

إنشاء مشروع حزمة

الخطوة الأولى هي إنشاء Visual Studio أو مشروع MSBuild للحزمة. للقيام بذلك، يجب أن يكون لديك واحد من اثنين من ملحقات الأدوات المتاحة المثبتة على جهاز الكمبيوتر الخاص بك. باستخدام Visual Studio Code, قم بتثبيت Microsoft Power Platform CLI. بخلاف ذلك، إذا كنت تستخدم Visual Studio 2019 أو إصدار لاحق، فقم بتثبيت Power Platform Tools لـ Visual Studio.

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

pac package init help
pac package init --outputDirectory DeploymentPackage

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

إضافة ملفات الحزم

بعد إنشاء مشروع الحزمة، يمكنك البدء في إضافة الحلول والملفات الأخرى إلى هذا المشروع.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

تكوين الحزمة

قم بتعريف تكوين الحزمة عن طريق إضافة معلومات حول حزمتك في ملف ImportConfig.xml في المشروع. راجع مرجع ImportConfig للحصول على مثال ووصف للعناصر والسمات الصالحة للاستخدام.

إضافة رمز مخصص

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

1. قم بتحرير ملف PackageTemplate.cs (أو PackageImportExtension.cs) في المجلد الجذر للمشروع.

2. في ملف #C، يمكنك:

   1. إدخال تعليمات برمجية مخصصة يتم تنفيذها عند تهيئه الحزمة في تعريف أسلوب تجاوز InitializeCustomExtension.

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

      على سبيل المثال، تقوم عينة التعليمات البرمجية التالية بتمكين معلمة وقت تشغيل مسماة SkipChecks للحزمة التي تحتوي على قيمتين محتملتين: true أو false. تتحقق عينة التعليمات البرمجية مما إذا كان المستخدم قد قام بتحديد معلمات وقت التشغيل أثناء تشغيل Package Deployer (اما باستخدام سطر الأوامر أو PowerShell) ثم يعالج التبعيات وفقًا لذلك. إذا لم يتم تحديد معلمات وقت التشغيل بواسطة المستخدم أثناء تشغيل الحزمة، فستكون قيمة الخاصية RuntimeSettings فارغة.

      public override void InitializeCustomExtension()  
      {  
      // Do nothing.  
      
      // Validate the state of the runtime settings object.  
      if (RuntimeSettings != null)  
      {  
      PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
      foreach (var setting in RuntimeSettings)  
      {  
      PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
      }  
      
      // Check to see if skip checks is present.  
      if ( RuntimeSettings.ContainsKey("SkipChecks") )  
      {  
      bool bSkipChecks = false;  
      if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
      OverrideDataImportSafetyChecks = bSkipChecks;  
      }  
      }  
      else  
      PackageLog.Log("Runtime Settings not populated");  
      }  
      

      يتيح هذا الرمز للمسؤول استخدام سطر الأوامر أو Import-CrmPackage cmdlet لتحديد ما إذا كان سيتم تخطي عمليات التحقق من السلامة أثناء تشغيل الأداة Package Deployer لاستيراد الحزمة. مزيد من المعلومات: نشر الحزم باستخدام Package Deployer وWindows PowerShell

   2. أدخل التعليمات البرمجية المخصصة التي سيتم تنفيذها قبل استيراد الحلول في تعريف أسلوب تجاوز PreSolutionImport لتحديد ما إذا كان سيتم الاحتفاظ بالتخصيصات أو الكتابة فوقها أثناء تحديث الحل المحدد في مثيل Dataverse الهدف، وما إذا كان سيتم تنشيط المكونات الإضافية وعمليات سير المهام بشكل تلقائي.

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

      تتوقع هذه الدالة المعلمات التالية:

      المعلمة‬	‏‏الوصف
      solutionName	اسم الحل
      oldVersion	رقم إصدار الحل القديم
      newVersion	رقم إصدار الحل الجديد
      oldSolutionId	GUID الحل القديم.
      newSolutionId	GUID الحل الجديد.

   4. أدخل تعليمات برمجية مخصصة يتم تنفيذها قبل اكتمال عملية استيراد الحل في تعريف أسلوب تجاوز BeforeImportStage. يتم استيراد عينة البيانات وبعض الملفات الثابتة للحلول في ملف ImportConfig.xml قبل اكتمال استيراد الحل.

   5. تجاوز اللغة المحددة حاليًا لاستيراد بيانات التكوين باستخدام تعريف أسلوب تجاوز OverrideConfigurationDataFileLanguage. إذا لم يتم العثور على معرف الإعدادات المحلية (LCID) المحدد للغة المحددة في قائمه اللغات المتوفرة في الحزمة، سيتم استيراد ملف البيانات الافتراضي.

      يمكنك تحديد اللغات المتوفرة لبيانات التكوين في العقدة <cmtdatafiles> في الملف ImportConfig.xml. يتم تحديد ملف استيراد بيانات التكوين الافتراضي في السمة crmmigdataimportfile في الملف ImportConfig.xml.

      بإمكان تخطي عمليات التحقق من البيانات (OverrideDataImportSafetyChecks = true) يمكن أن يكون فعالاً هنا إذا كنت متأكدًا من أن الهدف Dataverse المثيل لا يحتوي على أية بيانات.

   6. أدخل تعليمات برمجية مخصصة يتم تنفيذها بعد اكتمال عملية استيراد الحل في تعريف أسلوب تجاوز AfterPrimaryImport>. يتم الآن استيراد الملفات الثابتة المتبقية التي لم يتم استيرادها في السابق قبل بدء استيراد الحل.

   7. قم بتغيير الاسم الافتراضي لمجلد الحزمة إلى اسم الحزمة الذي تريده. للقيام بذلك، أعد تسمية مجلد PkgFolder (أو PkgAssets) في جزء مستكشف الحلول، ثم قم بتحرير قيمة الإرجاع ضمن خاصية GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
      {  
      get  
      {  
      // WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
      // Changing this name requires that you also change the correlating name in the Solution Explorer  
      return "PkgFolder";  
      }  
      }  
      

   8. قم بتغيير اسم الحزمة عن طريق تحرير القيمة المرتجعة تحت الخاصية GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
      {  
      return "Package Short Name";  
      }  
      

      هذه القيمة التي تم إرجاعها هي اسم الحزمة الخاصة بك التي تظهر في صفحة اختيار الحزمة في معالج Dynamics 365 Package Deployer .

   9. قم بتغيير وصف الحزمة عن طريق تحرير القيمة المرتجعة تحت الخاصية GetImportPackageDescriptionText.

      
      public override string GetImportPackageDescriptionText  
      {  
      get { return "Package Description"; }  
      }  
      
      

      هذه القيمة التي تم إرجاعها هي وصف الحزمة الذي يظهر بجانب اسم الحزمة في صفحة اختيار الحزمة في ملف معالج Package Deployer.

   10. قم بتغيير اسم الحزمة الطويل عن طريق تحرير القيمة المرتجعة تحت الخاصية GetLongNameOfImport.

       
       public override string GetLongNameOfImport  
       {  
       get { return "Package Long Name"; }  
       }  
       
       

       يظهر اسم الحزمة الطويل في الصفحة التالية بعد تحديد الحزمة لتثبيتها.

3. علاوةً على ذلك، تتوفر الدالات والمتغيرات التالية للحزمة:

   الاسم	كتابة	‏‏الوصف
   CreateProgressItem(String)	الوظيفة	تُستخدم لإنشاء عنصر تقدم جديد في واجهة المستخدم (UI).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	الوظيفة	تُستخدم لتحديث التقدم الذي نشأ بواسطة استدعاء CreateProgressItem(String). ProgressPanelItemStatus هو تعداد التعداد بالقيم التالية: العمل = 0 مكتمل = 1 فاشل = 2 تحذير = 3 غير معروف = 4
   RaiseFailEvent(String, Exception)	الوظيفة	تُستخدم لإفشال استيراد الحالة الحالية مع رسالة استثناء.
   IsRoleAssoicatedWithTeam(Guid, Guid)	الوظيفة	تُستخدم لتحديد ما إذا كان الدور مرتبطًا بفريق محدد.
   IsWorkflowActive(Guid)	الوظيفة	تُستخدم لتحديد ما إذا كان سير العمل المحدد نشطًا.
   PackageLog	مؤشر الفئة	مؤشر إلى واجهة التسجيل التي تمت تهيئتها للحزمة. تستخدم هذه الواجهة بواسطة حزمة لتسجيل الرسائل والاستثناءات لملف سجل الحزمة.
   RootControlDispatcher	الخاصية	واجهة مرسل يتم استخدامها للسماح لعنصر التحكم بعرض واجهة المستخدم الخاصة به أثناء نشر الحزمة. استخدم هذه الواجهة لتمكين التفاف عناصر أو أوامر واجهة المستخدم. من المهم التحقق من هذا المتغير بحثًا عن القيم الخالية قبل استخدامه لأنه قد لا يتم تعيينه على قيمة.
   CrmSvc	الخاصية	مؤشر إلى الفئة CrmServiceClient التي تتيح للحزمة أن تتعامل مع Dynamics 365 من داخل الحزمة. استخدم هذا المؤشر لتنفيذ أساليب SDK والإجراءات الأخرى في الأساليب التي تم تجاوزها.
   DataImportBypass	الخاصية	حدد ما إذا كان Dynamics 365 Package Deployer يتخطى كافة عمليات استيراد البيانات مثل استيراد عينة بيانات Dataverse وبيانات الملفات الثابتة والبيانات التي تم تصديرها من أداة ترحيل التكوين. حدد القيمة صواب أو خطأ. القيمة الافتراضية هي false.
   OverrideDataImportSafetyChecks	الخاصية	تحديد ما إذا كان Dynamics 365 Package Deployer يتجاوز بعض فحوصات السلامة الخاصة به، مما يساعد في تحسين أداء الاستيراد. حدد true أو false. القيمة الافتراضية هي false. يجب عليك تعيين هذه الخاصية إلى true فقط إذا لم يتضمن مثيل Dataverse الهدف أي بيانات.

4. احفظ مشروعك. الخطوة التالية هي إنشاء الحزمة.

إنشاء ونشر

تصف الأقسام التالية كيفية إنشاء الحزمة ونشرها.

البناء

يتم وصف إنشاء الحزمة الخاصة بك أدناه اعتمادًا على الأداة التي تستخدمها.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

تتكون الحزمة الخاصة بك من الملفات التالية الموجودة ضمن <Project>\Bin\Debug folder.

• <مجلد> PackageName: اسم المجلد هو نفسه الذي قمت بتغييره لاسم مجلد الحزمة في خطوة 2.g من هذا القسم إضافة تعليمات برمجية مخصصة. يحتوي هذا المجلد على جميع الحلول، وبيانات التكوين، والملفات الثابتة، والمحتويات لحزمتك.

• <PackageName.DLL>: يحتوي التجميع على التعليمات البرمجية المخصصة للحزمة الخاصة بك. يكون اسم التجميع بشكل افتراضي هو نفس اسم المشروع الخاص بك.

نشر

بعد إنشاء حزمة، يمكنك نشرها على مثيل Dataverse باستخدام أداة Package Deployer أو Windows PowerShell أو أمر CLI.

• للنشر باستخدام أداة Package Deployer، قم أولاً بتنزيل الأداة كما هو موضح أدوات تطوير Dataverse. بعد ذلك، اتبع المعلومات التفصيلية حول نشر الحزم في المقالة نشر الحزم باستخدام Package Deployer أو Windows PowerShell.

• للنشر باستخدام CLI، استخدم أمر pac package deploy.

  > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
  

  ‏‫ملاحظة‬

  لنشر حزمة في بيئة هدف باستخدام CLI، يجب عليك أولاً إعداد ملف تعريف مصادقة وتحديد مؤسسة. مزيد من المعلومات: pac auth create، pac org select

أفضل الممارسات

فيما يلي بعض النصائح حول أفضل الممارسات التي يجب اتباعها عند التعامل مع حزم Package Deployer.

إنشاء الحزم

عند إنشاء الحزم، يجب على المطورين:

• تأكد من توقيع تجميعات الحزمة.

نشر الحزم

عند نشر الحزم، يلزم على مسؤولي Dataverse:

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

راجع أيضًا

أداة حزمة الحلول