سيَاق تنفيذ المكون الإضَافي

مكتمل

فِي كل مرة يتم فيهَا تَشغيل مكون إضَافِي (أو ملحق سير عمل مخصص)، يوفر Microsoft Dataverse ثروة من البيَانَات حول سيَاق العَمَلية الحَالية. تتمتع كلّ مِن المكونَات الإضَافية وتجميعَات سير العمل المخصصة بإمكَانية الوصول إلى الفئة IWorkflowContext، والتي يمكن الوصول إليهَا مِن خلال أسَاليب مختلفة.

فِي المكونَات الإضَافية، يمكن الوصول إلى IPluginExecutionContext مِن خلال المعلمة IServiceProvider للأسلوب Execute عن طريق استدعَاء الأسلوب GetService.

public class SamplePlugin : IPlugin

{

public void Execute(IServiceProvider serviceProvider)

{

// Obtain the execution context from the service provider.

IPluginExecutionContext context = (IPluginExecutionContext)

serviceProvider.GetService(typeof(IPluginExecutionContext));

}

}

فِي ملحقَات سير العمل المخصصة، يتم تمرير IPluginExecutionContext كمعلمة للأسلوب Execute مِن النوع CodeActivityContext.

public class SampleWorkflowExtension : CodeActivity

{

protected override void Execute(CodeActivityContext context)

{

// Obtain the execution context from the code activity context.

IWorkflowContext workflowContext = context.GetExtension();

}

}

يقوم كل مِن IPluginExecutionContext وIWorkflowContext بتنفيذ الواجهة IExecutionContext. يعرض كل منهَا أيضًا معلومَات خَاصة بنوعهَا. لمزيد مِن المعلومَات، رَاجع فهم سيَاق التنفيذ.

خصَائص IExecutionContext

اثنَان مِن أكثر الخصَائص المتميزة لواجهة IExecutionContextهمَا InputParameters وOutputParameters. الخصَائص الأخرى المستخدمة بشكل متكرر هي PreEntityImagesوPostEntityImagesوSharedVariables.

InputParameters

يتم تضمين InputParameters فِي مجموعة InputParameters الخَاصة بسيَاق التنفيذ وهي مِن النوع Entity. تتيح لك هذه الخَاصية معرفة قيَم الكيَانَات التي تم تقديمهَا إلى المكون الإضَافِي قبل تنفيذ عملية معينة.

على سبيل المثَال، إذا كنت تريد التحقق مِن صحة بيَانَاتك ومنع حفظهَا إذا لم ينجح التحقق مِن الصحة، فستكون الخطوات التي تتخذهَا مشَابهة لمَا يلي:

1. قم بتسجيل المكون الإضَافِي الخَاص بك ليتم تَشغيله فِي مرحلة التحقق المسبق فِي إنشَاء و/أو تحديث الكيَان الذي تريد التحقق مِن صحته.

2. تحقق مِن صحة البيَانَات فِي المكون الإضَافِي الخَاص بك عن طريق قرَاءة القيَم مِن مجموعة InputParameters. عند إنشَاء، سترغب فِي استردَاد المجموعة "الهدف".

3. قم برمي InvalidPluginExecutionException إذا كَانت البيَانَات المقدمة غير صَالحة.

أو ربمَا تريد تحديث القيم فِي الكيَان الخَاص بك (مثل إزَالة الأحرف الخَاصة مِن رقم الهَاتف) قبل حفظ البيَانَات. يمكنك التعَامل مع هذا الموقف مِن خلال الخطوات التَالية:

1. قم بتسجيل المكون الإضَافِي الخَاص بك ليتم تَشغيله فِي مرحلة مَا قبل التَشغيل عند إنشَاء و/أو تحديث الكيَان الذي تريد تحديثه.

2. قم بتحديث البيَانَات فِي المكون الإضَافِي الخَاص بك عن طريق تحرير القيَم مِن مجموعة InputParameters. عند إنشَاء، سترغب فِي استردَاد المجموعة "الهدف".  

OutputParameters

يتم تضمين معلمَات الإخرَاج فِي مجموعة OutputParameters فِي سيَاق التنفيذ وهي مِن النوع الكيَان. يتم توفير معلمَات الإخرَاج فقط بعد حدوث العَمَلية المحددة. على هذا النحو، لن تتمكن مِن استخدَام هذه المجموعة إلا عند التعَامل مع الأحدَاث فِي مرحلة PostOperation. 

على سبيل المثَال، إذا كنت تريد تغيير القيم التي تم إرجَاعهَا بواسطة العَمَلية، فيمكنك تعديلهَا عن طريق تنفيذ الخطوات التَالية:

1. قم بتسجيل المكون الإضَافِي الخَاص بك للتَشغيل فِي المرحلة PostOperation عند إنشَاء الكيَان الذي تريد تحديثه و/ أو تحديثه.

2. قم بتحديث البيَانَات الموجودة فِي المكون الإضَافِي الخَاص بك عن طريق تحرير القيم مِن مجموعة OutputParameters. عند إنشَاء، سترغب فِي استردَاد المجموعة "الهدف". 

PreEntityImages وPostEntityImages

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

بينمَا يمكنك استردَاد قيم الكيَانَات باستخدَام سيَاق المؤسسة مِن دَاخل مكون إضَافِي مع طلب استردَاد، فإن استخدَام صور الكيَانَات لإجرَاء هذه المهمة يعد أكثر كفاءة وينصح به بشدة. 

SharedVariables

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

قد يكون الاستثنَاء الوحيد هو عندمَا تريد التأكد مِن عدم وجود أي مكونَات إضَافية "هَاربة" فِي بيئتك. أي أنهم يتم تنشيطهم بموجب سينَاريو العودية اللانهَائية. يمكنك أيضًا استخدَام سيَاق التنفيذ لتحديد مدى عمق تَشغيل المكون الإضَافِي الخَاص بك حَاليًا، ولكن فِي ظل مواقف معينة، قد يكون مِن المنَاسب التتبع يدويًا. عَلى سبيل المثَال، ربمَا يقوم المكون الإضَافِي الخَاص بك عن طريق الخطأ ببدء تَشغيل منطق التحديث دَاخل مكون إضَافِي تم تكوينه للتَشغيل عَلى تحديث الكيَان، ممَا يؤدي بدوره إلى تَشغيله بلا حدود. يمكنك إنشَاء نمط لحسَاب عدد المرَات التي يمكن فيهَا تَشغيل هذا المكون الإضَافي، وذلك لاستكشَاف هذه المشكلة وإصلاحهَا. قد يكون مِن أمثلة ذلك تكوين حد يبلغ خمسة عمليَات تَشغيل للمكوّن الإضَافِي مِن خلال الخطوات التَالية:

1. تحقق مِن وجود متغير RunCount المشترك فِي المكون الإضَافي، وإلا، فقم بإنشَاء متغير تمت تهيئته إلى الصفر.

2. تحقق ممَا إذا كَانت قيمة المتغير RunCount أكبر مِن خمسة، وإذا كَانت كذلك، فقم بإظهَار InvalidPluginExecutionException.

3. فِي نهَاية المكون الإضَافي، قم بزيَادة المتغير RunCount بمقدَار 1. 

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

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