الوصول إلى البيانات في المستندات على الخادم

ينطبق على
تنطبق المعلومات الموجودة في هذا الموضوع فقط على أنواع المشاريع وإصدارات Microsoft Office التالية: لمزيد من المعلومات، راجع الميزات المتوفرة بواسطة تطبيقات Office و نوع المشروع. نوع المشروع مشروعات على مستوى المستند إصدار Microsoft Office Excel 2007 و Excel 2010 Word 2007 و Word 2010

يمكنك البرمجة حيال البيانات في تخصيص على مستوى المستند بدون الحاجة إلى استخدام نموذج كائن Microsoft Office Word أو Microsoft Office Excel. وهذا يعني أن لك حق الوصول إلى البيانات المضمنة في مستند على خادم لم يكن يحتوي على Word أو Excel مثبتين. على سبيل المثال، التعليمات البرمجية على خادم (على سبيل المثال، في صفحة ASP.NET ) يمكنها تخصيص البيانات في المستند و إرسال المستند المخصص إلى المستخدم النهائي. عندما يفتح المستخدم النهائي المستند، التعليمات البرمجية الخاصة بربط المعلومات في تجميع الحل تقوم بربط البيانات المخصصة في المستند. و يعد ذلك ممكناً لأن البيانات في المستند منفصلة عن واجهة المستخدم . لمزيد من المعلومات، راجع البيانات المخزنة مؤقتًا في تخصيصات على مستوى المستند.

التخزين المؤقت للبيانات للاستخدام على خادم

لتخزين كائن بيانات في مستند تخزيناً مؤقتاً, علِّمه بالسمة CachedAttribute في وقت التصميم أو قم باستخدام الأسلوب StartCaching الخاص بالعنصر المضيف في وقت التشغيل. عند تخزين كائن بيانات مؤقتًا في المستند، يسلسل Visual Studio Tools لوقت تشغيل Office الكائن إلى سلسلة XML يتم تخزينها في المستند. يجب أن تفي الكائنات بمتطلبات معينة لكي تكون مؤهلة للتخزين المؤقت. لمزيد من المعلومات، راجع التخزين المؤقت للبيانات.

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

الوصول إلى البيانات في ذاكرة التخزين المؤقت

يمكنك الوصول إلى البيانات في ذاكرة التخزين المؤقت من تطبيقات خارج Office، على سبيل المثال من تطبيق وحدة تحكم أو تطبيق Windows Forms أو من صفحة ويب. التطبيق الذي يصل إلى بيانات ذاكرة التخزين المؤقت لابد أن يكون لديه ثقة كاملة; لا يمكن لتطبيق ويب الذي يحتوي على ثقة جزئية إدراج أو استرداد أو تغيير البيانات التي تم تخزينها مؤقتاً في مستند Office.

ذاكرة التخزين المؤقت للبيانات يتم الوصول إليها من خلال التسلسل الهرمي للمجموعات التي يمكن عرضها بواسطة الخاصية CachedData من الفئة ServerDocument :

• الخاصية CachedData تقوم بإرجاع Microsoft.VisualStudio.Tools.Applications.CachedData ، الذي يحتوي على كافة البيانات المخزنة مؤقتاً في التخصيص على مستوى المستند.

• كل Microsoft.VisualStudio.Tools.Applications.CachedData يحتوي على واحد أو أكثر من كائنات CachedDataHostItem . CachedDataHostItem يحتوي على كافة كائنات ذاكرة التخزين المؤقت للبيانات التي تم تعريفها داخل فئة واحدة

• كل CachedDataHostItem يحتوي على واحد أو أكثر من كائنات CachedDataItem . CachedDataItem يمثل كائنا للبيانات المخزنة مؤقتاً .

يوضح مثال التعليمات البرمجية التالي كيفية الوصول إلى سلسلة مخزنة مؤقتاً في الفئة Sheet1 من مشروع مصنف Excel . هذا المثال هو جزء من مثال أكبر تم توفيره لأسلوب ServerDocument.Save .

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

من أجل تعليمة برمجية توضح كيفية الوصول إلى البيانات في DataSet المخزنة مؤقتاً ، راجع كيفية القيام بما يلي: استرداد البيانات المخزنة مؤقتاً من مصنف على خادم.

تعديل البيانات في ذاكرة التخزين المؤقت

لتعديل كائنات البيانات المخزنة مؤقتاً ، تقوم عادةً بتنفيذ الخطوات التالية:

1. إلغاء تسلسل تمثيل XML للكائن المخزن مؤقتاً إلى مثيل جديد من الكائن. يمكنك الوصول إلى XML باستخدام خاصية Xml من CachedDataItem الذي يمثل كائن البيانات المخزنة مؤقتاً.

2. قم بإجراء التغييرات على تلك النسخة .

3. قم بإجراء تسلسل للكائن الذي تم تغييره إلى ذاكرة التخزين المؤقت للبيانات باستخدام إحدى الخيارات التالية:

   • إذا كنت ترغب في تسلسل التغييرات تلقائياً ، قم باستخدام أسلوب SerializeDataInstance . يستخدم هذا الأسلوب DiffGram تنسيق لسَلسَلة DataSet ، DataTable ، و يقوم بكتابة كائنات مجموعة البيانات في ذاكرة التخزين المؤقت للبيانات. تنسيق DiffGram يضمن أن التغييرات على ذاكرة التخزين المؤقت للبيانات في مستند دون اتصال يتم إرسالها إلى الخادم بشكل صحيح. لمزيد من المعلومات، راجع DiffGrams (ADO.NET).

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

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

تعديل بيانات بدون إلغاء تسلسل القيمة الحالية

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

يوضح مثال التعليمات البرمجية التالي كيفية تغيير قيمة سلسلة مخزنة مؤقتاً في فئة Sheet1 من مشروع مصنف Excel . هذا المثال هو جزء من مثال أكبر تم توفيره لأسلوب ServerDocument.Save .

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

If dataItem1 IsNot Nothing AndAlso _
    Type.GetType(dataItem1.DataType).Equals(GetType(String)) Then

    dataItem1.SerializeDataInstance("This is the new cached string value.")
    serverDocument1.Save()
End If

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

if (dataItem1 != null &&
    Type.GetType(dataItem1.DataType) == typeof(string))
{
    dataItem1.SerializeDataInstance("This is the new cached string value.");
    serverDocument1.Save();
}

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

تعديل قيم خاوية (Null) في التخزين المؤقت للبيانات

لا تقوم ذاكرة التخزين المؤقت للبيانات بتخزين الكائنات التي لها القيمة nullعند حفظ المستند أو إغلاقه. يحتوي هذا التحديد على نتائج عدة عند تعديل البيانات المخزنة مؤقتاً :

• إذا قمت بتعيين أي كائن في ذاكرة التخزين المؤقت للبيانات إلى قيمة null ، فإن كافة الكائنات في ذاكرة التخزين المؤقت للبيانات ستقوم بالتعيين تلقائياً إلى null عند فتح المستند و سيتم مسح ذاكرة التخزين المؤقت للبيانات بأكملها عندما يتم حفظ المستند و إغلاقه. أي، كافة الكائنات المخزنة مؤقتًا سيتم إزالتها من ذاكرة التخزين المؤقت للبيانات و ستكون مجموعة CachedData فارغة.

• في حالة بناء حل بكائنات null في ذاكرة التخزين المؤقت للبيانات وكنت تريد تهيئة هذه الكائنات عن طريق استخدام فئة ServerDocument قبل فتح المستند للمرة الأولى, يجب أن تتأكد من تهيئة كافة الكائنات الموجودة في ذاكرة التخزين المؤقت للبيانات. في حالة تهيئة بعض الكائنات ، كافة الكائنات سيتم تعيينها بالكامل إلى null عند فتح المستند و سيتم مسح ذاكرة التخزين المؤقت للبيانات عندما يتم حفظ المستند و إغلاقه.

الوصول إلى مجموعات البيانات المكتوبة في ذاكرة التخزين المؤقت

إذا كنت تريد الوصول إلى البيانات في مجموعة بيانات مكتوبة من حل Office و من تطبيق خارج Office كليهما، مثل تطبيق Windows Forms أو على مشروعASP.NET ، يجب عليك تعريف مجموعة البيانات المكتوبة في تجميع منفصل تتم الإشارة إليه في كلا المشروعين. إذا كنت ستضيف مجموعة البيانات المكتوبة إلى كل مشروع باستخدام معالج تكوين مصدر البيانات (Data Source Configuration Wizard) أو المصمم .NET، Framework سيعالج مجموعة البيانات المكتوبة في المشروعين كأنواع مختلفة. لمزيد من المعلومات حول إنشاء مجموعات البيانات مكتوبة راجع كيفية القيام بما يلي: إنشاء فئة البيانات المكتوب.

راجع أيضًا:

المهام

كيفية القيام بما يلي: استرداد البيانات المخزنة مؤقتاً من مصنف على خادم

كيفية القيام بما يلي: تغيير بيانات مخزنة مؤقـتًا في مصنف على خادم

كيفية القيام بما يلي: إدراج بيانات في مصنف على خادم

المبادئ

الوصول إلى البيانات في المستندات على الخادم

البيانات المخزنة مؤقتًا في تخصيصات على مستوى المستند

DiffGrams (ADO.NET)