Guide pratique pour créer un complément qui est une interface utilisateur

Cet exemple montre comment créer un complément qui est une windows Presentation Foundation (WPF) hébergée par une application autonome WPF.

Le complément est une interface utilisateur qui est un contrôle utilisateur WPF. Le contenu du contrôle utilisateur est un bouton unique qui, quand on clique dessus, affiche une boîte de message. L’application autonome WPF héberge l’interface utilisateur du complément comme contenu de la fenêtre principale de l’application.

Conditions préalables

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 bien ces concepts, consultez Compléments et extensibilité. Pour obtenir un didacticiel qui illustre 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. Consultez la vue d’ensemble des compléments WPF.

Exemple

Pour créer un complément qui est 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

Lorsqu’un complément est une interface utilisateur, le contrat du complément doit implémenter INativeHandleContract. Dans l’exemple, IWPFAddInContract implémente INativeHandleContract, comme indiqué 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.
    /// 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

Implémentation du segment de pipeline de vue de complément

Étant donné que le complément est implémenté en tant que sous-classe du FrameworkElement type, la vue complément doit également sous-classe FrameworkElement. Le code suivant montre l’affichage du complément du contrat, implémenté en tant que WPFAddInView classe.

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

Ici, la vue du complément est dérivée de UserControl. Par conséquent, l’interface utilisateur du complément doit également dériver de UserControl.

Implémentation du segment de pipeline d’adaptateur côté complément

Alors que le contrat est un INativeHandleContract, le complément est un FrameworkElement (tel que spécifié par le segment de pipeline de vue de complément). Par conséquent, il FrameworkElement doit être converti en une INativeHandleContract avant de traverser la limite d’isolation. Ce travail est effectué par l’adaptateur côté complément en appelant ViewToContractAdapter, comme indiqué dans le code suivant.

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

Dans le modèle de complément où un complément retourne une interface utilisateur (voir Créer un complément qui renvoie une interface utilisateur), l’adaptateur de complément a converti le FrameworkElement complément en un INativeHandleContract appel ViewToContractAdapter. ViewToContractAdapter doit également être appelé dans ce modèle, même si vous devez implémenter une méthode à partir de laquelle écrire le code pour l’appeler. Pour ce faire, substituez QueryContract et implémentez le code qui appelle ViewToContractAdapter si le code appelant QueryContract attend un INativeHandleContract. Dans ce cas, l’appelant sera l’adaptateur côté hôte, ce qui est traité dans une sous-section ultérieure.

Étant donné que l’adaptateur côté complément implémente une interface qui dérive de INativeHandleContract, vous devez également implémenter GetHandle, bien que cela soit ignoré lorsqu’il QueryContract est remplacé.

Implémentation du segment de pipeline de vue hôte

Dans ce modèle, l’application hôte s’attend généralement à ce que l’affichage hôte soit une FrameworkElement sous-classe. L’adaptateur côté hôte doit convertir la INativeHandleContract valeur en une FrameworkElement fois que la INativeHandleContract limite d’isolation est franchie. Étant donné qu’une méthode n’est pas appelée par l’application hôte pour obtenir le FrameworkElement, l’affichage hôte doit « retourner » en FrameworkElement le contenant. Par conséquent, la vue hôte doit dériver d’une sous-classe de FrameworkElement qui peut contenir d’autres UIs, telles que UserControl. Le code suivant montre l’affichage hôte du contrat, implémenté en tant que WPFAddInHostView classe.

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

Implémentation du segment de pipeline d’adaptateur côté hôte

Bien que le contrat soit un INativeHandleContract, l’application hôte attend un UserControl (tel que spécifié par la vue hôte). Par conséquent, il INativeHandleContract doit être converti en une FrameworkElement fois qu’il franchit la limite d’isolation, avant d’être défini comme contenu de la vue hôte (qui dérive de UserControl).

Cette opération est exécutée par l’adaptateur côté hôte, comme illustré 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 : 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

Comme vous pouvez le voir, l’adaptateur côté hôte acquiert l’adaptateur INativeHandleContract en appelant la méthode de QueryContract l’adaptateur côté complément (il s’agit du point où se trouve la INativeHandleContract limite d’isolation).

L’adaptateur côté hôte convertit ensuite le INativeHandleContract en un FrameworkElement en appelant ContractToViewAdapter. Enfin, la valeur FrameworkElement est définie comme contenu de l’affichage hôte.

Implémentation du complément

Avec l’adaptateur côté complément et la vue de complément en place, le complément peut être implémenté par dérivation de la vue de complément, comme illustré dans le code suivant.

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

Dans cet exemple, vous pouvez voir un avantage intéressant pour ce modèle : les développeurs de compléments doivent uniquement implémenter le complément (car il s’agit également de l’interface utilisateur), plutôt que d’une classe de complément et d’une interface utilisateur de complément.

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 et acquérir une vue hôte du complément. 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(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’application hôte utilise le code de modèle de complément .NET Framework classique pour activer le complément, qui retourne implicitement la vue hôte à l’application hôte. L’application hôte affiche par la suite l’affichage hôte (qui est un UserControl) à partir d’un Grid.

Le code permettant de traiter les interactions avec l’interface utilisateur du complément s’exécute dans le domaine d’application du complément. Ces interactions incluent :

• Gestion de l’événement ButtonClick .

• Affichage du MessageBox.

Cette activité est complètement isolée de l’application hôte.

Voir aussi

• Compléments et extensibilité
• Vue d’ensemble des compléments WPF