Jak utworzyć dodatek, który jest interfejsem użytkownika

W tym przykładzie pokazano, jak utworzyć dodatek, który jest aplikacją autonomiczną systemu Windows Presentation Foundation (WPF), która jest hostowana przez autonomiczną aplikację WPF.

Dodatek to interfejs użytkownika, który jest kontrolką użytkownika WPF. Zawartość kontrolki użytkownika to pojedynczy przycisk, który po kliknięciu wyświetla okno komunikatu. Aplikacja autonomiczna WPF hostuje interfejs użytkownika dodatku jako zawartość głównego okna aplikacji.

Wymagania wstępne

W tym przykładzie wyróżniono rozszerzenia WPF do modelu dodatku .NET Framework, które umożliwiają ten scenariusz, i przyjęto założenie, że:

• Znajomość modelu dodatku .NET Framework, w tym potoku, dodatku i programowania hosta. Jeśli nie znasz tych pojęć, zobacz Dodatki i rozszerzalność. Aby zapoznać się z samouczkiem przedstawiającym implementację potoku, dodatku i aplikacji hosta, zobacz Przewodnik: tworzenie rozszerzonej aplikacji.

• Znajomość rozszerzeń WPF w modelu dodatku .NET Framework. Zobacz Omówienie dodatków WPF.

Przykład

Aby utworzyć dodatek, który jest interfejsem użytkownika WPF, wymaga określonego kodu dla każdego segmentu potoku, dodatku i aplikacji hosta.

Implementowanie segmentu potoku kontraktu

Gdy dodatek jest interfejsem użytkownika, kontrakt dodatku musi zaimplementować element INativeHandleContract. W tym przykładzie IWPFAddInContract implementuje INativeHandleContractelement , jak pokazano w poniższym kodzie.

using System.AddIn.Contract;
using System.AddIn.Pipeline;

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 {}
}

Imports System.AddIn.Contract
Imports System.AddIn.Pipeline

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

Implementowanie segmentu potoku widoku dodatku

Ponieważ dodatek jest implementowany jako podklasa FrameworkElement typu, widok dodatku musi również podklasę FrameworkElement. Poniższy kod przedstawia widok dodatku kontraktu zaimplementowany jako WPFAddInView klasa.

using System.AddIn.Pipeline;
using System.Windows.Controls;

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

Imports System.AddIn.Pipeline
Imports System.Windows.Controls

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

W tym miejscu widok dodatku pochodzi z elementu UserControl. W związku z tym interfejs użytkownika dodatku powinien również pochodzić z elementu UserControl.

Implementowanie segmentu potoku adaptera dodatkowego

Chociaż kontrakt jest dodatkiem , dodatek jest elementem INativeHandleContractFrameworkElement (określonym przez segment potoku widoku dodatku). W związku z tym należy przekonwertować obiekt FrameworkElement na obiekt INativeHandleContract przed przekroczeniem granicy izolacji. Ta praca jest wykonywana przez kartę dodatku, wywołując metodę ViewToContractAdapter, jak pokazano w poniższym kodzie.

using System;
using System.AddIn.Contract;
using System.AddIn.Pipeline;
using System.Security.Permissions;

using AddInViews;
using Contracts;

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 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, that is, 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>
        public IntPtr GetHandle()
        {
            return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView).GetHandle();
        }
    }
}

Imports System
Imports System.AddIn.Contract
Imports System.AddIn.Pipeline
Imports System.Security.Permissions

Imports AddInViews
Imports Contracts

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 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, that is, overriding ContractBase.QueryContract, 
        ''' as shown above.
        ''' </summary>
        Public Function GetHandle() As IntPtr Implements INativeHandleContract.GetHandle
            Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView).GetHandle()
        End Function

    End Class
End Namespace

W modelu dodatku, w którym dodatek zwraca interfejs użytkownika (zobacz Tworzenie dodatku, który zwraca interfejs użytkownika), adapter dodatku przekonwertował FrameworkElement element na element INativeHandleContract przez wywołanie metody ViewToContractAdapter. ViewToContractAdapter Należy również wywołać metodę w tym modelu, chociaż należy zaimplementować metodę, z której należy napisać kod w celu jego wywołania. W tym celu należy zastąpić QueryContract i zaimplementować kod, który wywołuje ViewToContractAdapter , jeśli wywoływany kod QueryContract oczekuje elementu INativeHandleContract. W takim przypadku obiekt wywołujący będzie kartą po stronie hosta, która zostanie omówiona w kolejnej podsekcji.

Uwaga

Należy również zastąpić QueryContract ten model, aby włączyć tabulacji między interfejsem użytkownika aplikacji hosta i interfejsem użytkownika dodatku. Aby uzyskać więcej informacji, zobacz "Ograniczenia dodatków WPF" w omówienie dodatków WPF.

Ponieważ adapter dodatku implementuje interfejs pochodzący z INativeHandleContractklasy , należy również zaimplementować GetHandleelement , chociaż jest to ignorowane, gdy QueryContract jest zastępowany.

Implementowanie segmentu potoku widoku hosta

W tym modelu aplikacja hosta zwykle oczekuje, że widok hosta będzie podklasą FrameworkElement . Adapter po stronie hosta musi przekonwertować INativeHandleContract wartość na wartość FrameworkElement po przekroczeniu INativeHandleContract granicy izolacji. Ponieważ metoda nie jest wywoływana przez aplikację hosta w celu pobrania FrameworkElementelementu , widok hosta musi "zwrócić" FrameworkElement element, zawierający go. W związku z tym widok hosta musi pochodzić z podklasy FrameworkElement , która może zawierać inne interfejsy użytkownika, takie jak UserControl. Poniższy kod przedstawia widok hosta kontraktu zaimplementowany jako WPFAddInHostView klasa.

using System.Windows.Controls;

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

Imports System.Windows.Controls

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

Implementowanie segmentu potoku adaptera po stronie hosta

Chociaż kontrakt jest parametrem INativeHandleContract, aplikacja hosta oczekuje UserControl wartości (określonej przez widok hosta). W związku z tym należy przekonwertować element INativeHandleContract na wartość FrameworkElement po przekroczeniu granicy izolacji, zanim zostanie ustawiony jako zawartość widoku hosta (który pochodzi z UserControlelementu ).

Ta praca jest wykonywana przez kartę po stronie hosta, jak pokazano w poniższym kodzie.

using System.AddIn.Contract;
using System.AddIn.Pipeline;
using System.Windows;

using Contracts;
using HostViews;

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;
        }
    }
}

Imports System.AddIn.Contract
Imports System.AddIn.Pipeline
Imports System.Windows

Imports Contracts
Imports HostViews

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

Jak widać, karta po stronie hosta uzyskuje INativeHandleContract wartość przez wywołanie metody karty QueryContract dodatku (jest to punkt, w którym INativeHandleContract przekracza granicę izolacji).

Następnie adapter po stronie hosta konwertuje INativeHandleContract element na element FrameworkElement przez wywołanie metody ContractToViewAdapter. Na koniec parametr FrameworkElement jest ustawiany jako zawartość widoku hosta.

Implementowanie dodatku

Za pomocą karty dodatku i widoku dodatku można zaimplementować dodatek, wyprowadzając go z widoku dodatku, jak pokazano w poniższym kodzie.

using System.AddIn;
using System.Windows;

using AddInViews;

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");
        }
    }
}

Imports System.AddIn
Imports System.Windows

Imports AddInViews

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

W tym przykładzie można zobaczyć jedną interesującą zaletę tego modelu: deweloperzy dodatku muszą zaimplementować tylko dodatek (ponieważ jest to również interfejs użytkownika), a nie zarówno klasę dodatku, jak i interfejs użytkownika dodatku.

Implementowanie aplikacji hosta

Po utworzeniu karty hosta i widoku hosta aplikacja hosta może użyć modelu dodatku .NET Framework, aby otworzyć potok i uzyskać widok hosta dodatku. Te kroki przedstawiono w poniższym kodzie.

// 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);

' 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)

Aplikacja hosta używa typowego kodu modelu dodatku .NET Framework w celu aktywowania dodatku, który niejawnie zwraca widok hosta do aplikacji hosta. Następnie aplikacja hosta wyświetla widok hosta (który jest elementem UserControl) z obiektu Grid.

Kod do przetwarzania interakcji z interfejsem użytkownika dodatku jest uruchamiany w domenie aplikacji dodatku. Te interakcje obejmują następujące elementy:

• Obsługa zdarzenia ButtonClick .

• Wyświetlanie pliku MessageBox.

To działanie jest całkowicie odizolowane od aplikacji hosta.

Zobacz też

• Dodatki i rozszerzalność
• Dodatki WPF — omówienie