تَمرِين - اكتب أول مكون إضَافِي استخدمته

مكتمل

تحتَاج المؤسسة فِي هذا السينَاريو إلى التأكد مِن إدخَال بيَانَات رقم الهَاتف بتنسيقٍ متسق. وتحقيقَاً لذلك الهدف، تقوم بإنشَاء مكون إضَافِي لتَشغيل الإنشَاء/التحديث الذي يعمل عَلى إزَالة جميع الأحرف غير الرقمية مِن رقم الهَاتف قبل الحفظ إلى Dataverse. ومن ثم تقوم بإنشَاء مكون إضَافِي آخر والذي سيتم تَشغيله عَلى الشرط retrieve/retrievemultiple فِي "جهة الاتصَال" لإعَادة تنسيق رقم الهَاتف ليتضمن الأقواس والشرطَات، وذلك فِي حَالة وجود البيَانَات. 

التَمرِين الأول: إنشَاء/تحديث المكون الإضَافي

ستنشئ فِي ذلك التَمرِين مكونًا إضَافيًا والذي يتم تَشغيله عند الإنشَاء والتحديث. ويعمل هذا المكون الإضَافِي عَلى إزَالة الأحرف غير الرقمية مِن رقم الهَاتف.

يتألف كل تَمرِين مِن سينَاريو وأهدَاف تعليمية. يصف السينَاريو الغرض مِن التمَارين، بينمَا يتم سرد الأهدَاف وتحتوي عَلى نقَاط.

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫ملاحظة

وفِي حَال عدم توفر أدوات Dynamics 365 SDK، رَاجع تنزيل الأدوات مِن NuGet لتنزيلهَا.

المهمة الأولى: إنشَاء مكون إضَافي

1. قم بتَشغيل Visual Studio 2022.

2. حدد ملف > جديد > مشروع.

3. حدد مكتبة الفئَات (NET Framework.) وحدد التَالي.

   

4. أدخل عبارة D365PackageProject لـ اسم المشروع، وحدد موقعًا لحفظ المشروع، وحدد .NET Framework 4.6.2 لـ إطَار العمل، ثم حدد إنشَاء.

   

5. انقر بزر المَاوس الأيمن عَلى المشروع وحدد إدَارة حزم NuGet.

   

6. حدد علامة التبويب تصفح، وابحث عن microsoft.crmsdk.coreassemblies وحددهَا، ثم حدد تثبيت.

   

7. اقرأ شروط الترخيص ثم حدد قبول عند موافقتك.

8. أغلق مدير حزم NuGet.

9. انقر بزر المَاوس الأيمن فوق Class1.cs وحذف.

10. انقر بزر المَاوس الأيمن فوق المشروع، ثم حدد إضَافة > فئة.

11. قم بتسمية الفئة الجديدة PreOperationFormatPhoneCreateUpdate وحدد إضَافة.

    

12. أضف عبارَات الاستخدَام إلى الفئة الجديدة كمَا يلي:

     using Microsoft.Xrm.Sdk;
    
     using System.Text.RegularExpressions;
    

13. جعل الفئة عَامة وتنفيذ الواجهة IPlugin.

    

14. ابدأ تنفيذ عضو الواجهة.

    

    من المفترض أن تبدو فئتك الآن مثل الصورة التَالية.

    

المهمة الثَانية: تنسيق رقم الهَاتف

1. احصل عَلى سيَاق التنفيذ مِن موفر الخدمة. استبدل الاستثنَاء الموجود فِي الأسلوب Execute بجُزء التعليمة البرمجية المتكررة التَالي.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. تحقق مِن صحة معلمة إدخَال الهدف. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الأسلوب Execute.

    if (!context.InputParameters.ContainsKey("Target"))
   
    throw new InvalidPluginExecutionException("No target found");
   

3. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الأسلوب Execute. يحصل جُزء التعليمة البرمجية المتكررة ذلك عَلى الكيَان الهدف مِن معلمة الإدخَال، وبعد ذلك يتم التحقق ممَا إذا كَانت سمَاته تحتوي عَلى telephone1 (هَاتف العمل الخَاص بجهَات الاتصَال والهَاتف الخَاص بالحسَابات) مِن عدمه.

    var entity = context.InputParameters["Target"] as Entity;
   
    if (!entity.Attributes.Contains("telephone1"))
   
    return;
   

4. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الدَالة Execute. يزيل جُزء التعليمة البرمجية المتكررة هذا جميع الأحرف غير الرقمية مِن رقم الهَاتف الذي قدمه المستخدم.

    string phoneNumber = (string)entity["telephone1"];
   
    var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
   

5. قم بتعيين telephone1 إلى رقم هَاتف منسق. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الأسلوب Execute.

    entity["telephone1"] = formattedNumber;
   

   سيبدو الأسلوب Execute الآن مثل الصورة التَالية.

   

6. انقر بزر المَاوس الأيمن عَلى المشروع وحدد خصَائص.

   

7. حدد عَلامَة التَبويب التَوقِيع، وحَدد المُربَّع المُسمَّى تَوقِيع التَجمِيع وحدد مِلف مفتَاحٍ جديدٍ.

   

8. أدخل contoso.snk فِي حقل اسم ملف المفتَاح، وامسح خَانة الاختيَار حمَاية ملف مفتَاحي بكلمة مرور، ثم حدد موافق.

   

9. أغلق علامة التبويب الخصَائص.

10. قم ببنَاء المشروع وتأكَّد مِن نجَاح البنَاء.

المهمة الثَالثة: تسجيل مكون إضَافِي والخطوات

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫ملاحظة

وفِي حَال عدم توفر أدوات Dynamics 365 SDK، رَاجع تنزيل الأدوات مِن NuGet لتنزيلهَا.

1. ابدأ تَشغيل تطبيق plug-in registration tool.

2. حدد إنشَاء اتصَال جديد.

   

3. حدد Office 365، وحدد خَانة الاختيَار ‬‏‫إظهَار الخيَارَات المتقدمة، وابدأ توفير بيَانَات اعتمَادك، ثم حدد تسجيل الدخول.

   

4. حدد تسجيل ثم حدد تسجيل تجميع جديد.

   

5. حدد استعرَاض.

   

6. تصفح وصولاً إلى المجلد Bin > Debug فِي مكتبة الفئَات التي أنشأتهَا، وحدد D365PackageProject.dll، ثم حدد فتح.

   

7. حدد تسجيل المكونَات الإضَافية المُحددة.

   

8. حدد موافق.

9. ابدأ توسيع التجميع المسجل حديثًا.

   

10. انقر بزر المَاوس الأيمن فوق المكون الإضَافِي وحدد تسجيل خطوة جديدة.

    

11. حدد إنشَاء لـ الرسَالة وحدد جهة اتصَال لـ الكيَان الأسَاسي.

    

12. حدد PreOperation لـ مرحلة تنفيذ ‏‫البنية الأسَاسية لبرنَامج ربط العَمليَات التجَارية للحدث‬ ثم حدد تسجيل خطوة جديدة.

    

13. حدد إغلاق.

14. انقر بزر المَاوس الأيمن فوق المكون الإضَافِي وحدد تسجيل خطوة جديدة مرة أخرى.

    

15. حدد تحديث لـ الرسَالة، وحدد جهة الاتصَال لـ الكيَان الأسَاسي، ثم حدد البحث فِي السمَات.

    

16. ابدأ إلغَاء تحديد خَانة الاختيَار تحديد الكل، وحدد خَانة الاختيَار هَاتف العمل، ثم حدد موافق.

    

17. حدد PreOperation لـ مرحلة تنفيذ ‏‫البنية الأسَاسية لبرنَامج ربط العَمليَات التجَارية للحدث‬ ثم حدد تسجيل خطوة جديدة.

المهمة الخَامسة: اختبار المكون الإضَافي

1. انتقل إلى Maker Portal لديك وتأكَّد مِن تحديد البيئة الصحيحة.

2. حدد التطبيقَات وقم بتَشغيل تطبيق جمع التبرعَات.

   

3. حدد لوحة المعلومَات وافتح إحدى جهَات الاتصَال.

   

4. حدد + جديد.

   

5. أدخل اختبار لـ الاسم الأول وجهة اتصَال لـ اسم العَائلة و(123)-555-0100 لـ هَاتف العمل، ثم حدد حفظ.

   

   يجب حفظ السجل، ويجب أن يظهر هَاتف العمل القيم الرقمية فقط.

   

6. ابدأ تغيير هَاتف العمل إلى 001-123-555-0100 وانتظر بضع ثوانٍ.

   يجب تحديث السجل، ويجب أن يظهر هَاتف العمل القيم الرقمية فقط.

   

التَمرِين الثَاني: إنشَاء/استردَاد retrieve multiple

ستنشئ فِي ذلك التَمرِين مكونًا إضَافيًا والذي يتم تَشغيله عند retrieve وretrieve multiple. يضيف هذا المكون الإضَافِي الأقواس والشُرط إلى أرقَام الهواتف.

يتألف كل تَمرِين مِن سينَاريو وأهدَاف تعليمية. يصف السينَاريو الغرض مِن التمَارين، بينمَا يتم سرد الأهدَاف وتحتوي عَلى نقَاط.

المهمة الأولى: إنشَاء مكون إضَافي

1. ابدأ تَشغيل Visual Studio.

2. افتح المشروع الذي أنشأته فِي التَمرِين الأول.

3. انقر بزر المَاوس الأيمن فوق مشروع وحدد إضَافة > فئة.

   

4. فِي الحقل الاسم، أدخل PostOperationFormatPhoneOnRetrieveMultiple للفئة ثم حدد إضَافة.

5. أضف عبارَات الاستخدَام إلى الفئة الجديدة كمَا يلي:

    using Microsoft.Xrm.Sdk;
   

6. جعل الفئة عَامة وتنفيذ الواجهة IPlugin.

7. ابدأ تنفيذ عضو الواجهة. من المفترض أن تبدو فئتك الآن مثل الصورة التَالية.

   

المهمة الثَانية: تنسيق رقم الهَاتف للاستردَاد

1. احصل عَلى سيَاق التنفيذ مِن موفر الخدمة. استبدل الاستثنَاء الموجود فِي الأسلوب Execute بجُزء التعليمة البرمجية المتكررة التَالي.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. تحقق ممَا إذا كَان اسم الرسَالة Retrieve أو RetrieveMultiple. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الأسلوب Execute.

    if (context.MessageName.Equals("Retrieve"))	
    {
   
    }	
    else if(context.MessageName.Equals("RetrieveMultiple"))	
    {
   
    }
   

3. تحقق ممَا إذا كَانت معلمَات الإخرَاج تحتوي عَلى كيَان أعمَال وأنه نوع كيَان مِن عدمه. ألصق جُزء التعليمة البرمجية المتكررة التَالي دَاخل if الشرط retrieve.

    if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
    throw new InvalidPluginExecutionException("No business entity found");
   

4. احصل عَلى الكيَان وتحقق ممَا إذا كَان يحتوي عَلى الحقل telephone1 مِن عدمه. أضف جُزء التعليمة البرمجية المتكررة التَالي دَاخل الشرط if ‏retrieve.

    var entity = (Entity)context.OutputParameters["BusinessEntity"];
   
    if (!entity.Attributes.Contains("telephone1"))	
        return;
   

5. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى الشرط if retrieve. يحَاول جُزء التعليمة البرمجية المتكررة هذا تحليل telephone1 بشكلٍ طويل وسيتم إرجَاعه إذا لم تنجح عملية التحليل.

    if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
   
    return;
   

6. ابدأ تنسيق رقم الهَاتف بإضَافة الأقواس والشرطَات. أضف جُزء التعليمة البرمجية المتكررة التَالي دَاخل الشرط if retrieve.

    var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
    entity["telephone1"] = formattedNumber;
   

يبدو جُزء استردَاد الأسلوب Execute الآن مثل الصورة التَالية.

المهمة الثَالثة: تنسيق رقم الهَاتف لـ retrieve multiple

1. أضف جُزء التعليمة البرمجية المتكررة التَالي إلى دَاخل الشرط retrieve multiple. سيتحقق جُزء التعليمة البرمجية المتكررة هذا ممَا إذا كَانت معلمَات الإخرَاج تحتوي عَلى BusinessEntityCollection وإذا كَانت مِن نوع EntityCollection.

    if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
        throw new InvalidPluginExecutionException("No business entity collection found");
   

2. احصل عَلى مجموعة الكيَانَات مِن معلمَات الإخرَاج. أضف جُزء التعليمة البرمجية المتكررة التَالي دَاخل الشرط retrieve multiple.

    var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];
   

3. ابدأ التكرَار مِن خلال كل كيَان فِي مجموعة الكيَانَات.

    foreach (var entity in entityCollection.Entities)	
    {
   
    }
   

4. أضف جُزء التعليمة البرمجية المتكررة التَالي دَاخل الشرط foreach. سيفعل جُزء التعليمة البرمجية المتكررة ذلك نفس الشيء الذي يفعله الشرط retrieve.

    if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
    {
       if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
       {
           var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
           entity["telephone1"] = formattedNumber;
       }
    }
   

   سيبدو جُزء الشرط retrieve multiple للأسلوب Execute الآن مثل الصورة التَالية.

   

5. أعد إنشَاء المشروع وتأكَّد مِن نجَاح الإنشَاء.

المهمة الرَابعة: تحديث تجميع مكون إضَافِي وخطوات التسجيل

1. أبدَا تَشغيل ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫أدَاة تسجيل المكونَات الإضَافِي وحدد إنشَاء اتصَال جديد.

   

2. حدد Office 365، وحدد ‬‏‫إظهَار الخيَارَات المتقدمة، وابدأ توفير بيَانَات اعتمَادك، ثم حدد تسجيل الدخول.

3. حدد التجميع الذي سجلته فِي التَمرِين الأول ثم حدد تحديث.

   

4. حدد استعرَاض.

5. استعرض للوصول إلى مجلد debug لمشروعك، وحدد D365PackageProject.dll ثم حدد فتح.

   

6. حدد المكونَات الإضَافية ثم حدد تحديث المكونَات الإضَافية المُحددة.

   

7. حدد موافق.

8. انقر بزر المَاوس الأيمن فوق المكون الإضَافِي الجديد وحدد تسجيل خطوة جديدة.

9. حدد Retrieve لـ الرسَالة وحدد جهة الاتصَال لـ الكيَان الأسَاسي، ثم حدد PostOperation لـ مرحلة تنفيذ ‏‫البنية الأسَاسية لبرنَامج ربط العَمليَات التجَارية للحدث. تأكد مِن تحديد متزَامن‬ لـ وَضع التنفيذ ثم حدد تسجيل خطوة جديدة.

   

10. انقر بزر المَاوس الأيمن فوق المكون الإضَافِي وحدد تسجيل خطوة جديدة مرة أخرى.

11. حدد RetrieveMultiple لـ الرسَالة وحدد جهة الاتصَال لـ الكيَان الأسَاسي، ثم حدد PostOperation لـ مرحلة تنفيذ ‏‫البنية الأسَاسية لبرنَامج ربط العَمليَات التجَارية للحدث. تأكد مِن تحديد متزَامن‬ لـ وَضع التنفيذ، ثم حدد تسجيل خطوة جديدة.

المهمة الخَامسة: اختبار المكون الإضَافي

1. انتقل إلى Maker Portal وتأكَّد مِن وجودك فِي البيئة الصحيحة.

2. حدد تطبيقَات. ثم حدد تطبيق جمع التبرعَات وبعدهَا حدد تحرير. ستقوم بإضَافة الجدول "جهَات الاتصَال" إلى التطبيق.

   

3. حدد + صفحة جديدة.

4. حدد جدول Dataverse ثم حدد التَالي.

5. حدد الجدول الموجود. ثم حدد الجدول جهَات الاتصَال، ثم حدد إضَافة.

   

6. حدد تَشغيل.

   

7. حدد حفظ ومتَابعة.

8. حدد تَشغيل مرة أخرى.

9. حدد جهَات الاتصَال.

10. لن تتغير السجلات الموجودة التي لم يتم حفظهَا بالتنسيق الجديد. حدد + جديد.

    

11. اعمل عَلى توفير المعلومَات التَالية ثم حدد حفظ. يجب حفظ السجل، كمَا يجب تطبيق التنسيق الجديد عَلى المكون الإضَافي.

12. حدد جهَات الاتصَال مرة أخرى. يجب أن يظهر السجل الذي أنشأته بالتنسيق الجديد.

    

13. حدد إحدى جهَات الاتصَال الموجودة وافتحهَا.

    

14. ابدأ تحرير هَاتف العمل عَلى النحو التَالي:

    

15. حدد حفظ. يجب تطبيق التنسيق الجديد. حدد جهَات الاتصَال مرة أخرى.

    

سيحصل الهَاتف الذي جرى تحريره عَلى التنسيق الجديد.