كيفية القيام بما يلي: إنشاء الوظائف الإضافية التي تقوم بإرجاع UI

يوضح هذا المثال كيفية إنشاء الوظائف الاضافية لإرجاع Windows Presentation Foundation (WPF)واجهة المستخدم (UI) إلى مضيف تطبيق مستقل WPF.

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

المتطلبات الأساسية

يوضح هذا المثال ملحقات WPF للوظيفة الاضافية .NET Framework التى تتيح هذا السيناريو ويفترض ما يلي:

• معرفة طراز الوظيفة الاضافية .NET Framework بما في ذلك pipeline ، الوظيفة الاضافية ، وتطوير المضيف. إذا كنت غير معتاد على هذه المفاهيم ، راجع الوظائف الإضافية ووحدات الامتداد. للحصول على برنامج تعليمي يوضح تطبيق pipeline والوظيفة الاضافية ، والتطبيق المضيف ، راجع الإرشادات التفصيلية: إنشاء تطبيقات القابلة للتوسيع.

• معرفة الملحقات WPF لطراز الوظيفة الاضافية .NET Framework الذي يمكن العثور عليه هنا: نظرة عامة على الوظائف الإضافية لـ WPF.

مثال

لإنشاء وظيفة اضافية تعمل على ارجاع WPFواجهة المستخدم يتطلب رمز خاص من أجل كل قطعة pipeline والوظيفة الاضافية ، التطبيق المضيف.

تطبيق اتفاق قطعة pipeline

يجب تعريف أسلوب بواسطة اتفاق لارجاع واجهة المستخدم ،ويجب أن تكون قيمة الإرجاع الخاصة بها من النوع INativeHandleContract. هذا موضّح بواسطة الأسلوب GetAddInUI الخاص باتفاق IWPFAddInContract في التعليمات البرمجية التالية.

using System.AddIn.Contract; // IContract, INativeHandleContract
using System.AddIn.Pipeline; // AddInContractAttribute

namespace Contracts
{
    /// <summary>
    /// Defines the services that an add-in will provide to a host application
    /// </summary>
    [AddInContract]
    public interface IWPFAddInContract : IContract
    {
        // Return a UI to the host application
        INativeHandleContract GetAddInUI();
    }
}

تطبيق الوظيفة الاضافية عرض مقطع pipeline

لأن الوظيفة الاضافية تعمل على تنفيذ واجهات المستخدم فهى تتوفر كـالفئات الفرعية للفئة FrameworkElement ، أسلوب الوظيفة الاضافية طريقة العرض الذي يرتبط بـ IWPFAddInView.GetAddInUI يجب أن يقوم بإرجاع قيمة من النوع FrameworkElement. تُظهر التعليمات البرمجية التالية الوظيفة الإضافية عرض العقد مُطبق كواجهة.

using System.AddIn.Pipeline; // AddInBaseAttribute
using System.Windows; // FrameworkElement

namespace AddInViews
{
    /// <summary>
    /// Defines the add-in's view of the contract
    /// </summary>
    [AddInBase]
    public interface IWPFAddInView
    {
        // The add-in's implementation of this method will return
        // a UI type that directly or indirectly derives from 
        // FrameworkElement.
        FrameworkElement GetAddInUI();
    }
}

تطبيق الوظيفة الاضافية مكيف مقطع pipeline

يقوم أسلوب العقد بإرجاع INativeHandleContract, ولكن تقوم الوظيفة الاضافية بإرجاع FrameworkElement (كما تم تحديده بواسطة طريقة عرض الوظيفة الاضافية). وبالتالي، يجب أن يتم تحويل FrameworkElement إلى INativeHandleContract قبل عبور حاجز العزل. يتم إجراء هذا العمل بواسطة محول الوظيفة الاضافية عن طريق استدعاء ViewToContractAdapter ، كما هو موضح في التعليمات البرمجية التالية.

using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
using System.Windows; // FrameworkElement

using AddInViews; // IWPFAddInView
using Contracts; // IWPFAddInContract

namespace AddInSideAdapters
{
    /// <summary>
    /// Adapts the add-in's view of the contract to the add-in contract
    /// </summary>
    [AddInAdapter]
    public class WPFAddIn_ViewToContractAddInSideAdapter : ContractBase, IWPFAddInContract
    {
        IWPFAddInView wpfAddInView;

        public WPFAddIn_ViewToContractAddInSideAdapter(IWPFAddInView wpfAddInView)
        {
            // Adapt the add-in view of the contract (IWPFAddInView) 
            // to the contract (IWPFAddInContract)
            this.wpfAddInView = wpfAddInView;
        }

        public INativeHandleContract GetAddInUI()
        {
            // Convert the FrameworkElement from the add-in to an INativeHandleContract 
            // that will be passed across the isolation boundary to the host application.
            FrameworkElement fe = this.wpfAddInView.GetAddInUI();
            INativeHandleContract inhc = FrameworkElementAdapters.ViewToContractAdapter(fe);
            return inhc;
        }
    }
}

تطبيق عرض مقطع pipeline المضيف

لأن التطبيق المضيف سيقوم بعرض FrameworkElement ، الأسلوب في طريقة عرض المضيف المرتبط بـ IWPFAddInHostView.GetAddInUI يجب أن يقوم بإرجاع قيمة من النوع FrameworkElement. تُظهر التعليمات البرمجية التالية الوظيفة الإضافية عرض العقد مُطبق كواجهة.

using System.Windows; // FrameworkElement

namespace HostViews
{
    /// <summary>
    /// Defines the host's view of the add-in
    /// </summary>
    public interface IWPFAddInHostView
    {
        // The view returns as a class that directly or indirectly derives from 
        // FrameworkElement and can subsequently be displayed by the host 
        // application by embedding it as content or sub-content of a UI that is 
        // implemented by the host application.
        FrameworkElement GetAddInUI();
    }
}

تطبيق الوظيفة الاضافية مكيف جانب مقطع pipeline

يرجع أسلوب العقد INativeHandleContract ،ولكن يتوقع التطبيق المضيف FrameworkElement (كما تم تحديده من قبل طريقة عرض المضيف). وبالتالي، يجب أن يتم تحويل INativeHandleContract إلى FrameworkElement بعد عبور حاجز العزل. يتم إجراء هذا العمل بواسطة محول الجانب الخاص بالمضيف عن طريق استدعاء ContractToViewAdapter ، كما هو موضح في التعليمات البرمجية التالية.

using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
using System.Windows; // FrameworkElement

using Contracts; // IWPFAddInContract
using HostViews; // IWPFAddInHostView

namespace HostSideAdapters
{
    /// <summary>
    /// Adapts the add-in contract to the host's view of the add-in
    /// </summary>
    [HostAdapter]
    public class WPFAddIn_ContractToViewHostSideAdapter : IWPFAddInHostView
    {
        IWPFAddInContract wpfAddInContract;
        ContractHandle wpfAddInContractHandle;

        public WPFAddIn_ContractToViewHostSideAdapter(IWPFAddInContract wpfAddInContract)
        {
            // Adapt the contract (IWPFAddInContract) to the host application's
            // view of the contract (IWPFAddInHostView)
            this.wpfAddInContract = wpfAddInContract;

            // Prevent the reference to the contract from being released while the
            // host application uses the add-in
            this.wpfAddInContractHandle = new ContractHandle(wpfAddInContract);
        }

        public FrameworkElement GetAddInUI()
        {
            // Convert the INativeHandleContract that was passed from the add-in side
            // of the isolation boundary to a FrameworkElement
            INativeHandleContract inhc = this.wpfAddInContract.GetAddInUI();
            FrameworkElement fe = FrameworkElementAdapters.ContractToViewAdapter(inhc);
            return fe;
        }
    }
}

تطبيق الوظيفة الاضافية

مع انشاء الوظيفة الاضافية محول الجانب و الوظيفة الاضافية طريقة العرض يجب أن تطبق الوظيفة الاضافية ( WPFAddIn1.AddIn) الأسلوب IWPFAddInView.GetAddInUI لارجاع كائن FrameworkElement (UserControl في هذا المثال). تطبيق UserControl ، AddInUI ،موضح بواسطة التعليمات البرمجية التالية.

    <UserControl
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="WPFAddIn1.AddInUI">

    <StackPanel>
        <Button Click="clickMeButton_Click" Content="Click Me!" />
    </StackPanel>

</UserControl>

using System.Windows; // MessageBox, RoutedEventArgs
using System.Windows.Controls; // UserControl

namespace WPFAddIn1
{
    public partial class AddInUI : UserControl
    {
        public AddInUI()
        {
            InitializeComponent();
        }

        void clickMeButton_Click(object sender, RoutedEventArgs e)
        {
            MessageBox.Show("Hello from WPFAddIn1");
        }
    }
}

التطبيق IWPFAddInView.GetAddInUI بواسطة الوظيفة الإضافية ببساطة يحتاج لإرجاع مثيل جديد من AddInUI ، كما هو موضح فى التعليمات البرمجية التالية.

using System.AddIn; // AddInAttribute
using System.Windows; // FrameworkElement

using AddInViews; // IWPFAddInView

namespace WPFAddIn1
{
    /// <summary>
    /// Add-In implementation
    /// </summary>
    [AddIn("WPF Add-In 1")]
    public class WPFAddIn : IWPFAddInView
    {
        public FrameworkElement GetAddInUI()
        {
            // Return add-in UI
            return new AddInUI();
        }
    }
}

تنفيذ التطبيق المضيف

مع انشاء محول جانب المضيف وعرض المضيف، يمكن للتطبيق المضيف استخدام طراز الوظيفة الاضافية .NET Framework لفتح ال pipeline، والحصول على طريقة عرض المضيف الخاص بالوظيفة الاضافية واستدعاء الأسلوب IWPFAddInHostView.GetAddInUI. تظهر هذه الخطوات فى التعليمات البرمجية التالية.

// Get add-in pipeline folder (the folder in which this application was launched from)
string appPath = Environment.CurrentDirectory;

// Rebuild visual add-in pipeline
string[] warnings = AddInStore.Rebuild(appPath);
if (warnings.Length > 0)
{
    string msg = "Could not rebuild pipeline:";
    foreach (string warning in warnings) msg += "\n" + warning;
    MessageBox.Show(msg);
    return;
}

// Activate add-in with Internet zone security isolation
Collection<AddInToken> addInTokens = AddInStore.FindAddIns(typeof(IWPFAddInHostView), appPath);
AddInToken wpfAddInToken = addInTokens[0];
this.wpfAddInHostView = wpfAddInToken.Activate<IWPFAddInHostView>(AddInSecurityLevel.Internet);

// Get and display add-in UI
FrameworkElement addInUI = this.wpfAddInHostView.GetAddInUI();
this.addInUIHostGrid.Children.Add(addInUI);

راجع أيضًا:

المبادئ

الوظائف الإضافية ووحدات الامتداد

نظرة عامة على الوظائف الإضافية لـ WPF