Procedura: creare un componente aggiuntivo che restituisce un'interfaccia utente

Questo esempio illustra come creare un componente aggiuntivo che restituisce windows Presentation Foundation (WPF) a un'applicazione autonoma WPF host.

Il componente aggiuntivo restituisce un'interfaccia utente che è un controllo utente WPF. Il contenuto del controllo utente è costituito da un unico pulsante che consente di visualizzare una finestra di messaggio. L'applicazione autonoma WPF ospita il componente aggiuntivo e visualizza il controllo utente (restituito dal 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. Per informazioni su questi concetti, vedere Componenti aggiuntivi ed estensibilità. Per un'esercitazione in cui venga illustrata l'implementazione di una pipeline, un componente aggiuntivo e un'applicazione host, vedere Procedura dettagliata: creazione di un'applicazione estendibile.

• Conoscenza delle estensioni WPF per il modello di componente aggiuntivo .NET Framework, disponibile qui: Cenni preliminari sui componenti aggiuntivi WPF.

Esempio

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

Implementazione del segmento di pipeline di contratto

Un metodo deve essere definito dal contratto per la restituzione di un'interfaccia utente e il relativo valore restituito deve essere di tipo INativeHandleContract. Ciò è dimostrato dal GetAddInUI metodo del IWPFAddInContract contratto 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
    /// </summary>
    [AddInContract]
    public interface IWPFAddInContract : IContract
    {
        // Return a UI to the host application
        INativeHandleContract GetAddInUI();
    }
}

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

Namespace Contracts
    ''' <summary>
    ''' Defines the services that an add-in will provide to a host application
    ''' </summary>
    <AddInContract>
    Public Interface IWPFAddInContract
        Inherits IContract
        ' Return a UI to the host application
        Function GetAddInUI() As INativeHandleContract
    End Interface
End Namespace

Implementazione del segmento di pipeline di visualizzazione componente aggiuntivo

Poiché il componente aggiuntivo implementa le interfacce utente fornite come sottoclassi di FrameworkElement, il metodo nella vista del componente aggiuntivo correlato a IWPFAddInView.GetAddInUI deve restituire un valore di tipo FrameworkElement. Il codice seguente illustra la visualizzazione componente aggiuntivo del contratto, implementata come interfaccia.

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

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

Imports System.AddIn.Pipeline
Imports System.Windows

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.
        Function GetAddInUI() As FrameworkElement
    End Interface
End Namespace

Implementazione del segmento di pipeline dell'adattatore sul lato del componente aggiuntivo

Il metodo contract restituisce un INativeHandleContractoggetto , ma il componente aggiuntivo restituisce un oggetto FrameworkElement , come specificato dalla visualizzazione del componente aggiuntivo. Di conseguenza, l'oggetto FrameworkElement deve essere convertito in un oggetto INativeHandleContract prima di superare il limite di isolamento. Questa operazione viene eseguita dall'adattatore sul lato componente aggiuntivo chiamando ViewToContractAdapter, come illustrato nel codice seguente.

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

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

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

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 IWPFAddInView

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

        Public Function GetAddInUI() As INativeHandleContract Implements IWPFAddInContract.GetAddInUI
            ' Convert the FrameworkElement from the add-in to an INativeHandleContract 
            ' that will be passed across the isolation boundary to the host application.
            Dim fe As FrameworkElement = Me.wpfAddInView.GetAddInUI()
            Dim inhc As INativeHandleContract = FrameworkElementAdapters.ViewToContractAdapter(fe)
            Return inhc
        End Function
    End Class
End Namespace

Implementazione del segmento di pipeline di visualizzazione host

Poiché l'applicazione host visualizzerà un FrameworkElementoggetto , il metodo nella visualizzazione host correlata a IWPFAddInHostView.GetAddInUI deve restituire un valore di tipo FrameworkElement. Il codice seguente illustra la visualizzazione host del contratto, implementata come interfaccia.

using System.Windows;

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

Imports System.Windows

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.
        Function GetAddInUI() As FrameworkElement
    End Interface
End Namespace

Implementazione del segmento di pipeline dell'adattatore sul lato host

Il metodo del contratto restituisce un oggetto INativeHandleContract, ma l'applicazione host prevede un oggetto FrameworkElement (come specificato dalla visualizzazione host). Di conseguenza, l'oggetto INativeHandleContract deve essere convertito in un oggetto FrameworkElement dopo aver superato il limite di isolamento. Questa operazione viene eseguita dall'adattatore lato host chiamando ContractToViewAdapter, 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 : 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;
        }
    }
}

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
        Implements IWPFAddInHostView
        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 (IWPFAddInHostView)
            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)
        End Sub

        Public Function GetAddInUI() As FrameworkElement Implements IWPFAddInHostView.GetAddInUI
            ' Convert the INativeHandleContract that was passed from the add-in side
            ' of the isolation boundary to a FrameworkElement
            Dim inhc As INativeHandleContract = Me.wpfAddInContract.GetAddInUI()
            Dim fe As FrameworkElement = FrameworkElementAdapters.ContractToViewAdapter(inhc)
            Return fe
        End Function
    End Class
End Namespace

Implementazione del componente aggiuntivo

Con l'adattatore sul lato aggiuntivo e la visualizzazione del componente aggiuntivo creata, il componente aggiuntivo (WPFAddIn1.AddIn) deve implementare il IWPFAddInView.GetAddInUI metodo per restituire un FrameworkElement oggetto (in UserControl questo esempio). L'implementazione di UserControl, AddInUIè illustrata dal codice seguente.

    <UserControl
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="WPFAddIn1.AddInUI">
    
    <StackPanel>
        <Button Click="clickMeButton_Click" Content="Click Me!" />
    </StackPanel>
    
</UserControl>

using System.Windows;
using System.Windows.Controls;

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

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

Imports System.Windows
Imports System.Windows.Controls

Namespace WPFAddIn1
    Partial Public Class AddInUI
        Inherits UserControl
        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

L'implementazione di da IWPFAddInView.GetAddInUI parte del componente aggiuntivo deve semplicemente restituire una nuova istanza di AddInUI, come illustrato nel codice seguente.

using System.AddIn;
using System.Windows;

using AddInViews;

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

Imports System.AddIn
Imports System.Windows

Imports AddInViews

Namespace WPFAddIn1
    ''' <summary>
    ''' Add-In implementation
    ''' </summary>
    <AddIn("WPF Add-In 1")>
    Public Class WPFAddIn
        Implements IWPFAddInView
        Public Function GetAddInUI() As FrameworkElement Implements IWPFAddInView.GetAddInUI
            ' Return add-in UI
            Return New AddInUI()
        End Function
    End Class
End Namespace

Implementazione dell'applicazione host

Dopo la creazione dell'adattatore sul lato host e della visualizzazione host, l'applicazione host può usare il modello di componente aggiuntivo .NET Framework per aprire la pipeline, acquisire una visualizzazione host del componente aggiuntivo e chiamare il IWPFAddInHostView.GetAddInUI metodo . Il codice riportato di seguito illustra i diversi passaggi.

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

' 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(IWPFAddInHostView), appPath)
Dim wpfAddInToken As AddInToken = addInTokens(0)
Me.wpfAddInHostView = wpfAddInToken.Activate(Of IWPFAddInHostView)(AddInSecurityLevel.Internet)

' Get and display add-in UI
Dim addInUI As FrameworkElement = Me.wpfAddInHostView.GetAddInUI()
Me.addInUIHostGrid.Children.Add(addInUI)

Vedi anche

• Componenti aggiuntivi ed estendibilità
• Cenni preliminari sui componenti aggiuntivi di WPF