Guide pratique pour créer un Add-In qui retourne une interface utilisateur

Cet exemple montre comment créer un complément qui retourne une application windows Presentation Foundation (WPF) à une application autonome WPF hôte.

Le complément retourne une interface utilisateur qui est un contrôle utilisateur WPF. Le contenu du contrôle utilisateur est un bouton unique qui, lorsque vous cliquez dessus, affiche une boîte de message. L’application autonome WPF héberge le complément et affiche le contrôle utilisateur (retourné par le complément) comme contenu de la fenêtre principale de l’application.

conditions préalables requises

Cet exemple met en évidence les extensions WPF du modèle de complément .NET Framework qui activent ce scénario et suppose ce qui suit :

• Connaissance du modèle de complément .NET Framework, y compris le pipeline, le complément et le développement hôte. Si vous ne connaissez pas ces concepts, consultez compléments et extensibilité. Pour obtenir un didacticiel montrant l’implémentation d’un pipeline, d’un complément et d’une application hôte, consultez procédure pas à pas : création d’une application extensible.

• Connaissance des extensions WPF du modèle de complément .NET Framework, disponibles ici : WPF Add-Ins Vue d'ensemble.

Exemple

Pour créer un complément qui retourne une interface utilisateur WPF nécessite un code spécifique pour chaque segment de pipeline, le complément et l’application hôte.

Implémentation du segment de pipeline de contrat

Une méthode doit être définie par le contrat pour retourner une interface utilisateur, et sa valeur de retour doit être de type INativeHandleContract. Ceci est illustré par la méthode GetAddInUI du contrat IWPFAddInContract dans le code suivant.

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

Implémentation du segment de pipeline Add-In View

Étant donné que le complément implémente les interfaces utilisateur qu’il fournit en tant que sous-classes de FrameworkElement, la méthode de la vue du complément qui correspond à IWPFAddInView.GetAddInUI doit retourner une valeur de type FrameworkElement. Le code suivant montre la vue de complément du contrat, implémentée en tant qu’interface.

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

Implémentation du segment de pipeline d’adaptateur Add-In-Side

La méthode de contrat retourne un INativeHandleContract, mais le module complémentaire retourne un FrameworkElement (tel que spécifié par la vue du module complémentaire). Par conséquent, la FrameworkElement doit être convertie en INativeHandleContract avant de traverser la limite d’isolation. L'adaptateur côté complément effectue ce travail en appelant ViewToContractAdapter, comme indiqué dans le code suivant.

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

Implémentation du segment de pipeline d’affichage hôte

Étant donné que l’application hôte affiche une FrameworkElement, la méthode de la vue hôte qui correspond à IWPFAddInHostView.GetAddInUI doit retourner une valeur de type FrameworkElement. Le code suivant montre la vue hôte du contrat, implémentée en tant qu'interface.

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

Implémentation du segment de pipeline d’adaptateur Host-Side

La méthode de contrat retourne une INativeHandleContract, mais l’application hôte attend un FrameworkElement (comme spécifié par la vue hôte). Par conséquent, le INativeHandleContract doit être converti en FrameworkElement après avoir franchi la limite d’isolation. Ce travail est effectué par l’adaptateur côté hôte en appelant ContractToViewAdapter, comme indiqué dans le code suivant.

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

Implémentation du Add-In

Avec l’adaptateur côté complément et l’affichage complément créés, le complément (WPFAddIn1.AddIn) doit implémenter la méthode IWPFAddInView.GetAddInUI pour renvoyer un objet FrameworkElement (un UserControl dans cet exemple). L’implémentation du UserControl, AddInUI, est illustrée par le code suivant.

    <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’implémentation de IWPFAddInView.GetAddInUI par le module complémentaire doit simplement retourner une nouvelle instance de AddInUI, comme illustré dans le code suivant.

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

Implémentation de l’application hôte

Avec l’adaptateur côté hôte et la vue hôte créées, l’application hôte peut utiliser le modèle de complément .NET Framework pour ouvrir le pipeline, acquérir une vue hôte du complément et appeler la méthode IWPFAddInHostView.GetAddInUI. Ces étapes sont présentées dans le code suivant.

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

Voir aussi

• Compléments et extensibilité
• Vue d’ensemble WPF Add-Ins