استدعاء تعليمات برمجية في وظائف إضافية على مستوى التطبيق من حلول Office الأخرى

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

يمكن عرض الكائنات في الوظيفة الإضافية الخاصة بك لحلول أخرى بما في ذلك حلول Microsoft Office الأخرى. وهذا مفيد إذا كانت الوظيفة الإضافية الخاصة بك توفر خدمة تريد تمكين حلول أخرى من استخدامها. على سبيل المثال، إذا كان لديك وظيفة إضافية لـ Microsoft Office Excel تقوم بعملية حسابية على البيانات المالية من خدمة ويب ، يمكن لحلول أخرى تنفيذ هذه الحسابات بواسطة استدعاء الوظيفة الإضافية في Excel في وقت التشغيل.

هناك خطوتان رئيسيتان في هذه العملية:

• في الوظيفة الإضافية الخاصة بك ، اعرض كائناً إلى حلول أخرى.

• في حل آخر، قم بالوصول إلى الكائن المعروض بواسطة الوظيفة الإضافية الخاصة بك، و استدع أعضاء الكائن.

أنواع من الحلول التي يمكنها استدعاء التعليمات البرمجية في وظيفة إضافية

يمكنك عرض كائن في وظيفة إضافية إلى الأنواع التالية من الحلول :

• التعليمات البرمجية لـتطبيقات Visual Basicـ (VBA) في مستند يتم تحميله في نفس عملية التطبيق كالوظيفة الإضافية الخاصة بك.

• التخصيصات على مستوى المستند يتم تحميلها في نفس عملية التطبيق كالوظيفة الإضافية الخاصة بك.

• غيرها من الوظائف الإضافية التي تم إنشاؤها باستخدام قوالب مشروع Office فى اVisual Studio

• وظائف COM الإضافية (أي، الوظائف الإضافية التي تقوم بتنفيذ واجهة IDTExtensibility2 مباشرة).

• أي حل يتم تشغيله في عملية مختلفة عن الوظيفة الإضافية الخاصة بك (هذا النوع من الحلول يسمى أيضا عملاء خارج العملية ). و هذه تشمل التطبيقات التي تقوم بأتمتة تطبيق Office، مثل Windows Forms أو تطبيق وحدة التحكم، والوظائف الإضافية التي يتم تحميلها في عملية مختلفة.

عرض الكائنات إلى حلول أخرى

لعرض كائن في الوظيفة الإضافية الخاصة بك إلى حلول أخرى ، نفذ الخطوات التالية في الوظيفة الإضافية الخاصة بك :

1. قم بتعريف فئة يمكن عرضها إلى حلول Office الأخرى. كحد أدنى، هذه الفئة يجب أن تكون عامة, يجب أن يكون لديها السمة ComVisibleAttribute معينة إلى true ، و يجب أن تعرض واجهة IDispatch .

2. تجاوز إسلوبRequestComAddInAutomationService في فئة ThisAddIn. قم بإرجاع الكائن الذي تريد عرضه إلى حلول أخرى.

يوضح مثال التعليمات البرمجية التالي تجاوز RequestComAddInAutomationService يفترض هذا المثال أنك قمت بتعريف فئة باسم AddInUtilities تريد عرضها إلى حلول أخرى. لرؤية تلك التعليمات البرمجية في سياق إرشادات تفصيلية أكبر، راجع الإرشادات التفصيلية: استدعاء تعليمات برمجية في وظيفة إضافية على مستوى التطبيق من VBA.

Private utilities As AddInUtilities

Protected Overrides Function RequestComAddInAutomationService() As Object
    If utilities Is Nothing Then
        utilities = New AddInUtilities()
    End If
    Return utilities
End Function

private AddInUtilities utilities;

protected override object RequestComAddInAutomationService()
{
    if (utilities == null)
        utilities = new AddInUtilities();

    return utilities;
}

عند تحميل الوظيفة الإضافية الخاصة بك،يستدعى Visual Studio Tools لوقت تشغيل Office RequestComAddInAutomationService . The runtime assigns the returned object to the Object() property of a COMAddIn object that represents your add-in. COMAddInمعالج حدث من الاختيار "إضافة التحكم نص منسق" صندوق يفتح في. محرر تعليمات برمجية

متطلبات عرض واجهة IDispatch في الكائن المعروض تختلف لعملاء VBA عمن ليسوا بعملاء VBA. وهناك أيضا متطلبات إضافية لعرض الكائن الخاص بك لعملاء خارج العملية.

عرض حلول VBA الى IDispatch

هناك عدة طرق يمكن من خلالها للكائن فى الوظيفة الإضافية عرض واجهة IDispatch إلى حلول VBA. عادة ، فإن الطريقة الموصى بها لتنفيذ الخطوات التالية :

1. تعريف واجهة تصرح بالأساليب التي تريد عرضها إلى حلول أخرى.

2. قم بتطبيق االسمة ComVisibleAttribute لهذه الواجهة ، وتعيين هذه السمة لـ true.

3. قم بتعديل الفئة الخاصة بك لتطبيق هذه الواجهة.

4. عند قيام مستخدم بالنقر فوق خانة الاختيار "إضافة زر" تشغيل "شريط"، رقم هو أسلوب إضافة ClassInterfaceAttributeإلى المحدد الحالي في مستند إذا خانة الاختيار هو محددة، أو قم بإزالة Noneإذا خانة الاختيار هو مسح.ClassInterfaceType

يوضح مثال التعليمات البرمجية التالي كيفية تعريف فئة تعرض الواجهة IDispatch. لرؤية تلك التعليمات البرمجية في سياق إرشادات تفصيلية أكبر، راجع الإرشادات التفصيلية: استدعاء تعليمات برمجية في وظيفة إضافية على مستوى التطبيق من VBA.

<ComVisible(True)> _
Public Interface IAddInUtilities
    Sub ImportData()
End Interface

<ComVisible(True)> _
<ClassInterface(ClassInterfaceType.None)> _
Public Class AddInUtilities
    Implements IAddInUtilities

    ' This method tries to write a string to cell A1 in the active worksheet.
    Public Sub ImportData() Implements IAddInUtilities.ImportData

        Dim activeWorksheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

        If activeWorksheet IsNot Nothing Then
            Dim range1 As Excel.Range = activeWorksheet.Range("A1")
            range1.Value2 = "This is my data"
        End If
    End Sub
End Class

[ComVisible(true)]
public interface IAddInUtilities
{
    void ImportData();
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class AddInUtilities : IAddInUtilities
{
    // This method tries to write a string to cell A1 in the active worksheet.
    public void ImportData()
    {
        Excel.Worksheet activeWorksheet = Globals.ThisAddIn.Application.ActiveSheet as Excel.Worksheet;

        if (activeWorksheet != null)
        {
            Excel.Range range1 = activeWorksheet.get_Range("A1", System.Type.Missing);
            range1.Value2 = "This is my data";
        }
    }
}

عند تنفيذ الخطوات التالية، تعليمات VBA البرمجية يمكنها فقط استدعاء الأساليب التي تقوم بالتصريح بها في الواجهة. تعليمات VBA البرمجية لا يمكنها استدعاء أي أساليب أخرى في الفئات، بما في ذلك الأساليب التي تحصل عليها الفئة الخاصة بك من الفئات الأساسية مثل Object.

You can alternatively expose the IDispatch interface by applying the ClassInterfaceAttribute attribute to the class, and by setting this attribute to the AutoDispatch or AutoDual value of the ClassInterfaceType enumeration. في حالة القيام بذلك، لا يلزم أن تقوم بالتصريح بالأساليب الموجودة في واجهة منفصلة. ومع ذلك ، يمكن لتعليمات VBA البرمجية استدعاء أي أساليب عامة وغير ثابتة في فئتك، بما في ذلك الأساليب التي تم الحصول عليها من الفئات الأساسية مثل Object.

عرض IDispatch لحلول Non-VBA

إذا كنت ترغب في عرض كائن في الوظيفة الإضافية الخاصة بك إلى حلول ليست VBA مثل الوظائف الإضافية الأخرى، يجب تنفيذ الخطوات التالية للتأكد من أن الكائن الخاص بك يعرض واجهة IDispatch:

1. تعريف واجهة تصرح بالأساليب التي تريد عرضها إلى حلول أخرى. الحلول الأخرى يمكنها فقط استدعاء الأساليب التي تقوم بالتصريح بها في هذه الواجهة.

2. قم بتطبيق االسمة ComVisibleAttribute لهذه الواجهة ، وتعيين هذه السمة لـ true.

3. قم بتعديل الفئة الخاصة بك لتطبيق هذه الواجهة.

4. عند قيام مستخدم بالنقر فوق خانة الاختيار "إضافة زر" تشغيل "شريط"، رقم هو أسلوب إضافة ClassInterfaceAttributeإلى المحدد الحالي في مستند إذا خانة الاختيار هو محددة، أو قم بإزالة Noneإذا خانة الاختيار هو مسح.ClassInterfaceType

5. قم ببناء مشروع الوظيفة الإضافية الخاص بك مع الخيار تسجيل لتوافق COM. لمزيد من المعلومات، راجع كيفية القيام بما يلي: تسجيل المكوّن لـ توافق COM.

تجنب حالة التعارض في العملاء خارج العملية

إذا كنت ترغب في عرض كائن في الوظيفة الإضافية إلى عملاء خارج العملية، اتبع الخطوات المذكورة أعلاه لعرض واجهة IDispatch إلى الحلول ليست VBA. ومع ذلك، لضمان أن العملاء خارج العملية يمكنهم استدعاء كائن الوظيفة الإضافية المعروض، الفئة الخاصة بك يجب أن تشتق أيضا من StandardOleMarshalObject.

و إلا ، فمحاولات الحصول على مثيل من الكائن المعروض الخاص بك فى عميل خارج العملية قد تفشل بشكل غير متوقع. وهذا لأن كل الاستدعاءات لنموذج الكائن لتطبيق Office يجب عملها على مؤشر الترابط واجهة المستخدم الرئيسي، ولكنها الاستدعاءات من عميل خارج عملية للكائن الخاص بك ستصل على مؤشر ترابط RPC (استدعاء إجراء عن بُعد). آلية تنظيم و إرسال COM في .NET Framework لن تبدّل مؤشرات الترابط، بل ستحاول بدلاً من ذلك تنظيم و إرسال استدعاء الكائن على مؤشر ترابط RPC الوارد بدلاً من مؤشر ترابط UI الرئيسي.

إذا كان الكائن الخاص بك مثيلاً من فئة مشتقة من StandardOleMarshalObject، و الاستدعاءات الواردة إلى الكائن يتم تنظيمها و إرسالها تلقائياً إلى مؤشر الترابط حيث تم إنشاء الكائن المعروض، الذي سيكون مؤشر ترابط UI الرئيسي للتطبيق المضيف.

للحصول على معلومات حول حول استخدام مؤشرات الترابط في حلول Office، راجع دعم مؤشر الترابط في Office.

الوصول إلى كائنات من حلول أخرى

لاستدعاء الكائن المعروض في الوظيفة الإضافية الخاصة بك، نفذ الخطوات التالية في حل العميل :

1. COMAddInيجب أن تكون مثبتة تشغيل كل كمبيوتر يقوم بتشغيل الحلول التي تم إنشاؤها باستخدام Microsoft المكتب أدوات المطور في . قم بتثبيت the‏‫NET Framework 3.5. أو COMAddIns.Application

2. قم بالوصول إلى خاصية Object() من الكائن COMAddIn. هذه الخاصية تقوم بإرجاع الكائن المعروض من الوظيفة الإضافية.

3. قم باستدعاء أعضاء الكائن المعروض.

طريقة استخدام قيمة الإرجاع للخاصية COMAddInObject() تختلف لعملاء VBA عن العملاء غير VBA. للعملاء خارج العملية ، من الضروري إضافة تعليمات برمجية لتجنب حالة تعارض ممكنة.

الوصول إلى الكائنات من حلول VBA

إلى ينزّل 3.5 إطار عمل.NET، راجع http://انتقال.microsoft.com/fwlink/?LinkID=96339 . إلى ينزّل ImportData، راجع http://انتقال.microsoft.com/fwlink/?LinkId=178957 . لرؤية تلك التعليمات البرمجية في سياق إرشادات تفصيلية أكبر، راجع الإرشادات التفصيلية: استدعاء تعليمات برمجية في وظيفة إضافية على مستوى التطبيق من VBA.

Sub CallVSTOMethod()
    Dim addIn As COMAddIn
    Dim automationObject As Object
    Set addIn = Application.COMAddIns("ExcelImportData")
    Set automationObject = addIn.Object
    automationObject.ImportData
End Sub

الوصول إلى الكائنات من حلول غير VBA

في حل غير VBA، يجب تحويل قيمة الخاصية COMAddInObject() إلى الواجهة التى تطبقها ثم يمكنك استدعاء الأساليب المعروضة على واجهة الكائن. يوضح مثال التعليمات البرمجية التالي كيفية استدعاء أسلوب ImportData من وظيفة إضافية مختلفة.

Dim addIn As Office.COMAddIn = _
    Globals.ThisAddIn.Application.COMAddIns.Item("ExcelImportData")
Dim utilities As ExcelImportData.IAddInUtilities = _
    TryCast(addIn.Object, ExcelImportData.IAddInUtilities)
utilities.ImportData()

object addInName = "ExcelImportData";
Office.COMAddIn addIn = Globals.ThisAddIn.Application.COMAddIns.Item(
    ref addInName);

ExcelImportData.IAddInUtilities utilities = 
    (ExcelImportData.IAddInUtilities)addIn.Object;
utilities.ImportData();

في هذا المثال، إذا حاولت بدلاً من ذلك تحويل قيمة الخاصية COMAddInObject() إلى الفئة التي تطبق الواجهة IAddInUtilities في الوظيفة الإضافية الأصلية، ستطرح التعليمة البرمجية InvalidCastException.

الوصول إلى كائنات من عملاء خارج العملية

للوصول إلى كائن معروض فى وظيفة إضافية من عميل خارج العملية ، اتبع نفس الخطوات المذكورة أعلاه للعملاء غير VBA. ومع ذلك، إذا كان العميل خارج العملية يحاول الاستدعاء في وظيفة الإضافية بعد وقت قليل من تحميل تطبيق Office, يجب أن يعالج العميل الحالة حيث تقوم خاصية COMAddInObject() بإرجاع null. في هذه الحالة، يجب على العميل إعادة تجربة العملية بعد قليل من الانتظار (على سبيل المثال، 100 مللي ثانية).

عند بدء تشغيل تطبيق Office، يعرض التطبيق كائنات COMAddIn للعملاء قبل تحميل الوظائف الإضافية المناظرة لهذه الكائنات بواسطة التطبيق. وهذا يعني أن العميل خارج العملية الذى يحاول الوصول إلى كائن COMAddIn بعد بدء تشغيل التطبيق، قد يقوم باسترداد الكائن قبل تحميل الخاصية الاضافية. في هذه الحالة، الخاصية COMAddInObject() ستقوم بإرجاع null, لأن الوظيفة الإضافية غير متوفرة لإرجاع الكائن المطلوب

راجع أيضًا:

المهام

الإرشادات التفصيلية: استدعاء تعليمات برمجية في وظيفة إضافية على مستوى التطبيق من VBA

كيفية القيام بما يلي: إنشاء مشاريع Office في Visual Studio

المبادئ

تخصيص ميزات UI باستخدام الواجهات القابلة للتوسعة

بنية الوظائف الإضافية على مستوى التطبيق

موارد أخرى

برمجة وظائف إضافية على مستوى التطبيق

تطوير حلول Office