إنشَاء فئة البرنَامج النصي

مكتمل

فِي هذه الوحدة، سوف تستكشف طَريقَة بنَاء فئة البرنَامج النصي C# لتنفيذ منطق التحويل الخَاص بك.

يجب أن يفِي الكود المخصص ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستخدم مَعَ موصل بالمُتَطلبَات التَالية:

• يجب أن يكون اسم الفئة Script.

• يجب أن تنفذ فئة البرنَامج النصي ScriptBase.

• يجب أن تقوم فئة البرنَامج النصي بتنفيذ طَريقَة تُسمى ExecuteAsync.

• يجب أن يستغرق تَشغِيل الرمز المخصص أقل مِن خمس ثوانٍ.

• يجب أن يكون إجمَالي الرمز المخصص أقل مِن 1 ميغَابايت.

• يتم دعم ملف أو فئة برنَامج نصي واحد فقط.

استكشَاف ScriptBase

ScriptBase عبارة عن فئة توفرهَا البنية الأسَاسية للموصل المخصص مَعَ واجهَات وأسَاليب مسَاعدة دَاعمة. تحتَاج فئة Script الخَاصة بك إلى استخدَام هذه الفئة المجردة كفئة أسَاسية لهَا.

public class Script : ScriptBase
{
    public override Task<HttpResponseMessage> ExecuteAsync()
    {
        // Your code here
    }
}

بالإضَافَة إلى أسلوب ExecuteAsync، تتضمن هذه الفئة أيضًا أسلوب المسَاعد CreateJsonContent الذي تستخدمه لإنشَاء كَائن StringContent مِن JSON المتسلسل. عَلى سبيل المثَال، فِي التعليمة البرمجية التَالية، يقوم أسلوب المسَاعد CreateJsonContent بتعبئة response.Content مِن الاستجَابة المحولة التي تم إنشَاؤهَا.

// Wrap the original JSON object into a new JSON object with just one key ('wrapped')
var newResult = new JObject
{
    ["wrapped"] = result,
};
      
    response.Content = CreateJsonContent(newResult.ToString());

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

كمَا تحتوي فئة ScriptBase عَلى الخَاصية العَامة Context، الذي يتوفر لمنطقك لتوفير سيَاق للطلب الذي تتم معَالجته. إن خَاصية Context مِن نوع IScriptContext وتحتوي عَلى الخصَائص والأسَاليب المفيدة التَالية:

• OperationId - تكون هذه الخَاصية مفيدة للغَاية عندمَا تحتَاج إلى تحديد العَمَليَّة التي تتم معَالجتهَا حتى يتمكن منطقك مِن توفير التحويلات الصَحِيحة.

• Request - هذا الأسلوب عبارة عن HttpRequestMessage للعَمَليَّة التي تتم معَالجتهَا. إذا كنت بحَاجة إلى تحويل الأمر، يمكنك تَعدِيل هذه الطَريقَة، ثم تمريرهَا إلى SendAsync لإرسَال الأمر إلى الخِدمَة.

• Logger - يوفر لك هذا الأسلوب مثيلاً لـ ILogger الذي يمكنك استخدَامه لتَسجِيل معلومَات التشخيص مِن التعليمَات البرمجية الخَاصة بك إلى "سجلات الشفرة" لتَشغِيل الموصل.

• SendAsync - استخدم هذه الخَاصية لإرسَال طلب HTTP إلى الخِدمَة. يجب عليك استخدَام هذه الطَريقَة بدلاً مِن إجرَاء مكَالمة HttpClient.SendAsync الخَاصة بك.

تجميع التعليمَات البرمجية الخَاصة بك محليًا

يمكن أن يسَاعد تجميع التعليمَات البرمجية محليًا فِي تسهيل التعرف عَلى مشكلات التجميع. لتأليف التعليمَات البرمجية محليًا، ستحتَاج إلى إنشَاء مَشرُوع عَلى جهَاز الكمبيوتر المحلي الخَاص بك، ثم إنشَاء ملفات لفئة ScriptBase وواجهة IScriptContext. ستقوم بنسخ التعليمَات البرمجية الخَاصة بهذه الملفات مِن وثَائق تعريف الفئَات والواجهَات الدَاعمة.

كمَا قد يكون المَشرُوع مفتوح المَصدَر Microsoft/MTC_CustomConnectorCodeProject عَلى GitHub مفيدًا للتطوير المحلي. يوفر هذا المَشرُوع إعدَادًا مسبقًا لمَشرُوع وحدة التحكم لتطوير التعليمَات البرمجية المخصصة.

مسَاحَات الأسمَاء المدعومة

تقتصر التعليمة البرمجية المخصصة التي تقوم بتطبيقهَا عَلى مجموعة مِن مسَاحَات الأسمَاء المدعومة. مسَاحَات الأسمَاء هذه هي فِي الغَالب مجموعة مِن مسَاحَات أسمَاء النظَام.* الشَائعة، بمَا فِي ذلك التَسجِيل وNewtonsoft JSON، للمسَاعدة فِي دعم المنطق فِي التعليمَات البرمجية المخصصة الخَاصة بك. للحُصُول عَلى قَائمة كَاملة بمسَاحَات الأسمَاء المدعومة حَاليًا، انتقل إلى مسَاحَات الأسمَاء المدعومة.

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

أمثلة عَلى التعليمَات البرمجية المخصصة الأخرى

لمَعرفَة المزيد حول أنواع التحويلات المختلفة التي ستكملهَا باستِخدَام تعليمَات برمجية مخصصة، يمكنك استعرَاض أمثلة موصلات Microsoft Power Platform المنشورة. من خلال البحث عن ScriptBase فِي المستودع العَام PowerPlatformConnectors، يمكنك عَرض الموصلات الحَالية التي تقوم بتنفيذ التعليمَات البرمجية المخصصة.