So erstellen Sie ein Add-In, das eine Benutzeroberfläche ist

Dieses Beispiel zeigt, wie Sie ein Add-In erstellen, bei dem es sich um eine Windows Presentation Foundation (WPF) handelt, die von einer eigenständigen WPF-Anwendung gehostet wird.

Das Add-In ist eine Benutzeroberfläche, die ein WPF-Benutzersteuerelement ist. Der Inhalt des Benutzersteuerelements ist eine einzelne Schaltfläche, die beim Klicken auf ein Meldungsfeld angezeigt wird. Die eigenständige WPF-Anwendung hostt die Add-In-Benutzeroberfläche als Inhalt des Hauptanwendungsfensters.

Voraussetzungen

In diesem Beispiel werden die WPF-Erweiterungen für das .NET Framework Add-in-Modell hervorgehoben, die dieses Szenario ermöglichen, und es wird das Folgende angenommen:

• Kenntnisse des .NET Framework-Add-In-Modells, einschließlich Pipeline-, Add-In- und Hostentwicklung. Wenn Sie mit diesen Konzepten nicht vertraut sind, lesen Sie Add-Ins und Erweiterbarkeit. Ein Lernprogramm, das die Implementierung einer Pipeline, eines Add-Ins und einer Hostanwendung veranschaulicht, finden Sie unter Walkthrough: Creating an Extensible Application.

• Kenntnisse der WPF-Erweiterungen für das .NET Framework-Add-In-Modell. Siehe WPF Add-Ins Übersicht.

Beispiel

Zum Erstellen eines Add-Ins, bei dem es sich um eine WPF-Benutzeroberfläche handelt, ist ein bestimmter Code für jedes Pipelinesegment, das Add-In und die Hostanwendung erforderlich.

Implementieren des Vertragspipelinesegments

Wenn ein Add-In eine Benutzeroberfläche ist, muss der Vertrag für das Add-In INativeHandleContractimplementieren. Im Beispiel implementiert IWPFAddInContractINativeHandleContract, wie im folgenden Code dargestellt.

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

Implementieren des Add-In Ansichtspipelinesegments

Da das Add-In als Unterklasse des FrameworkElement Typs implementiert wurde, muss die Add-In-Ansicht auch eine Unterklasse von FrameworkElementsein. Der folgende Code zeigt die Add-In-Ansicht des Vertrags, implementiert als WPFAddInView-Klasse.

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

Hier wird die Add-In-Ansicht von UserControlabgeleitet. Folglich sollte die Benutzeroberfläche des Add-Ins auch von UserControlabgeleitet werden.

Implementierung des Add-In-Side-Adapter-Pipeline-Segments

Während der Vertrag ein INativeHandleContractist, ist das Add-In ein FrameworkElement (wie im Pipelinesegment der Add-In-Ansicht angegeben). Daher muss die FrameworkElement vor dem Überschreiten der Isolationsgrenze in eine INativeHandleContract umgewandelt werden. Diese Arbeit führt der Add-In-Side-Adapter aus, indem er ViewToContractAdapteraufruft, wie im folgenden Code gezeigt wird.

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

Im Add-In-Modell, in dem ein Add-In eine Benutzeroberfläche zurückgibt (siehe Erstellen einer Add-In, die eine Benutzeroberfläche zurückgibt,), hat der Add-In-Adapter die FrameworkElement in eine INativeHandleContract konvertiert, indem ViewToContractAdapteraufgerufen wird. ViewToContractAdapter muss auch in diesem Modell aufgerufen werden, obwohl Sie eine Methode implementieren müssen, aus der Sie den Code zum Aufrufen schreiben können. Dazu überschreiben Sie QueryContract und implementieren den Code, der ViewToContractAdapter aufruft, wenn der Code, der QueryContract aufruft, ein INativeHandleContracterwartet. In diesem Fall ist der Aufrufer der hostseitige Adapter, der in einem nachfolgenden Unterabschnitt behandelt wird.

Anmerkung

Darüber hinaus müssen Sie QueryContract in diesem Modell außer Kraft setzen, um das Tabbing zwischen Hostanwendungs-UI und Add-In-UI zu aktivieren. Weitere Informationen finden Sie unter "WPF Add-In Limitations" in WPF Add-Ins Overview.

Da der Add-In-Side-Adapter eine Schnittstelle implementiert, die von INativeHandleContractabgeleitet wird, müssen Sie auch GetHandleimplementieren, auch wenn dies ignoriert wird, sobald QueryContract überschrieben wird.

Implementieren des Pipelinesegments "Hostansicht"

In diesem Modell erwartet die Hostanwendung in der Regel, dass die Hostansicht eine FrameworkElement Unterklasse ist. Der hostseitige Adapter muss die INativeHandleContract zu einer FrameworkElement umwandeln, nachdem die INativeHandleContract die Isolationsgrenze überschreitet. Da eine Methode nicht von der Hostanwendung aufgerufen wird, um die FrameworkElementzu erhalten, muss die Hostansicht die FrameworkElement zurückgeben, indem sie sie enthält. Folglich muss die Hostansicht von einer Unterklasse von FrameworkElement abgeleitet werden, die andere UIs enthalten kann, z. B. UserControl. Der folgende Code zeigt die Hostansicht des Vertrags, implementiert als Klasse WPFAddInHostView.

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

Implementierung des Host-Side-Adapter-Pipeline-Segments

Während der Vertrag ein INativeHandleContractist, erwartet die Hostanwendung eine UserControl (wie in der Hostansicht angegeben). Folglich muss die INativeHandleContract nach dem Überschreiten der Isolationsgrenze in eine FrameworkElement konvertiert werden, bevor sie als Inhalt der Hostansicht festgelegt wird (die von UserControlabgeleitet wird).

Diese Arbeit wird vom hostseitigen Adapter ausgeführt, wie im folgenden Code gezeigt.

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

Wie Sie sehen können, ruft der hostseitige Adapter die INativeHandleContract ab, indem er die QueryContract-Methode des Add-In-seitigen Adapters aufruft (dies ist der Punkt, an dem die INativeHandleContract die Isolationsgrenze überschreitet).

Der hostseitige Adapter konvertiert dann die INativeHandleContract in eine FrameworkElement, indem ContractToViewAdapteraufgerufen wird. Schließlich wird der FrameworkElement als Inhalt der Hostansicht festgelegt.

Umsetzung von Add-In

Wenn der Add-In-Adapter und die Add-In-Ansicht vorhanden sind, kann das Add-In implementiert werden, indem es von der Add-In-Ansicht abgeleitet wird, wie im folgenden Code dargestellt.

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

In diesem Beispiel sehen Sie einen interessanten Vorteil dieses Modells: Add-In-Entwickler müssen das Add-In nur implementieren (da es auch die Benutzeroberfläche ist), anstatt sowohl eine Add-In-Klasse als auch eine Add-In-Benutzeroberfläche.

Implementieren der Hostanwendung

Nachdem der hostseitige Adapter und die Hostansicht erstellt wurden, kann die Hostanwendung das .NET Framework-Add-In-Modell verwenden, um die Pipeline zu öffnen und eine Hostansicht des Add-Ins zu erhalten. Diese Schritte werden im folgenden Code gezeigt.

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

Die Hostanwendung verwendet typischen .NET Framework-Add-In-Modellcode zum Aktivieren des Add-Ins, das implizit die Hostansicht an die Hostanwendung zurückgibt. Die Hostanwendung zeigt anschließend die Hostansicht (ein UserControl) aus einem Gridan.

Der Code für die Verarbeitung von Interaktionen mit der Add-In-Benutzeroberfläche wird in der Anwendungsdomäne des Add-Ins ausgeführt. Diese Interaktionen umfassen Folgendes:

• Behandeln des ButtonClick-Ereignisses.

• Zeigt die MessageBoxan.

Diese Aktivität ist vollständig von der Hostanwendung isoliert.

Siehe auch

• Add-Ins und Erweiterbarkeit
• WPF Add-Ins Übersicht