Практическое руководство. Создание надстройки, являющейся пользовательским интерфейсом

Статья
08/11/2011

В этом примере показано, как создать надстройку, представляющую собой user interface (UI) Windows Presentation Foundation (WPF), размещенное автономным приложением WPF.

Надстройка — это UI, представляющий собой пользовательский элемент управления WPF. Содержимое пользовательского элемента управления составляет одна кнопка, при нажатии которой отображается окно сообщения. Автономное приложение WPF размещает UI надстройки как содержимое главного окна приложения.

Предварительные требования

В этом примере акцентируются расширения WPF для модели надстройки .NET Framework, поддерживающей этот скрипт, и предполагается соблюдение следующих условий:

Знание модели надстройки .NET Framework, включая конвейер, надстройку и разработку ведущего приложения. Для ознакомления с этими понятиями см. раздел Надстройки и расширения среды. Руководство, в котором демонстрируется реализация конвейера, надстройки и ведущего приложения, см. в разделе Пошаговое руководство. Создание расширяемого приложения.
Знание расширений WPF для модели надстройки .NET Framework, которые можно найти в разделе Общие сведения о надстройках WPF.

Пример

Чтобы создать надстройку, представляющую собой UI WPF, требуется специальный код для каждого сегмента конвейера, надстройки и ведущего приложения.

Реализация сегмента конвейера «контракт»

Если надстройка представляет собой UI, контракт для надстройки должен реализовать INativeHandleContract. В примере IWPFAddInContract реализует INativeHandleContract (как показано в следующем коде).


Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInContractAttribute

Namespace Contracts
    ''' <summary>
    ''' Defines the services that an add-in will provide to a host application.
    ''' In this case, the add-in is a UI.
    ''' </summary>
    <AddInContract>
    Public Interface IWPFAddInContract
        Inherits INativeHandleContract
        Inherits IContract
    End Interface
End Namespace

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

namespace Contracts
{
    /// <summary>
    /// Defines the services that an add-in will provide to a host application.
    /// In this case, the add-in is a UI.
    /// </summary>
    [AddInContract]
    public interface IWPFAddInContract : INativeHandleContract {}
}

Реализация сегмента конвейера «представление надстройки»

Поскольку надстройка реализована как подкласс типа FrameworkElement, представление надстройки также должно быть подклассом FrameworkElement. В следующем коде показано представление надстройки контракта, реализованное как класс WPFAddInView.


Imports System.AddIn.Pipeline ' AddInBaseAttribute
Imports System.Windows.Controls ' UserControl

Namespace AddInViews
    ''' <summary>
    ''' Defines the add-in's view of the contract.
    ''' </summary>
    <AddInBase>
    Public Class WPFAddInView
        Inherits UserControl
    End Class
End Namespace

using System.AddIn.Pipeline; // AddInBaseAttribute
using System.Windows.Controls; // UserControl

namespace AddInViews
{
    /// <summary>
    /// Defines the add-in's view of the contract.
    /// </summary>
    [AddInBase]
    public class WPFAddInView : UserControl { }
}

В данном случае представление надстройки является производным от UserControl. Следовательно, UI надстройки должен также быть производным от UserControl.

Реализация сегмента конвейера «адаптер на стороне надстройки»

Контракт представляет собой INativeHandleContract, а надстройка — FrameworkElement (как указано в сегменте конвейера «представление надстройки»). Таким образом, перед пересечением границы изоляции FrameworkElement необходимо преобразовать в INativeHandleContract. Эту работу выполняет адаптер на стороне надстройки, вызывая ViewToContractAdapter (как показано в следующем коде).


Imports System ' IntPtr
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
Imports System.Security.Permissions

Imports AddInViews ' WPFAddInView
Imports 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
        Inherits ContractBase
        Implements IWPFAddInContract

        Private wpfAddInView As WPFAddInView

        Public Sub New(ByVal wpfAddInView As WPFAddInView)
            ' Adapt the add-in view of the contract (WPFAddInView) 
            ' to the contract (IWPFAddInContract)
            Me.wpfAddInView = wpfAddInView
        End Sub

        ''' <summary>
        ''' ContractBase.QueryContract must be overridden to:
        ''' * Safely return a window handle for an add-in UI to the host 
        '''   application's application.
        ''' * Enable tabbing between host application UI and add-in UI, in the
        '''   "add-in is a UI" scenario.
        ''' </summary>
        Public Overrides Function QueryContract(ByVal contractIdentifier As String) As IContract
            If contractIdentifier.Equals(GetType(INativeHandleContract).AssemblyQualifiedName) Then
                Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView)
            End If

            Return MyBase.QueryContract(contractIdentifier)
        End Function

        ''' <summary>
        ''' GetHandle is called by the WPF add-in model from the host application's 
        ''' application domain to to get the window handle for an add-in UI from the 
        ''' add-in's application domain. GetHandle is called if a window handle isn't 
        ''' returned by other means ie overriding ContractBase.QueryContract, 
        ''' as shown above.
        ''' NOTE: This method requires UnmanagedCodePermission to be called 
        '''       (full-trust by default), to prevent illegal window handle
        '''       access in partially trusted scenarios. If the add-in could
        '''       run in a partially trusted application domain 
        '''       (eg AddInSecurityLevel.Internet), you can safely return a window
        '''       handle by overriding ContractBase.QueryContract, as shown above.
        ''' </summary>
        <SecurityPermissionAttribute(SecurityAction.Demand, Flags:=SecurityPermissionFlag.UnmanagedCode)>
        Public Function GetHandle() As IntPtr Implements INativeHandleContract.GetHandle
            Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView).GetHandle()
        End Function

    End Class
End Namespace

using System; // IntPtr
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
using System.Security.Permissions;

using AddInViews; // WPFAddInView
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
    {
        WPFAddInView wpfAddInView;

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

        /// <summary>
        /// ContractBase.QueryContract must be overridden to:
        /// * Safely return a window handle for an add-in UI to the host 
        ///   application's application.
        /// * Enable tabbing between host application UI and add-in UI, in the
        ///   "add-in is a UI" scenario.
        /// </summary>
        public override IContract QueryContract(string contractIdentifier)
        {
            if (contractIdentifier.Equals(typeof(INativeHandleContract).AssemblyQualifiedName))
            {
                return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView);
            }

            return base.QueryContract(contractIdentifier);
        }

        /// <summary>
        /// GetHandle is called by the WPF add-in model from the host application's 
        /// application domain to to get the window handle for an add-in UI from the 
        /// add-in's application domain. GetHandle is called if a window handle isn't 
        /// returned by other means ie overriding ContractBase.QueryContract, 
        /// as shown above.
        /// NOTE: This method requires UnmanagedCodePermission to be called 
        ///       (full-trust by default), to prevent illegal window handle
        ///       access in partially trusted scenarios. If the add-in could
        ///       run in a partially trusted application domain 
        ///       (eg AddInSecurityLevel.Internet), you can safely return a window
        ///       handle by overriding ContractBase.QueryContract, as shown above.
        /// </summary>
        [SecurityPermissionAttribute(SecurityAction.Demand, Flags = SecurityPermissionFlag.UnmanagedCode)]
        public IntPtr GetHandle()
        {
            return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView).GetHandle();
        }
    }
}

В такой модели надстройки, где надстройка возвращает UI (см. раздел Практическое руководство. Создание надстройки, возвращающей пользовательский интерфейс), адаптер надстройки преобразовывал объект FrameworkElement в INativeHandleContract, вызывая метод ViewToContractAdapter. Метод ViewToContractAdapter также необходимо вызвать в этой модели, хотя сначала нужно реализовать метод, с помощью которого записывается код для вызова метода. Это делается путем переопределения QueryContract и реализации кода, вызывающего ViewToContractAdapter, если код, вызывающий QueryContract, ожидает INativeHandleContract. В этом случае вызывающая сторона будет адаптером на стороне узла, который рассматривается в следующем подразделе.

Примечание
Кроме того, необходимо переопределить QueryContract в этой модели, чтобы разрешить переходы между UI ведущего приложения и UI надстройки.Дополнительные сведения см. в подразделе "Ограничения надстройки WPF" раздела Общие сведения о надстройках WPF.

Кроме того, необходимо переопределить QueryContract в этой модели, чтобы разрешить переходы между UI ведущего приложения и UI надстройки.Дополнительные сведения см. в подразделе "Ограничения надстройки WPF" раздела Общие сведения о надстройках WPF.

Поскольку адаптер со стороны надстройки реализует интерфейс, который является производным от INativeHandleContract, необходимо также реализовать GetHandle, несмотря на то, что это игнорируется при переопределении QueryContract.

Реализация сегмента конвейера «хост-представление»

В этой модели ведущее приложение обычно ожидает, что хост-представление окажется подклассом FrameworkElement. Адаптер на стороне узла должен преобразовать INativeHandleContract в FrameworkElement, после того как INativeHandleContract пересечет границу изоляции. Поскольку метод не вызывается ведущим приложением для получения FrameworkElement, хост-представление должно «возвращать» FrameworkElement, включая его в себя. Таким образом, хост-представление должно быть производным от подкласса элемента FrameworkElement, который может содержать другие UIs, например UserControl. В следующем коде показано хост-представление контракта, реализованного в качестве класса WPFAddInHostView.


Imports System.Windows.Controls ' UserControl

Namespace HostViews
    ''' <summary>
    ''' Defines the host's view of the add-in
    ''' </summary>
    Public Class WPFAddInHostView
        Inherits UserControl
    End Class
End Namespace

using System.Windows.Controls; // UserControl

namespace HostViews
{
    /// <summary>
    /// Defines the host's view of the add-in
    /// </summary>
    public class WPFAddInHostView : UserControl { }
}

Реализация сегмента конвейера «адаптер на стороне сайта»

Контракт представляет собой INativeHandleContract, а ведущее приложение ожидает UserControl (как указано в хост-представлении). Таким образом, INativeHandleContract необходимо преобразовать в FrameworkElement после пересечения границы изоляции, но перед заданием в качестве содержимого хост-представления (которое является производным от UserControl).

Эту работу выполняет адаптер на стороне узла (как показано в следующем коде).


Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
Imports System.Windows ' FrameworkElement

Imports Contracts ' IWPFAddInContract
Imports HostViews ' WPFAddInHostView

Namespace HostSideAdapters
    ''' <summary>
    ''' Adapts the add-in contract to the host's view of the add-in
    ''' </summary>
    <HostAdapter>
    Public Class WPFAddIn_ContractToViewHostSideAdapter
        Inherits WPFAddInHostView
        Private wpfAddInContract As IWPFAddInContract
        Private wpfAddInContractHandle As ContractHandle

        Public Sub New(ByVal wpfAddInContract As IWPFAddInContract)
            ' Adapt the contract (IWPFAddInContract) to the host application's
            ' view of the contract (WPFAddInHostView)
            Me.wpfAddInContract = wpfAddInContract

            ' Prevent the reference to the contract from being released while the
            ' host application uses the add-in
            Me.wpfAddInContractHandle = New ContractHandle(wpfAddInContract)

            ' Convert the INativeHandleContract for the add-in UI that was passed 
            ' from the add-in side of the isolation boundary to a FrameworkElement
            Dim aqn As String = GetType(INativeHandleContract).AssemblyQualifiedName
            Dim inhc As INativeHandleContract = CType(wpfAddInContract.QueryContract(aqn), INativeHandleContract)
            Dim fe As FrameworkElement = CType(FrameworkElementAdapters.ContractToViewAdapter(inhc), FrameworkElement)

            ' Add FrameworkElement (which displays the UI provided by the add-in) as
            ' content of the view (a UserControl)
            Me.Content = fe
        End Sub
    End Class
End Namespace

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

using Contracts; // IWPFAddInContract
using HostViews; // WPFAddInHostView

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

        public WPFAddIn_ContractToViewHostSideAdapter(IWPFAddInContract wpfAddInContract)
        {
            // Adapt the contract (IWPFAddInContract) to the host application's
            // view of the contract (WPFAddInHostView)
            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);

            // Convert the INativeHandleContract for the add-in UI that was passed 
            // from the add-in side of the isolation boundary to a FrameworkElement
            string aqn = typeof(INativeHandleContract).AssemblyQualifiedName;
            INativeHandleContract inhc = (INativeHandleContract)wpfAddInContract.QueryContract(aqn);
            FrameworkElement fe = (FrameworkElement)FrameworkElementAdapters.ContractToViewAdapter(inhc);

            // Add FrameworkElement (which displays the UI provided by the add-in) as
            // content of the view (a UserControl)
            this.Content = fe;
        }
    }
}

Как видите, адаптер на стороне узла получает INativeHandleContract посредством вызова метода QueryContract адаптера на стороне надстройки (это точка, в которой INativeHandleContract пересекает границу изоляции).

Адаптер на стороне узла затем преобразует INativeHandleContract в FrameworkElement посредством вызова ContractToViewAdapter. Наконец, FrameworkElement задается как содержимое хост-представления.

Реализация надстройки

При использовании адаптера на стороне надстройки и представления надстройки надстройка может быть реализована путем наследования из представления надстройки (как показано в следующем коде).

    <addInViews:WPFAddInView
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:addInViews="clr-namespace:AddInViews;assembly=AddInViews"
    x:Class="WPFAddIn1.AddInUI">

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

</addInViews:WPFAddInView>


Imports System.AddIn ' AddInAttribute
Imports System.Windows ' MessageBox, RoutedEventArgs

Imports AddInViews ' WPFAddInView

Namespace WPFAddIn1
    ''' <summary>
    ''' Implements the add-in by deriving from WPFAddInView
    ''' </summary>
    <AddIn("WPF Add-In 1")>
    Partial Public Class AddInUI
        Inherits WPFAddInView
        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub clickMeButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            MessageBox.Show("Hello from WPFAddIn1")
        End Sub
    End Class
End Namespace

using System.AddIn; // AddInAttribute
using System.Windows; // MessageBox, RoutedEventArgs

using AddInViews; // WPFAddInView

namespace WPFAddIn1
{
    /// <summary>
    /// Implements the add-in by deriving from WPFAddInView
    /// </summary>
    [AddIn("WPF Add-In 1")]
    public partial class AddInUI : WPFAddInView
    {
        public AddInUI()
        {
            InitializeComponent();
        }

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

Этот пример наглядно показывает одно любопытное преимущество данной модели: разработчикам необходимо только реализовать надстройку (поскольку она представляет собой UI), а не класс надстройки и UI надстройки.

Реализация ведущего приложения

С помощью адаптера на стороне узла и созданного хост-представления ведущее приложение может использовать модель надстройки .NET Framework, чтобы открыть конвейер и получить хост-представление надстройки. Эти действия показаны в следующем коде.

' Get add-in pipeline folder (the folder in which this application was launched from)
Dim appPath As String = Environment.CurrentDirectory

' Rebuild visual add-in pipeline
Dim warnings() As String = AddInStore.Rebuild(appPath)
If warnings.Length > 0 Then
    Dim msg As String = "Could not rebuild pipeline:"
    For Each warning As String In warnings
        msg &= vbLf & warning
    Next warning
    MessageBox.Show(msg)
    Return
End If

' Activate add-in with Internet zone security isolation
Dim addInTokens As Collection(Of AddInToken) = AddInStore.FindAddIns(GetType(WPFAddInHostView), appPath)
Dim wpfAddInToken As AddInToken = addInTokens(0)
Me.wpfAddInHostView = wpfAddInToken.Activate(Of WPFAddInHostView)(AddInSecurityLevel.Internet)

' Display add-in UI
Me.addInUIHostGrid.Children.Add(Me.wpfAddInHostView)

// 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(WPFAddInHostView), appPath);
AddInToken wpfAddInToken = addInTokens[0];
this.wpfAddInHostView = wpfAddInToken.Activate<WPFAddInHostView>(AddInSecurityLevel.Internet);

// Display add-in UI
this.addInUIHostGrid.Children.Add(this.wpfAddInHostView);

Ведущее приложение использует обычный код модели надстройки .NET Framework для активации надстройки, которая неявным образом возвращает хост-представление ведущему приложению. Ведущее приложение затем отображает хост-представление (представляющее собой UserControl) из Grid.

Код для обработки взаимодействия с UI надстройки выполняется в домене приложения надстройки. Это взаимодействие включает следующие операции:

Обработка события Button Click.
Отображение MessageBox.

Это действие полностью изолировано от ведущего приложения.

См. также

Основные понятия

Надстройки и расширения среды

Общие сведения о надстройках WPF

Поделиться через