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

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

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

ملحوظة

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

المتطلبات المسبقه

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

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

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

• إنشاء مشروع Visual Studio أو MSBuild
• إضافة الحلول والملفات الأخرى إلى المشروع
• تحديث ملفات HTML الموفرة (اختياري)
• تحديد قيم التكوين الخاصة بالحزمة
• تحديد الرمز المخصص للحزمة
• إنشاء الحزمة ونشرها

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

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

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

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

Power Platform CLI

قم بتشغيل الأمر pac package init لإنشاء الحزمة الأولية. لمزيد من المعلومات: راجع ‎pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

تحتوي مخرجات CLI الناتجة على المجلدات والملفات الموضحة أدناه. تم استخدام اسم المجلد "DeploymentPackage" هنا كمثال.

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

في المشروع الذي تم إنشاؤه، ابحث عن ملف التكوين ImportConfig.xml في المجلد PkgAssets والملف PackageImportExtension.cs. ستقوم بتعديل هذه الملفات كما هو موضح لاحقًا في هذه المقالة.

أدوات Power Platform

يمكنك إنشاء مشروع Visual Studio باستخدام قالب حل Power Platform وإضافة مشروع حزمة لاحقا باستخدام قالب مشروع نشر حزمة Power Platform، أو إنشاء مشروع مباشرة باستخدام قالب مشروع نشر حزمة Power Platform.

ملحوظة

لا تختر قالب حزمة Power Platform. هذا القالب مخصص لحزم المكونات الإضافية.

يحتوي الحل Visual Studio الناتج والمشروع على المجلدات والملفات الموضحة أدناه. تم استخدام الاسم "Deployment-package" هنا كمثال. لا يتم عرض محتويات مجلد المحتوى هنا للإيجاز.

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

في المشروع الذي تم إنشاؤه، ابحث عن ملف التكوين ImportConfig.xml في المجلد PkgFolder وملف PackageTemplate.cs. ستقوم بتعديل هذه الملفات كما هو موضح لاحقًا في هذه المقالة.

مزيد من المعلومات حول استخدام امتداد Power Platform Tools: البدء السريع: إنشاء مشروع Power Platform Tools

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

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

Power Platform CLI

عند استخدام CLI، يمكنك إضافة حزم وحلول ومراجع خارجية إلى مشروع الحزمة الخاص بك باستخدام أحد الأوامر الفرعية إضافة. أدخل pac package helpللاطلاع على قائمة الأوامر الفرعية. دعنا نضيف حلاً لحزمتنا.

> 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.

أدوات Power Platform

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

بعد ذلك، قم بتحديث الملفات الخاصة بلغة HTML.

1. في جزء مستكشف الحلول، قم بتوسيع PkgFolder>Content>en-us. ابحث عن مجلدين يسمى EndHTML و WelcomeHTML. تحتوي هذه المجلدات على ملفات HTML والملفات المقترنة التي تتيح لك عرض المعلومات (للمستخدم) في نهاية عملية نشر الحزمة وبدايتها. قم بتحرير الملفات في مجلد HTML لهذه المجلدات لإضافة معلومات لعرضها لحزمتك.

2. يمكنك أيضًا إضافة ملفات HTML إلى حزمتك بلغات أخرى بحيث يظهر المحتوى في HTML باللغة المستندة إلى الإعدادات المحلية لجهاز الكمبيوتر الخاص بالمستخدم. وللقيام بذلك:

   1. أنشئ نسخة من المجلد en-us تحت PkgFolder>المحتوى.
   2. أعد تسمية المجلد المنسوخ باللغة المناسبة. على سبيل المثال، فيما يتعلق باللغة الإسبانية، غيّر اسم المجلد إلى es-ES.
   3. قم بتعديل محتوى ملفات HTML لإضافة محتوى باللغة الإسبانية.

تكوين الحزمة

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

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

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

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

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

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

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

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

      public override void InitializeCustomExtension()  
      {
        // 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 لاستيراد الحزمة. مزيد من المعلومات: نشر الحزم باستخدام Windows PowerShell وPackage Deployer

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

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

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

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

   4. تجاوز الأسلوب OverrideSolutionImportDecision لإرجاع قائمة تعداد UserRequestedImportAction التي تتحكم في ما إذا كان سيتم تخطي استيراد حل أو تحديثه أو ترقيته (الافتراضي).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
        string solutionUniqueName, Version organizationVersion,
        Version packageSolutionVersion, Version inboundSolutionVersion,
        Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
      {
        return systemSelectedImportAction == 
            ImportAction.Import ? UserRequestedImportAction.ForceUpdate
            : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
            packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
            systemSelectedImportAction);
      }
      

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

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

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

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

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

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

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

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

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

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

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

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

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

   11. قم بتغيير اسم الحزمة الطويل عن طريق تحرير القيمة المرتجعة تحت الخاصية 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)	الوظيفة	تُستخدم لإفشال عملية استيراد الحالة الحالية مع رسالة استثناء.
   IsRoleAssociatedWithTeam(Guid, Guid)	الوظيفة	تُستخدم لتحديد ما إذا كان الدور مرتبطًا بفريق محدد.
   IsWorkflowActive(Guid)	الوظيفة	تُستخدم لتحديد ما إذا كان سير العمل المحدد نشطًا.
   PackageLog	مؤشر الفئة	مؤشر إلى واجهة التسجيل التي تمت تهيئتها للحزمة. تستخدم هذه الواجهة بواسطة حزمة لتسجيل الرسائل والاستثناءات لملف سجل الحزمة.
   RootControlDispatcher	الخاصية	واجهة مرسل يتم استخدامها للسماح لعنصر التحكم بعرض واجهة المستخدم الخاصة به أثناء نشر الحزمة. استخدم هذه الواجهة لتمكين التفاف عناصر أو أوامر واجهة المستخدم. من المهم التحقق من هذا المتغير بحثًا عن القيم الخالية قبل استخدامه لأنه قد لا يتم تعيينه على قيمة.
   CrmSvc	الخاصية	مؤشر إلى فئة CrmServiceClient يسمح لحزمة بمعالجة Dynamics 365 من داخل الحزمة. استخدم هذا المؤشر لتنفيذ أساليب SDK والإجراءات الأخرى في الأساليب التي تم تجاوزها.
   DataImportBypass	الخاصية	حدد ما إذا كان Dynamics 365 Package Deployer يتخطى جميع عمليات استيراد البيانات مثل استيراد بيانات عينة Dataverse وبيانات الملف الثابت والبيانات المصدرة من أداة Configuration Migration. حدد القيمة صواب أو خطأ. القيمة الافتراضية هي false.
   OverrideDataImportSafetyChecks	الخاصية	حدد ما إذا كان Dynamics 365 Package Deployer يتجاوز بعض عمليات التحقق من السلامة الخاصة به، مما يساعد في تحسين أداء الاستيراد. حدد true أو false. القيمة الافتراضية هي false. يجب عليك تعيين هذه الخاصية إلى true فقط إذا لم يتضمن مثيل Dataverse الهدف أي بيانات.

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

إنشاء ونشر

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

إنشاء

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

Power Platform CLI

لإنشاء حزمة تم إنشاؤها باستخدام CLI، يمكنك تحميل ملف .csproj في Visual Studio، ولكن بدلا من ذلك سنستخدم الأمر dotnet وMSBuild. يفترض المثال أدناه أن دليل العمل يحتوي على ملف csproj.*.

> 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

أدوات Power Platform

لإنشاء الحزمة، اضغط على F5 في Visual Studio أو حدد Build>Build solution.

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

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

ملحوظة

قد ترى مجلد .NET (على سبيل المثال، net472) يحتوي على مجلد pdpublish. توجد ملفات DLL الخاصة بك وملفات المشاريع الأخرى في مجلد pdpublish هذا.

• <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:

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

راجع أيضًا

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