Come creare un Add-In che è una UI

Questo esempio illustra come creare un componente aggiuntivo che è Windows Presentation Foundation (WPF) ospitato in un'applicazione autonoma WPF.

Il componente aggiuntivo è un'interfaccia utente che è un controllo utente WPF. Il contenuto del controllo utente è un singolo pulsante che, quando si fa clic, visualizza una finestra di messaggio. L'applicazione autonoma WPF ospita l'interfaccia utente del componente aggiuntivo come contenuto della finestra principale dell'applicazione.

prerequisiti

In questo esempio vengono evidenziate le estensioni WPF per il modello di componente aggiuntivo .NET Framework che abilitano questo scenario e si presuppone quanto segue:

• Conoscenza del modello di componente aggiuntivo .NET Framework, tra cui pipeline, componenti aggiuntivi e sviluppo host. Se non si ha familiarità con questi concetti, vedere componenti aggiuntivi ed estensibilità. Per un tutorial che dimostra l'implementazione di una pipeline, un componente aggiuntivo e un'applicazione host, vedere Guida passo-passo: Creazione di un'applicazione estensibile.

• Conoscenza delle estensioni WPF per il modello di componente aggiuntivo .NET Framework. Consulta la panoramica WPF Add-Ins.

Esempio

Per creare un componente aggiuntivo che è un'interfaccia utente WPF richiede codice specifico per ogni segmento di pipeline, il componente aggiuntivo e l'applicazione host.

Implementazione del segmento della pipeline del contratto

Quando un componente aggiuntivo è un'interfaccia utente, il contratto per il componente aggiuntivo deve implementare INativeHandleContract. Nell'esempio IWPFAddInContract implementa INativeHandleContract, come illustrato nel codice seguente.

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

Implementazione del segmento della pipeline di visualizzazione Add-In

Poiché il componente aggiuntivo viene implementato come sottoclasse del tipo FrameworkElement, anche la vista del componente aggiuntivo deve essere una sottoclasse di FrameworkElement. Il codice seguente mostra la visualizzazione del componente aggiuntivo del contratto, implementata come classe WPFAddInView.

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

In questo caso, la visualizzazione del componente aggiuntivo è derivata da UserControl. Di conseguenza, l'interfaccia utente del componente aggiuntivo deve derivare anche da UserControl.

Implementazione del segmento della pipeline dell'adattatore Add-In-Side

Mentre il contratto è un INativeHandleContract, il componente aggiuntivo è un FrameworkElement (come specificato dal segmento della pipeline di visualizzazione del componente aggiuntivo). Pertanto, il FrameworkElement deve essere convertito in un INativeHandleContract prima di superare il limite di isolamento. Questa operazione viene eseguita dall'adattatore del lato del componente aggiuntivo chiamando ViewToContractAdapter, come illustrato nel codice seguente.

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

Nel modello di componente aggiuntivo in cui un componente aggiuntivo restituisce un'interfaccia utente (vedere Creare un Add-In che restituisce undell'interfaccia utente), l'adattatore ha trasformato il FrameworkElement in un INativeHandleContract attraverso la chiamata a ViewToContractAdapter. ViewToContractAdapter deve essere chiamato anche in questo modello, anche se è necessario implementare un metodo da cui scrivere il codice per chiamarlo. Per farlo, eseguire l'override di QueryContract e implementare il codice che chiama ViewToContractAdapter se il codice che chiama QueryContract prevede un INativeHandleContract. In questo caso, il chiamante sarà l'adattatore lato host, che verrà trattato in una sottosezione successiva.

Poiché l'adattatore sul lato componente aggiuntivo implementa un'interfaccia che deriva da INativeHandleContract, è necessario implementare anche GetHandle, anche se questo viene ignorato quando QueryContract viene sottoposto a override.

Implementazione del segmento della pipeline di visualizzazione host

In questo modello, l'applicazione host prevede in genere che la visualizzazione host sia una sottoclasse FrameworkElement. L'adattatore lato host deve convertire il INativeHandleContract in un FrameworkElement dopo che il INativeHandleContract supera il limite di isolamento. Poiché un metodo non viene chiamato dall'applicazione host per ottenere il FrameworkElement, la visualizzazione host deve "restituire" il FrameworkElement contenendolo. Di conseguenza, la vista host deve derivare da una sottoclasse di FrameworkElement che può contenere altre interfacce utente, ad esempio UserControl. Il codice seguente mostra la visualizzazione host del contratto, implementata come classe 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

Implementazione del segmento della pipeline dell'adattatore Host-Side

Mentre il contratto è un INativeHandleContract, l'applicazione host prevede un UserControl (come specificato dalla visualizzazione host). Di conseguenza, il INativeHandleContract deve essere convertito in un FrameworkElement dopo aver superato il limite di isolamento, prima di essere impostato come contenuto della visualizzazione host (che deriva da UserControl).

Questo lavoro viene eseguito dall'adattatore sul lato host, come illustrato nel codice seguente.

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

Come si può notare, l'adattatore sulla parte host acquisisce il INativeHandleContract chiamando il metodo di QueryContract dell'adattatore sulla parte add-in (questo è il punto in cui il INativeHandleContract attraversa il limite di isolamento).

L'adattatore sul lato host converte quindi il INativeHandleContract in un FrameworkElement chiamando ContractToViewAdapter. Infine, il FrameworkElement viene impostato come contenuto della visualizzazione host.

Implementazione del Add-In

Con l'adattatore sul lato aggiuntivo e la visualizzazione del componente aggiuntivo sul posto, il componente aggiuntivo può essere implementato derivando dalla visualizzazione del componente aggiuntivo, come illustrato nel codice seguente.

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

Da questo esempio è possibile vedere un vantaggio interessante di questo modello: gli sviluppatori di componenti aggiuntivi devono implementare solo il componente aggiuntivo (poiché è anche l'interfaccia utente), anziché una classe del componente aggiuntivo e un'interfaccia utente del componente aggiuntivo.

Implementazione dell'applicazione host

Dopo la creazione dell'adattatore sul lato host e della vista host, l'applicazione host può usare il modello di componente aggiuntivo .NET Framework per acquisire una vista host del componente aggiuntivo e aprire la pipeline. Questi passaggi sono illustrati nel codice seguente.

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

L'applicazione host utilizza il classico modello di componente aggiuntivo di .NET Framework per attivare il componente aggiuntivo, che restituisce in modo implicito la vista host all'applicazione host. L'applicazione host visualizza in seguito la vista host (che è un UserControl) da un Grid.

Il codice per l'elaborazione delle interazioni con l'interfaccia utente del componente aggiuntivo viene eseguito nel dominio dell'applicazione del componente aggiuntivo. Queste interazioni includono quanto segue:

• Gestione dell'evento ButtonClick.

• Visualizzazione del MessageBox.

Questa attività è completamente isolata dall'applicazione host.

Vedere anche

• Componenti aggiuntivi ed Estensibilità
• Panoramica WPF Add-Ins