تعلم كيفية بناء وتطوير مشاريع تستخدم eConnect

[humam]

رأيت انه من الافضل فصل هذا الموضوع عن الجزء الاول والذي كان يتضمن اساسيات eConnect وطريقة تثبيته بينما في هذاالموضوع سوف نتطرق الى الجانب التطبيقي واتوقع ان يكون هناك موضوع ثالث منفصل يتعلق بكيفية تغيير اعدادت مكونات eCoonect.

[humam]

e-connect Schema & XML document

لكي يكون التطبيق الذي تطوره قادر على التفاعل مع الجريت بلينز فانه يجب ان يكون قادر على ارسال واستقبال وثائق XML التي تصف GP Transactions & Document ان e-connect يمتلك ما يعرف ب eConnect Schema وهي ببساطة عبارة عن اداة لضبط وثائق XML بحيث تكون ضمن السياقات التي يمكن ل eConnect من التعامل معها وهي سوف تحتوي على التركيب النحوي لعبارت XML التي يجب استخدامها والتقيد بها.
ملاحظة:ملف Schema هو عبارة عن ملف XML بأمتداد .xsd

اين تجد ملفات eConnect Schema

عند تنصيب eConnect بالشكل الصحيح سوف تجد ملفات eConnect Schema في المواقع التالية:
c:\Program Files\Common Files\Microsoft Shared\eConnect 10\XML Schema\Incoming
XSD Individual Schema

ومن اسم المجلد الاخير يدل على انك سوف تجد اكثر من ملف .xsd وكل واحد سوف يخص احدى وثائق XML اي سوف توجد هناك انواع متعددة من وثائق XML مثلا وثائق لنقل Master Data وهي بالضرورة سوف تختلف عن وثائق XML التي سوف تنقل Transaction Data وبتالي فأن لكل وثيقة سوف تكون هناك مجموعة من القواعد الخاصة بها وهذه القواعد هي عبارة عن ملفات eConnect Schema ارجو ان يكون هذا الشرح المبسط قد ازال بعض الغموض عن هذه الملفات.

الملف الثاني هو eConnect.xsd وسوف تجده في المسار التالي :
c:\Program Files\Common Files\Microsoft Shared\eConnect
10\XML Schema\Incoming XSD Schemas

وهذا الملف سوف يحتوي على Schema لكل وثائق XML وبصورة مجتمعة والغرض من هذا الملف والملفات السابقة انه في التطيبق الذي تطوره بواسطة .NET قد تحتاج الى عمل Validation لوثائق XML التي تولذها وهذا الملف يعطيك قابلية على عمل Validation لمختلف الانواع او يمكن استخدام الملفات المفردة لعمل Validation لكل وثيقة على حدة.

[humam]

eConnect XML Document Structure

ان eConnect Schema سوف تصف هرمية eConnect XML Document حيث كما هو معروف ان وثائق XML سوف تمتلك بناء هرمي يستخدم لوصف البيانات وان وثائق XML سوف تحتوي على ما يسمى ب Node والتي تمتلك علاقات من نوع Parent/Child وكذلك تمتلك ما يمسى ب Element الذي يستخدم لوصف البيانات وفي الحقيقة ان العمل مع eConnect يحتاج لبعض المتطلبات التي يجب ان يمتلكها المطور مثل معرفة هرمية XML معرفة كيفية العمل مع اطار العمل .NET وللمزيد يجب ان يحصل على قدر من الدراية ب MSMQ في حالة رغب في استخدام Biz Talk Server ولكن اتصور ان الحد الادنى مطلوب اي ليس مطلوب منك ان تكون محترف في هذه المواضيع لتكون قادر على فهم كيفية عمل eConnect ولكن التطبيق العملي لكي يكون ناجح نعم يحتاج الى مطورين من ذوي الخبرة وخصوصا ضمن نطاق التعامل مع وثائق XML في اطار العمل .NET وغيرها من المتطلبات الاخرى.
نعود الى هرمية eConnect XML والتي تمتلك تركيب خاص بها كما وضحت سابقا وهذا التركيب يكون مدرج ضمن ملفات .xsd وقد ذكرت هذه المعلومة بشكل مكرر في هذا الموضوع ولذا سوف اتوقف عن ذكرها ولكن يجب ان تكون حاضرة في الذهن.
وان هذه الهرمية تشير الى وجود ثلاث مستويات مختلفة ترتبط فيما بينها بعلاقة Parent/Child وهي :

eConnect Document
eConnect Transaction Type
eConnect XML Node

الشكل التالي يوضح هذا البناء الهرمي بشكل مبسط :

من الشكل السابق تكون العلاقة بين المستويات الثلاثة واضحة ان eConnect Document سوف يكون هو الجذر الرئيسي اي الاب لكل العناصر الباقية و eConnect Transaction Type سوف يكون الاب لباقي الNode المحتواة في داخله وهي eConnect XML Node واخيرا سوف تحتوي eConnect XML Node على العناصر Elements والتي سوف تستخدم لوصف البيانات اتمنى ان تكون العلاقة واضحة بين المستويات الثلاثة.

[humam]

eConnect Document

كما نلاحظ ان السطر الاول والذي يحتوي على معرف XML وكذلك Schema ومن المهم جدا ان تعرف ان الوثيقة سوف تحتوي على Node واحدة فقط من نوع eConnect Transaction Type وهذا الامر مهم جدا لانه في حالة حصول اي خطأ في عملية تحديث البيانات سوف يتم استخدام rollback لازالة كل Transactions الموجودة في الوثيقة لذا تؤكد الوثائق على ضرورة ان تحتوي XML Document على معلومات تتعلق بنوع واحد من GP Transaction اي يجب عدم خلط الانواع المختلفة وذلك لكي تكون هناك امكانية لاستخدام Rollback في حالة حصول خلل.


eConnect Transaction Type

وهي تعتبر Parent Node لباقي الNodes المحتواة في داخلها وهي سوف تمثل GP Document Or Operation ومن الممكن ان تحتوي في داخلها على اكثرمن Child Node واحدة في الشكل اعلاه نلاحظ انها تحتوي على عقدتين الاولى هي <eConnectProcessInfo> وهي نوع خاص من Node سوف نوضح لاحقا اهميته والعقدة الثانية هي <taSopHdrIvcInsert> والتي تمثل eConnect XML Node .
<eConnectProcessInfo> Node

ان eConnect Schema تشترط ان تكون اول Node ضمن eConnect Transaction Type هي من النوع <eConnectProcessInfo> وتستخدم هذه العقدة للتحكم بكيفية تنفيذ eConnect Transaction Type Node في المثال التالي يوضح كيفية استخدام هذه العقدة eConnect Connection String :

<eConnectProcessInfo>
<ConnectionString> Provider=SQLOLEDB.1;
Integrated Security= SSPI;
PersistSecurity Info= False;
Initial Catalog= TWO;
Data Source= GP10
</ConnectionString>
</eConnectProcessInfo>

[humam]

eConnect XML Node

ان XML Node يمكن ان يكون Parent لاكثر من Element واحد وان Element سوف تحتوي على Data Value ويقوم eConnect باستخدام هذه Data Value لتحديث بيانات الجريت بلينز.
ان eConnect Schema تعرف الخصائص التي يجب ان تمتلكها XML Node وهي كما يلي :
اسم العنصر element name : حيث ان لكل عنصر هناك اسم يجب ادراجه بين Tags ويجب ان نستخدم الاسماء المعرفة مسبقا مثل :

<BACHNUMB>TEST14</BACHNUMB>

الحقول المطلوبة required field : كما نعلم ان لكل عنصر من عناصر الجريت بلينز سوف تكون هناك حقول اخيارية واخرى اجبارية لذا يجب ان توفر كل الحقول المطلوبة لتحديث Module معين وفي حالة اغفال هذه الحقول سوف يؤدي ذلك الى خطأ.
نوع البيانات Data type :وهذا الجزء يخبرك بنوع المعلومات التي يستقبلها هذا العنصر مثلا اذا كان Customer Name سوف يكون نوع البيانات هو String .
محددات البيانات Data constraint :بعض انوع العناصر تحتاج الى قيم محدد من البيانات ويجب الالتزام بها اذا مررت قيم خاج هذا النطاق سوف يؤدي ذلك الى حصول خطأ.

تكوين eConnect XML Document

بما ان لغة XML هي عبارة عن لغة نصية لذا سوف تكون قادر على تكوين XML بواسطة اي برنامج نصوص او يمكن استخدام برامج مثل XML Editor ولكن تنصح وثائق eConnect بأستخدام البرمجة لتكوين وثائق XML وذلك لان البناء اليدوي قد عمليا شبه مستحيل لذا يوفرeConnect نوعين من Assemblies يمكن استخدامها لبناء XML برمجيا :

Microsoft.Dynamics.GP. eConnect.Serialization.dll

في حالة استخدام هذه المكتبة فأن Serialization سوف يعمل على تنظيم XML بشكل مماثل لمواصفات eConnect Schema .

Microsoft.Dynamics.GP. eConnect.Serialization.dll

في حالة استخدام هذه المكتبة فأن NET سوف لا يعيد ترتيب XML بحيث توافق eConnect Schema بل يتم امرار XML بنفس التركيب الذي تم تصميمه

[humam]

Using eConnect to update existing Document

يوجد العديد من XML Document تسمح لك بالقيام بعملية تحديث بيانات GP Documents الموجودة مسبقا ولكي يكون eConnect قادرعلى تحديث هذه Documents فأن eConnect XML Document يجب ان تحتوي على نوع خاص من eConnect XML Node تحتوي على Update Functionality .

ملاحظة:سوف استخدم مصطلح XML Document للدلالة على eConnect XML Document و Transaction Type للدلالة على eConnect Transaction Type واخيرا XML Node للدلالة على eConnect XML Node .

ان هذه XML Node الخاصة والتي تمتلك Update Functionality سوف تشير الى Business Object والذي كما ذكرنا في السابق انه مجموعة من الاجراءات المخزنه ووضيفة هذا Business Object هو التأكد هل ان البيانات الموجودة في XML Node تخص GP Document موجودة مسبقا في قاعدة البيانات ام لا فأذا وجد Business Object هذه البيانات موجودة مسبقا سوف يقوم بتحديث تلك Documents اما اذا لم تكن موجودة سوف يضيف Document جديدة .

بالنسبة الى الطرق التي يستخدمها Business Object لتحديث GP Document هناك طريقتين يمكن استخدامها:

Document Exchange: في هذه الحالة فان Business Object سوف يقوم بعملية تحديث لجميع حقول البيانات سواء تم امرار هذه الحقول او لم يتم امرار قيم هذه الحقول وفي حالة ترك قيم بعض الحقول فارغة فسوف يتم استخدام eConnect default value لاعداد هذه الحقول اي ببساطة عند استخدام هذه الطريقة سوف تحتاج الى امرار قيم جميع الحقول حتى لو لم تتغير قيمها السابقة.

Field Level Update: في هذه الطريقة يمكن السماح بادراج فقط الحقول التي سوف تتغير قيمها ضمن XML Node اما الحقول التي لم يتم ادراجها ضمن XML Node سوف تحتفظ بقيمها السابقة.

Automating document number assignment
ان XML Document التي تعمل على تكوين GP Documents جديدة سوف تحتاج ان تمرر المعرف الخاص بهذه Document ضمن XML Node ولكن بعض XML Document توفر امكانية ايجاد Document Number عن طريق استرجاع المعرف السابق لأخر Document ثم زيادته بمقدار واحد وتعيينه الى Document الجديدة وللقيام بذلك فان XML Document يجب ان تحتوي على Schema توفر Auto numbering اي ان هذه الخاصية ليست متاحة لكل انوع XML Document وبعد التأكد من وجود هذه الخاصية يجب ان تمرر العنصر الذي يمثل Document Number مع تركه فارغا وبتالي سوف يقوم eConnect بالبحث عن الرقم واسناده الى الوثيقة.
في المثال التالي يوضح XML Document تستخدم Transaction Type من نوع GL وهنا سوف نلاحظ كيفية ترك حقل JRNENTRY فارغ للحصول على الرقم بصورة ذاتية :

<taGLTransactionHeaderInsert>
<BACHNUMB>TEST14</BACHNUMB>
<JRNENTRY></JRNENTRY>
<REFRENCE>General Transaction</REFRENCE>
<TRXDATE>2007-01-21</TRXDATE>
<RVRSNGDT>1900-01-01</RVRSNGDT>
<TRXTYPE>0</TRXTYPE>
<SQNCLINE>16384</SQNCLINE>
</taGLTransactionHeaderInsert>

ملاحظة:
ان SOP Document لاتتطلب منك امرار عنصر يمثل معرف الوثيقة بل سوف تقوم بشكل ذاتي بتحديث معرف GP Document سواء مررت العنصر الذي يمثل معرف الوثيقة وتركته فارغا او لم تذكر هذا المعرف ضمن XML Node . ولكن في حالة كونك مررت العنصر الذي يمثل المعرف مع قيمة سوف يؤدي ذلك الى استخدام هذه القيمة لتحديث حقل المعرف في قاعدة البيانات.

[humam]

الجدول السابق يحتوي على انواع وثائق XML التي تدعم Auto Numbering

[humam]

Dot NET Development

لكي تكون قادر على تصميم مشاريع بواسطة اطار العمل .NET يجب ان تعمل على ادراج مرجع لل eConnect assembly في المشروع الذي تصممه وان assembly eConnect سوف تحتوي على فضاء الاسماء name space الذي يمكنك من انشاء كائنات eConnect واستدعاء طرقها المختفلة وبصورة عامة ان مكونات eConnect تحتوي على assemblies التالية :
Microsoft.Dynamics.GP.eConnect.dll
Microsoft.Dynamics.GP.eConnect.MiscRoutines.dll
Microsoft.Dynamics.GP.eConnect.Serialization.dll
والتي يمكن ان تجدها في المجلد التالي :
Files\Common Files\Microsoft Shared\eConnect 10\Objects\Dot Net. C:\Program

Adding Reference

لكي تكون قادرعلى استخدام المكتبات الدياميكية انفة الذكر في مشاريعك عليك اضافة مرجع لهذه المكتبات :
بالضغط على اسم المشروع ثم اختر Add Reference ومن نافذة Add Reference اختر علامة التبويب Browse ومنها اختر المجلد Dot Net الموضح مساره الكامل سابقا وسوف تجد ملفات assemblies اختر المجموعة وانقر على الزر Ok وبهذا اضفت مرجع لهذه المكونات وبتالي سوف تكون قادر على استدعاء طرق واحداث eConnect ضمن مشروع .NET الذي تطوره.

Including Namespace

في الحقيقة اتوقع ان يكون مفهوم Namespace او فضاء الاسماء مستوعب من قبل المطورين على اعتبار انه من مفاهيم برمجة .NET الاساسية اما بالنسبة للذين لايمتلكون هذه الخلفية سوف احاول اعطاء شرح مبسط ولانني في هذا الموضوع اود ان اركز على استخدام مكونات eConnect اما موضوع مفاهيم برمجة .NET فانها تحتاج الى مجلدات لشرحها وتوجد هناك مواقع متخصصة بهذا الموضوع يمكن الاطلاع عليها.
فضاء الاسماء يستخدم لعملية احتواء مجموعة من الكتل البرمجية والتي تؤدي وظائف معينة ويسهل على المطورين عملية الوصول الى الكائنات الموجودة داخل هذه الكتل.
بالنسبة الى eConnect Namespace يمكن استدعاء فضاء الاسماء الخاص بها عن طريق استخدام عبارة Import بالنسبة الى VB.NET او عبارة Using في حالة استخدام C# :

Imports Microsoft.Dynamics.GP.eConnect

Using Imports Microsoft.Dynamics.GP.eConnect.MiscRoutines;

[humam]

Microsoft.Dynamics.GP.eConnect.dll

هنا سوف نشرح الطرق والكائنات المتوفرة في هذه المكتبة الدياميكية والتي يمكن استدعاء مكوناتها عن طريق تضمين فضاء الاسماء Microsoft.Dynamics.GP.eConnect وتحتوي هذه المكتبة على ثلاث فئات اساسية هي :
eConnectMethod: وهذه الفئة تعطيك امكانية ارسال واستلام وثائق XML.
EnumTypes: وهذه الفئة تحتوي على ثوابت من النوع Enum والتي تحتاج الى امرارها الى الطرق التي سوف تستخدمها من الفئة الاولى.

eConnectException: وهذه الفئة تجعلك قادر الى متابعة الاستثناءات التي قد تحصل اثناء العمل مع مكونات eConnect.

ملاحظة: للمزيد من المعلومات حول Enum و Exception يمكن مراجعة مكتبة MSDN.

الفئة eConnectMethod :

وتحتوي هذه الفئة على طريقتين هما :
1. eConnect_EntryPoint method
2. eConnect_Requester method
ولكي تكون قادر على استدعاء هذه الطرق عليك ان تعرف اولا كائن من النوع eConnectMethod وكما يلي:
VB.NET:

Dim eConnectObject As New eConnectMethods

C#:

eConnectType eConnect = new eConnectType();

في C#نلاحظ انك تحتاج اولا الى ذكر نوع الكائن او المتغير ثم تتبعه بأسم المتغير وبعد ذلك تتم عملية انشاء نسخة جديدة من الكائن بواسطة العبارة new.

الطريقة eConnect_EntryPoint method

وهي تسمح لك بعملية ارسال وثائق XML من التطبيق الذي تصممه الى برنامج الجريت بلينز وتمتلك هذه الدالة خمس بارمترات هي:
ConnectionString: وهي عبارة عن سلسلة نصية تحتوي على اسم المزود واسم قاعدة البيانات واعدادات الامان:

sConnectionString = @aa"data source=GP10;initial catalog=TWO;integrated security=SSPI";
هذا المثال بلغة C# والمعامل @aa ضروري في بداية العبارة لكي يتم ترجمتها مثل ما هي بدون الحاجة الى استخدام معاملات الهروب.
ConnectionString = "DataSource=GP10; Integrated Security=SSPI;
"Persist Security Info=False; Initial Catalog=TWO"
هذا المثال بلغة VB.NET

ConnectionType: وهنا سوف نحدد نوع الاتصال ويوجد هناك خياران هما:

EnumTypes.ConnectionStringType.SqlClient
EnumTypes.ConnectionStringType.OleDb

الخيار الاول يعني ان الاتصال يتم مع مصدربيانات SQL Server اما OleDb يستخدم للاتصال مع الانواع الاخرى من قواعد البيانات ونلاحظ ان قيمة هذا البارمتر هي من النوع EnumTypes والمضمنة في الفئة EnumTypes .

sXML:وسوف يمثل هذا البرامتر XML document لذا عليك ان تنشىء كائن من هذا النوع لكي تمرره الى هذه الطريقة.

ValidationType: وهنا سوف تحدد نوع التحقق وهناك قيميتين هما None او XSD في حالة None هذا يعني انك لاتريد ان تجري عملية تحقق على وثيقة XML التي ترسلها الى الجريت بلينز اما الخيار الثاني XSD فهو يعني انك تريد التحقق من تركيب وثيقة XML باستخدام eConnect Schema قبل ارسالها الى الجريت بلينز وقد ذكرنا سابقا عن ملفات Schema ما الغرض منها واين يمكنك ايجادها.

eConnectSchema:ان هذا البرامتر سوف يكون اختياري في حالة كونك استخدمت القيمة None في البرامتر السابق اما اذا استخدمت القيمة XSD فعليك هنا توضيح مسار ملف XSD الذي سوف تستخدمه في عملية المقارنه والتحقق.

[ماهر أحمد]

فعلا على قولت المثل:
أعطي القوس لباريها ... أنت رجل مبدع يا استاذ همام
مقالات من أقوى المقالات اللي قريتها بحياتي

متشكرين

[humam]

فعلا على قولت المثل:
أعطي القوس لباريها ... أنت رجل مبدع يا استاذ همام
مقالات من أقوى المقالات اللي قريتها بحياتي

متشكرين

الشكر لله اخي العزيز وشكرا جزيلا على هذا الاطراء الجميل وعسى ان اكون عند حسن ظنكم

[humam]

استخدام الطريقة eConnect_EntryPoint method

سوف نورد مثال حول الطريقة السابقة في عملية ارسال XML document الى قاعدة بيانات الجريت بلينز ويمكن تصميم نموذج مبسط يحتوي على زر اسمه Submit ومربع نص XML Doc يستخدم لادخال وثيقة XML ويمكن الاستعانة بنماذج XML المرفقة مع eConnect للحصول على محتويات الوثيقة ثم ادراجها في مربع النص والضغط على الزر Submit لارسال تلك الوثيقة الى الجريت بيلنز وفي حالة تنفيذ الشفرة بنجاح نظهر رسالة بذلك :لاحظ الصورة المرفقة
المثال بسيط جدا في البداية نعرف عبارة الاتصال وبعد ذلك نعمل على تحميل وثيقة XML من مربع النص الى متغير الكائن الذي يمثل وثيقة XML وهو الكائن xmlDoc وذلك بأستحدام الطريقة LoadXml التابعة لهذا الكائن بعد ذلك ننشىء نسخة جديدة من الكائن eConnectObject بأستخدام الكلمة new مع الملاحظة اننا في بداية الشفرة عرفنا متغير من النوع eConnectMethods طبعا هناك فرق بين عملية انشاء متغير الكائن وعملية انشاء نسخة من الكائن وهذا الموضوع من اساسيات البرمجية كائنية التوجه OPP بعد ذلك قمنا باستدعاء الطريقة eConnect_EntryPoint التابعة للكائن eConnectObject وامرار البارامترات المطلوبة لهذه الطريقة ونلاحظ كيفية الاستعانة بالفئة EnumTypes للحصول على الثوابت المطلوبة مثل sqlClient لتحديد نوع قاعدة البيانات و الثابت None للدلالة على اننا سوف لن نستخدم Validation للتحقق من صحة تركيب هذه الوثيقة لذا تلاحظ اننا لم ندرج المعامل الاخير والذي يشير الى مسار ملف schema لاننا هنا اخترنا عدم التحقق لذا يمكن اهمال هذا البرامتر لانه اصبح اخياري ولكن يجب ان تمرر وثيقة eConnect XML لضمان تنفيذ الشفرة بشكل صحيح.
واخيرا نتحقق من القيمة المعادة بواسطة الدالة لمعرفة هل تم التنفيذ بنجاح ثم افتح برنامج الجريت بلينز للتحقق من وجود السجل الذي اضفته افضل ان تستخدم eConnect XML التي تخص Customer لانها من ابسط الانواع ونسبة حصول الخطاء قليلة .

[humam]

ملاحظة:

ان استخدام هذه الطريقة بهذا الشكل المبسط ليس عمليا لانك هنا سوف تنسخ وثيقة XML الجاهزة وتدرجها في مربع النص ولكن في الجانب العملي تحتاج الى التحكم برمجيا بهذه الوثيقة وسوف نوضح ذلك انشاء الله بعد التطرق الى طرق المكتبة الديناميكية eConnect.Serialization.dll
والتي تحتوي على هذه الامكانيات ولكن بصراحة يجب ان يكون المتتبع لهذا الموضوع له اطلاع على تقنية Object Serialization ويصنف هذا الموضوع ضمن المواضيع المتقدمة لبرمجة اطار العمل .NET وسوف احاول اعطاء نبذة مختصرة عن هذا المفهوم كما ذكرت في الشرح السابق هناك فرق بين نسخة الكائن Object Instance وبين متغير الكائن Object Pointer ان انشاء نسخة جديدة من كائن سوف يؤدي الى حفظ عناصر هذا الكائن في منطقة معينة من الذاكرة تسمى Managed Heap ولكن انشاء متغير الكائن سوف لا يؤدي الى عملية نسخ الكائن الى هذه المنطقة من الذاكرة بل يؤدي الى انشاء مؤشر في الذاكرة يحتوي على موقع الكائن في Managed Heap تأتي عملية تسلسل الكائنات Object Serialization وهي عملية نسخ لنسخة الكائن Object Instance في وحدة تخزين Stream والتي قد تكون على القرص الصلب او في الذاكرة وفيما بعد يمكنك استرجاع نسخة الكائن بواسطة عملية Object Deserializing وامرارها الى مؤشر الكائن او Object Pointer اعرف ان هذا الكلام لايزيل الغموض عن هذا الموضوع لكنه يعطي فكرة مبسطة .

[humam]

الطريقة eConnect_Requester method

وهي الطريقة الثانية ضمن هذه المكتبة الديناميكية وتستخدم لأسترجاع البيانات من الجريت بلينز وهي تمتلك ثلاث بارامترات هي:
ConnectionString: وهي عبارة عن سلسلة نصية تحتوي على اسم المزود واسم قاعدة البيانات واعدادات الامان.

ConnectionType: وهنا سوف نحدد نوع الاتصال ويوجد هناك خياران هما:

EnumTypes.ConnectionStringType.SqlClient
EnumTypes.ConnectionStringType.OleDb

الخيار الاول يعني ان الاتصال يتم مع مصدربيانات SQL Server اما OleDb يستخدم للاتصال مع الانواع الاخرى من قواعد البيانات ونلاحظ ان قيمة هذا البارمتر هي من النوع EnumTypes والمضمنة في الفئة EnumTypes .

sXML:وسوف يمثل هذا البرامتر XML document لذا عليك ان تنشىء كائن من هذا النوع لكي تمرره الى هذه الطريقة.

الدالة سوف تعيد عبارة نصية تمثل البيانات التي تم استرجاعها من الجريت بلينز و على شكل وثيقة XML.

[humam]

استخدام الطريقة eConnect_Requester method

سوف نحاول تطوير المثال البسيط الذي استخدمناه مع الطريقة السابقة عن طريق اضافة زر جديد الى النموذج نطلق عليه اسم Request Button وفي هذا الزر سوف نستخدم الطريقة السابقة لاسترجاع معلومات من الجريت بلينز وبالتحديد سوف نسترجع معلومات عن Customer. السؤال الذي يطرح نفسه كيف سوف نحدد اي زبون نريد استرجاع المعلومات عنه والجواب اذا لاحظنا برامترات الطريقة eConnect_Requester وهي ثلاثة الاول والثاني واضحان و لا لبس فيهما ولكن البرامتر الثالث يشوبه نوع من الغموض وهو ليس مني لان وثائق eConnect تعرفه كما ذكرت ولكن بعد ملاحظة سريعة سوف تكتشف ان السر هنا في هذا البرامتر هنا عليك ان تمرر وثيقة eConnect XML ولكن من نوع خاص وهي تسمى Request Document قبل استدعاء الطريقة ويمكن ان تجد امثلة عن هذا النوع من الوثائق ملحقة في مجلد eConnect وكذلك سوف ارفق ملف صورة لهذه الوثيقة.

[humam]

لاحظ الصورة المرفقة لشفرة الزر Request الشفرة ابسط من سابقتها اولا نعرف متغيرات لعبارة الاتصال ومتغير كائن من نوع eConnectMethods لكي نستدعي الطريقة eConnect_Requester والثالث متغير كائن من نوع XMLDocument بعد ذلك سوف نقوم بأعداد عبارة الاتصال ثم سوف استخدم مربع النص XmlDoc_TextBox بشكل مزدوج هنا في المرة الاولى سوف استخدمه لتمرير eConnect Request XML Document ثم بعد ذلك نحمل هذه الوثيقة الى كائن XML بواسطة الطريقة XMLLoad الان اصبحت برامترات الطريقة جاهزه ويمكن استدعاء الطريقة وكما ذكرنا ان الطريقة سوف تعود بسلسلة نصية تحتوي على البيانات المطلوبة وبتنسيق XML وهنا استخدمت نفس مربع النص لعرض النتيجة المعادة من الجريت بلينز.
الان عند تشغيل التطبيق اول خطوة سوف اقوم بأدراج eConnect Request XML Document في مربع النص وهذه الوثيقة هي التي تحدد اي زبون سوف استرجع وهنا تحتاج الى تمريرالمعرف اي Customer ID . لاحظ الصورة eConnectRequesXML.JPG ثم بعد ذلك سوف اضغط على الزرRequest لأرسال الطلب. وبعد لحظات سوف تعاد النتيجة الى مربع النص كما في الشكل Requested Data.JPG وكما نلاحظ ان المعلومات غير منسقة بشكل مقروء لذا يمكن ان تنسخ هذه المعلومات الى Clipboard ثم اضف ملف جديد الى مشروع .NET من نوع XML والصق هذه البيانات هناك ثم اضغط Ctrl + K , Ctrl +F او Ctrl +A ومن قائمة Edit اختر Advanced ثم Format Selection وسوف تجد ان البيانات تم تنسيقها لتكون مفهومة ومقروءة من قبل المستخدم وهذه احدى ميزات XML اي ان اي شخص سوف يكون قادر على فهم محتوى الوثيقة حتى لو لم يكن له خبرة في XML . لاحظ الصورة Customer XML.JPG
وبهذا ينتهي هذا المثال المبسط.

[humam]

Serialization Assembly

وهنا سوف نتحدث عن المكتبةالثانية من مكتبات eConnect والتي سوف تعطينا امكانية انشاء eConnect XML برمجيا بدل من التعامل بشكل نصي كما فعلنا في الامثلة السابقة والاسم الصريح لهذه المكتبة هو Microsoft.Dynamics.GP.eConnect.Serialization.dll ولكي تكون قادر على استخدام كائنات هذه المكتبة عليك ادراج فضاء الاسماء Microsoft.Dynamics.GP.eConnect.Serialization ضمن المشروع .

قبل التطرق الى فئات هذه المكتبة اود ان اذكر بتركيب وثائق eConnect XML لانه من الضروري ان يكون حاضر في الذهن حتى نستطيع فهم كيفية استخدام هذه المكتبة كما قلنا ان وثيقة XML سوف تكون مكونة من ثلاث مستويات هي :

eConnect Document
eConnect Transaction Type
eConnect XML Node

ان هذه المكتبة سوف تعطيك امكانية انشاء eConnect Transaction Type و eConnect XML Node بشكل برمجي ثم امرارها الى كائن يمثل eConnect XML Node وبتالي سوف تكون قد حصلت على وثيقة XML كاملة عند ذلك يمكنك استخدامها عن طريق امرارها كمعامل الى الطريقة eConnect_EntryPoint method او خزنها على شكل ملف على القرص الصلب وهذا الملف يمكمن استخدامه من قبلMSMQ .

ملاحظة:
سوف تجد كل التفاصيل المتعلقة بانواع transaction type schemas and XML nodes ضمن ملفات help الخاصة ب eConnect .
افضل طريقة لفهم عمل هذه المكتبة هو انشاء مثال عملي

[Monzer Osama]

جهد مبارك أخي همام ... ربنا يفتح عليك

لإدراج أكواد داخل مشاركاتك وكي تظهر بالشكل والتنسيق الجديد
مثل:

your code here

اضغط على الرابط لمعرفة كيفية القيام بذلك ....
http://www.gp4arab.com/forum/showpost.php?p=4002&postcount=7

[humam]

شكرا اخي منذر على هذه الملاحظة نعم ان ادراج الكود ضمن الردود افضل حيث يعطي المتتبع امكانية ملاحظة الشرح مع الاطلاع على الشفرة البرمجية وهذا ما سوف احاول استخدامه في المشاركات القادمة

[humam]

سوف يكون استخدام هذه المكتبة لانشاء eConnect XML document بشكل برمجي وكما وضحت سابقا ان تركيب هذه الوثيقة سوف يكون مكون من Root او Parent Node ممثل ب eConnect Transaction Type وتحت هذا الجذر سوف تأتي باقي الاعضاء او Nodes والتي سوف تمثل eConnect XML Node اعدت شرح التركيب لانه سوف يسهل علينا المثال التالي وهو اعقد نوعا ما من المثال الاول.

[humam]

Sales Order Processing

في هذا المثال سوف نحاول تكوين وثيقة XML تمثل SOP Transaction وهنا سوف نختار تكوين Invoice وكما هو معلوم ان مثل هذه الانواع من Transactions سوف تكون مكونه من جزئين الاول هو Header والثاني هو Details والذي سوف يمثل lines التي تخص Invoice وسوف نعمل على تكوين هذه الوثيقة برمجيا ثم نستخدم تقنية Sterilization لتكوين ملف وبعد ذلك سوف نحول هذا الملف الى وثيقة XML هذا هو الجزء الاول من المشروع.
الجزء الثاني سوف نحاول ارسال وثيقة XML التي كونها برمجيا الى الجريت بلينز لتحديث قاعدة البيانات.
هنا قبل البدء بالتنفيذ العملي انصح بالاطلاع على تركيب وثيقة SOP Transaction schema والتي سوف تكون متوفرة في ملفات Help الخاصة بeConnect وهي على درجة عالية من التعقيد لانها تحتوي على اجزاء عديدة ودرجة التعقيد سوف تكون معتمدة على Functionality التي تريد توفيرها من خلال XML على سبيل المثال سوف تكون هناك اجزاء خاصة ب Commissions و Distributions و Markdown amounts الى اخره من التفاصيل المتعلقة بعملية SOP .

سوف نبداء مشروع .NET جديد ويجب ان تضيف Reference المطلوبة لهذا المشروع وهي كما يلي:

Microsoft.Dynamics.GP.eConnect.dll
Microsoft.Dynamics.GP.eConnect.MiscRoutines.dll
Microsoft.Dynamics.GP.eConnect.Serialization.dll
System Enterprise Services.dll

[humam]

ثم بعد ذلك سوف نضيف Module الى المشروع وسوف نعرف فيها اجراء عام اسمه SerializeSOPObject سوف نوضح من خلاله كيفية استخدام المكتبة Microsoft.Dynamics.GP.eConnect.Serialization.dll للقيام بعملية تكوين eConnect XML بشكل برمجي في البداية سوف نضمن فضاءات الاسماء المطلوبة.

Imports System
Imports System.Xml
Imports System.Xml.Serialization
'Required to convert Seriailaizaion Object to XML and vis versa
Imports System.IO
Imports System.Text
Imports Microsoft.VisualBasic
Imports Microsoft.Dynamics.GP.eConnect
Imports Microsoft.Dynamics.GP.eConnect.Serialization

[humam]

ثم بعد ذلك نعرف الاجراء العام SerializeSOPObject والذي يمتلك بارامتر واحد فقط يستخدم في عملية امرار اسم الملف الذي سوف نخزن XML فيه على القرص الصلب. ثم بعد ذلك سوف نعرف عدد من المتغيرات كما هو واضح في الصورة المرفقة المتغير الاول هو SOPInvoice وهو من نوع SOPTypeTransaction والذي سوف نستخدمه لتكوين Rootلوثيقة XML وسوف يمثل Parent Node وهذا الكائن يمتلك خاصية taSopLineIvcInsert_Items وهي عبارة عن مصفوفة من الكائنات من النوع taSopLineIvcInsert_ItemsTaSopLineIvcInsert والتي تمثل lines ضمن Invoice لذا نعرف متغيري كائن من النوع taSopLineIvcInsert_ItemsTaSopLineIvcInsert الاول يمثل line الاول في Invoice وهو SOPLine1 والمتغير الثاني SOPLine2 والذي يمثل line الثاني في Invoice ثم بعد ذلك نعرف كائن ٍSOPHdr من نوع taSOPHdrIveInsert والذي سوف يمثل Header لل Invoice وسوف نمرر هذا الكائن الى الخاصية taSOPHdrIveInsert التي تعود للكائن SOPInvoice والذي هو من النوع SOPTypeTransaction . بعد نعرف مصفوفة array من النوع taSopLineIvcInsert_ItemsTaSopLineIvcInsert وبحجم 2 اي تمتلك عنصرين وعناصر هذه المصفوفة lineItemArray هي كائنات من النوع taSopLineIvcInsert_ItemsTaSopLineIvcInsert


Dim SOPInvoice As New SOPTransactionType
Dim SOPLine1 As New taSopLineIvcInsert_ItemsTaSopLineIvcInsert
Dim SOPLine2 As New taSopLineIvcInsert_ItemsTaSopLineIvcInsert
Dim SOPHdr As New taSopHdrIvcInsert
Dim lineItemArray(1) As taSopLineIvcInsert_ItemsTaSopLineIvcInsert

[humam]

الخطوة التالية هي بداية حلقة من نوع Try-End Try لتنفيذ الشفرة المطلوبة مع وضع امكانيات لمعرفة Exceptions عند حدوثها اولا سوف نبدأ بأعداد الكائن SOPLine1 بأمرار القيم التي تمثل Line وهنا يجب امرار كل Required Fields التي يحتاجها تكوين line ويمكن معرفة هذه الحقول عن طريق مراجعة ملفات help وبعد اكمال اعدادات هذا الكائن نمرره الى المصفوفة lineItemArray وهكذا سوف نعمل على اعداد الكائن SOPLine2 وامراره الى المصفوفة lineItemArray .
بعد ذلك سوف نمرر المصفوفة lineItemArray الى الخاصية taSopLineIvcInsert_Items العائدة للكائن SOPInvoice لكن قبل ذلك يجب اعداد الخاصية عن طريق تحديد حجم المصفوفة وهذا ما تقوم به عبارة ReDim

Try
'Create Line XML Node
'Create element of first Line in the Invoice
With SOPLine1
.ADDRESS1 = "Zyenoa 22/160"
.CITY = "Baghdad"
.COUNTRY = "Iraq"
.CUSTNMBR = "Humam"
.SOPNUMBE = "INV1"
.SOPTYPE = 3
.DOCID = "STDINV"
.QUANTITY = 2
.ITEMNMBR = "ACCS-CRD-12Wh"
.ITEMDESC = "Phone Cord – 12’ White"
.UNITPRCE = 10.95
.XTNDPRCE = 21.9
.LOCNCODE = "WAREHOUSE"
.DOCDATE = DateString
End With
'Add first line to array
lineItemArray(0) = SOPLine1
'Create element of second Line in the Invoice
With SOPLine2
.ADDRESS1 = "Zyenoa 22/160"
.CITY = "Baghdad"
.COUNTRY = "Iraq"
.CUSTNMBR = "Humam"
.SOPNUMBE = "INV1"
.SOPTYPE = 3
.DOCID = "STDINV"
.QUANTITY = 2
.ITEMNMBR = "ACCS-CRD-25BK"
.ITEMDESC = "Phone Cord – 25’ Black"
.UNITPRCE = 15.95
.XTNDPRCE = 31.9
.LOCNCODE = "WAREHOUSE"
.DOCDATE = DateString
End With
'Add second line to array
lineItemArray(1) = SOPLine2
'chaneg size of array in SOPInvoice and pass
lineItemArray
as lines
'Add Line Node to Transaction Type
ReDim Preserve SOPInvoice.taSopLineIvcInsert_Items(1)
SOPInvoice.taSopLineIvcInsert_Items = lineItemArray

[humam]

بعد ذلك نعمل على اعداد الكائن ٍSOPHdr وهنا يجب امرار كل Required Fields التي يحتاجها تكوين Header ويمكن معرفة هذه الحقول عن طريق مراجعة ملفات help ثم بعد ذلك نمرر الكائن الى الخاصية taSopLineIvcInsert_Items التي تعود للكائن SOPInvoice وبنهاية هذه الخطوة نكون قد كونا Nodes التالية :
اولا. Transaction Type Node وهي تمثل Parent Node ويمثلها الكائن SOPInvoice
ثانيا. كونا ثلاثة عقد 3 Nodes واحدة تمثل Header واثنتان تمثلان Lines ممثلة بالكائنات SOPHdr و SOPLine1 و SOPLine2 وهذه Nodes تعتبر ابناء Childs للParent Node وبتالي نكون قد اتبعنا التسلسل الصحيح لتركيب eConnect Nodes .

'Header XML Node
'Create Invoice Header
With SOPHdr
.SOPTYPE = 3
.SOPNUMBE = "INV1"
.DOCID = "STDINV"
.BACHNUMB = "Test"
.LOCNCODE = "WAREHOUSE"
.DOCDATE = DateString
.CUSTNMBR = "HUMAM"
.CUSTNAME = "HUMAM"
.ShipToName = "WAREHOUSE"
.ADDRESS1 = "Zyenoa 22/160"
.CITY = "Baghdad"
.COUNTRY = "Iraq"
.CNTCPRSN = "Humam"
.FAXNUMBR = "13125550150"
.ZIPCODE = "65700"
.SUBTOTAL = 53.8
.DOCAMNT = 53.8
.USINGHEADERLEVELTAXES = 0
.PYMTRMID = "Net 30"
End With
'Add Header Node to Transaction Type
SOPInvoice.taSopHdrIvcInsert = SOPHdr

[humam]

الان سوف نحتاج الى الخطوة الاخيرة وهي عملية تكوين XML Document حيث قمنا بتعريف كائن eConnect وهو من النوع eConnect Type والذي سوف يمثل eConnect XML Document وهذا الكائن يمتلك خاصية SOPTypeTransaction وهي تستقبل مصفوفة من الكائنات من النوع SOPTypeTransaction اي يمكن ارسال اكثر من Invoice واحدة من خلال نفس XML Document وهنا كل Invoice سوف تكون ممثلة بكائن من نوع SOPTypeTransaction وبما ان هذه الخاصية هي من نوع array لذا يجب اعداد حجم المصفوفة قبل استخدامها عن طريق العبارة ReDim ثم بعد ذلك نمرر الكائن SOPInvoice لها وبهذا تنتهي عملية انشاء eConnect XML Document .

Dim eConnect As New eConnectType
ReDim Preserve eConnect.SOPTransactionType(0)
eConnect.SOPTransactionType(0) = SOPInvoice

[humam]

عملية Serialization

وهنا سوف نعمل على تحويل الكائن eConnect الذي يمثل وثيقة eConnect XML الى ملف على القرص الصلب وبتالي يمكن استدعاء هذا الكائن من قبل الشفرات البرمجية الاخرى. وهنا سفو تبدأ العملية عن طريق تعريف ملف من نوع FileStream وهنا سوف نمرر اسم الملف الذي يمثل بارامتر الاجراء الذي نعمل عليه وهو filename وكذلك نحدد العملية المطلوبة وهي تكوين ملف ثم بعد ذلك سوف نحتاج الى تحديد نوع writer الذي سوف يستخدم في كتابة الملف وهنا استخدمنا XMLWriter والذي سوف يأخذ معاملين هما اسم الملف ومعرف الشفرة المستخدمة لكتابة الملف.
بعد ذلك سوف نعرف كائن من نوع XMLSerializer والذي يعمل على تحويل الكائن الذي تم امرار نوعه اليه اثناء انشاء الكائن وهذا ما تقوم به عبارة Get Type التي تعيد فئة الكائن يقوم بتحويل هذا الكائن الى ملف عن طريق الطريقة Serialize التابعة لهذا الكائن والتي تأخذ معاملين الاول يمثل كائن من نوع Writer الذي سوف يستخدم لكتابة الكائن والمعامل الثاني هو الكائن نفسه المراد كتابته وهو في هذه الحالة eConnect والذي يمثل eConnect XML ثم في اخر خطة نقوم بأغلاق writer وبهذا ينتهي الاجراء SerializeSOPObject الذي استخدم لتكوين ملف XML برمجيا ثم تحويله الى ملف XML عادي .


'Start Serialization
Dim sopFileStream As New FileStream(fileName, FileMode.Create)
Dim XMLwriter As New XmlTextWriter(sopFileStream, New UTF8Encoding)
'Serialize using the XmlTextWriter to the file
Dim MySerializer As New XmlSerializer(GetType(eConnectType))
MySerializer.Serialize(XMLwriter, eConnect)
XMLwriter.Close()
Catch ex As Exception
MsgBox("System error:" + ex.Message)
End Try

[humam]

شفرة الزر Submit

هنا ان الشفرة لاتختلف كثيرا الشفرة التي اوردناها في المثال الاول لذا لن اتوسع في شرحها سوف ابين فقط نقطة الاختلاف عن الشفرة السابقة حيث ان هذه الشفرة سوف ترتكزعلى استخدام الطريقة eConnect_EntryPoint والتي تستخدم الى ارسال الوثائق الى الجريت بلينز وكما نعلم ان هذه الطريقة سوف تحتاج الى برامتر من نوع XML Document في الشفرة السابقة قمنا بأدخال الكائن بشكل يدوي عبر كائن النص ثم امراره الى الطريقة هنا سوف نستدعي الاجراء الذي صممناه SerializeSOPObject لتكوين وثيقة XML برمجيا ثم تحويلها الى ملف ومن ثم نقراء وثيقة XML من هذا الملف بدل القراءة من مربع النص اما مربع النص الموجود هنا فهو فقط لاظهار تاثير مرئي للمستخدم لملاحظة وثيقة XML التي سوف يتم ارسالها ويمكن نسخ هذه الوثية وتنسيقها بشكل جيد ضمن اطار العمل .NET وبهذا ينتهي المثال الخاص بالمكتبة Serialization

Dim SOPInvoiceDocument As String
Dim ConnectionString As String
'Add referance to System.EnterpriseServices
Dim eConnectObject As New eConnectMethods
Dim Result As Boolean
Dim xmldoc As New Xml.XmlDocument
Try
'Call the SerializeSOPObject subroutine and specify
'a file name Create eConnect XML Document
SerializeSOPObject("SOPInvoice.xml")
'Create an XML document object and load it with the XML
from the
'file that the SerializeSOPObject subroutine created
xmldoc.Load("SOPInvoice.xml")
'Convert the XML to a string
SOPInvoiceDocument = xmldoc.OuterXml
XML.Text = xmldoc.OuterXml
XML.ScrollBars = ScrollBars.Both
'Set the connection string
'This connection string uses integrated security to connect
to the
'TWO database on the local computer
ConnectionString = "Data Source=ISYS-MYNET\GP10;Integrated
Security=SSPI;" _
& "Persist Security Info=False;Initial Catalog=TWO;"
'Send XML document to GP
Result = eConnectObject.eConnect_EntryPoint(ConnectionStrin g,
EnumTypes.ConnectionStringType.SqlClient, _
SOPInvoiceDocument, EnumTypes.SchemaValidationType.None)
Catch ex As eConnectException
MsgBox(" XML error " + ex.Message)
Catch ex As SystemException
MsgBox("Error:" + ex.Message)
End Try

[Monzer Osama]

جهد رائع أخي الحبيب ... زادك الله علما ومعرفة...
أخي هل هذه الأمثلة تنطبق على الـ E-Connect 10 علما بأن الـ Schema الخاصة بشاشة الـ SOP ما اختلفت .... لكن سؤالي عن التعامل مع الكود.

[humam]

والله اخي العزيز انا طبقت هذه الامثلة على GP10 لكن من ناحية Code انها لاتختلف بين GP10 وGP9 واذا كان من اختلاف يحدث فهو في Schema اي اذا غيرت المايكروسوفت تركيب SOP في GP10 عنه في GP9 عند ذلك سوف تحتاج الى تعديل الشفرة وشكرا

[عثمان]

متشكر عزيزي همام ....
دروس أكثر من رائعة

[humam]

الشكر لله اخي عثمان

[humam]

اعتقد بنهاية المثال السابق نكون قد انهينا هذا الموضوع واتمنى ان يوفر الاسس التي بستطيع من خلالها الاخوة المطورين بناء البرامج التي تتعامل مع eConnect وفق المتطلبات التي يرغبون بتحقيقها

[Shaheen]

تحياتي لك استاذي همام
موضوع رائع من قبل شخص رائع

[humam]

تحياتي لك استاذي همام
موضوع رائع من قبل شخص رائع

الله يخليك اخوية شاهين انت الاروع

[أحمد الغامدي]

May Allah Save You Brother Humam

Your topice very useful

Thanks

[humam]

May Allah Save You Brother Humam

Your topice very useful

Thanks

الله يخليك ويحفظك اخوية احمد

[as_radwan]

شكرا جزيلا للاستاذ همام.
علي موضوعه الماتع ونتمنا ان نري مزيد من المواضيع

[download2m]

لا نستطيع ان اقول اقل من جزاك الله كل الخير على هذا المجهود الرائع

[Monzer Osama]

أخي الكريم لدي سؤال لو سمحت , في الكود التالي:


Dim SOPLine1 As New taSopLineIvcInsert_ItemsTaSopLineIvcInsert
Dim SOPLine2 As New taSopLineIvcInsert_ItemsTaSopLineIvcInsert



قمنا بتعرف SOPline1,andSOPline2 فهل يجب علي أن أعرف متغير لكل سطر أريد أدخاله؟

اقوم بتصميم شاشة ووضعت DataGrid لكي تُكتب فيها اسماء الأصناف , وكما تعرف أن عدد الأصناف غير معروف , وأعتقدأنه ليس من المعقول أن أعرف لكل صنف سطر جديد, أعتقد أن هنالك شئ لم أفهمه , أرجو توضيحه لي لو تكرمت ,
كيف أقرأ المعلومات من DataGid وأمررها الى الدالة eConnectObject.eConnect_EntryPoint ?
وهل هنالك طريقة اسهل من الDataGrid?

شكرا لك عزيزي