Comment : créer un complément qui retourne une interface utilisateur
Cet exemple montre comment créer un complément qui retourne une user interface (UI) Windows Presentation Foundation (WPF) à une application autonome WPF hôte.
Le complément retourne une UI qui correspond à un contrôle utilisateur WPF. Le contenu du contrôle utilisateur est un bouton unique qui, lorsque vous cliquez dessus, affiche un message. L'application autonome WPF héberge le complément et affiche le contrôle utilisateur (retourné par le complément) en tant que contenu de la fenêtre d'application principale.
Composants requis
Cet exemple met en surbrillance les extensions WPF au 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 du développement du pipeline, du complément et de l'hôte. Si ces concepts ne vous sont pas familiers, consultez Compléments et extensibilité. Pour obtenir des instructions pas à pas pour 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 au modèle de complément .NET Framework, que vous pouvez trouver dans : Vue d'ensemble des compléments WPF.
Exemple
La création d'un complément qui retourne une UI WPF requiert un code spécifique pour chaque segment de pipeline, le complément et l'application hôte.
Implémentation du segment de pipeline du contrat
Une méthode doit être définie par le contrat pour retourner une UI et sa valeur de retour doit être de type INativeHandleContract. La méthode GetAddInUI du contrat IWPFAddInContract utilisée dans le code suivant montre comment procéder.
Imports System.AddIn.Contract ' IContract, INativeHandleContract
Imports System.AddIn.Pipeline ' AddInContractAttribute
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
using System.AddIn.Contract; // IContract, INativeHandleContract
using System.AddIn.Pipeline; // AddInContractAttribute
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();
}
}
Implémentation du segment de pipeline de la vue du complément
Comme le complément implémente les UIs qu'il fournit comme sous-classes de FrameworkElement, la méthode utilisée dans la vue du complément qui correspond à IWPFAddInView.GetAddInUI doit retourner une valeur de type FrameworkElement. Le code suivant affiche la vue du complément du contrat, implémentée sous forme d'interface.
Imports System.AddIn.Pipeline ' AddInBaseAttribute
Imports System.Windows ' FrameworkElement
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
using System.AddIn.Pipeline; // AddInBaseAttribute
using System.Windows; // FrameworkElement
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();
}
}
Implémentation du segment d'adaptateur côté complément du pipeline
La méthode du contrat retourne un INativeHandleContract, tandis que le complément retourne un FrameworkElement (comme défini dans la vue du complément). Par conséquent, le FrameworkElement doit être converti en un INativeHandleContract avant de passer par la limite d'isolation. Cette opération est exécutée par l'adaptateur côté complément en appelant ViewToContractAdapter, comme illustré dans le code suivant.
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
Imports System.Windows ' FrameworkElement
Imports AddInViews ' IWPFAddInView
Imports Contracts ' IWPFAddInContract
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
using System.Windows; // FrameworkElement
using AddInViews; // IWPFAddInView
using Contracts; // IWPFAddInContract
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;
}
}
}
Implémentation du segment de pipeline de la vue hôte
Comme l'application hôte affiche un FrameworkElement, la méthode dans la vue hôte qui correspond à IWPFAddInHostView.GetAddInUI doit retourner une valeur de type FrameworkElement. Le code suivant affiche la vue hôte du contrat, implémentée sous forme d'interface.
Imports System.Windows ' FrameworkElement
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
using System.Windows; // FrameworkElement
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();
}
}
Implémentation du segment d'adaptateur côté hôte du pipeline
La méthode du contrat retourne un INativeHandleContract, alors que l'application hôte attend un FrameworkElement (comme spécifié par la vue hôte). Par conséquent, le INativeHandleContract doit être converti en un FrameworkElement après être passé par la limite d'isolation. Cette opération est exécutée par l'adaptateur côté hôte en appelant ContractToViewAdapter, comme illustré dans le code suivant.
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
Imports System.Windows ' FrameworkElement
Imports Contracts ' IWPFAddInContract
Imports HostViews ' IWPFAddInHostView
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
using System.Windows; // FrameworkElement
using Contracts; // IWPFAddInContract
using HostViews; // IWPFAddInHostView
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;
}
}
}
Implémentation du complément
Une fois l'adaptateur côté complément et la vue du complément créés, le complément (WPFAddIn1.AddIn) doit implémenter la méthode IWPFAddInView.GetAddInUI pour retourner un objet FrameworkElement (un UserControl dans cet exemple). L'implémentation du UserControl, AddInUI, est illustrée par le code suivant.
<UserControl
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
x:Class="WPFAddIn1.AddInUI">
<StackPanel>
<Button Click="clickMeButton_Click" Content="Click Me!" />
</StackPanel>
</UserControl>
Imports System.Windows ' MessageBox, RoutedEventArgs
Imports System.Windows.Controls ' UserControl
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
using System.Windows; // MessageBox, RoutedEventArgs
using System.Windows.Controls; // UserControl
namespace WPFAddIn1
{
public partial class AddInUI : UserControl
{
public AddInUI()
{
InitializeComponent();
}
void clickMeButton_Click(object sender, RoutedEventArgs e)
{
MessageBox.Show("Hello from WPFAddIn1");
}
}
}
L'implémentation de IWPFAddInView.GetAddInUI par le complément doit simplement retourner une nouvelle instance de AddInUI, comme illustré par le code suivant.
Imports System.AddIn ' AddInAttribute
Imports System.Windows ' FrameworkElement
Imports AddInViews ' IWPFAddInView
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
using System.AddIn; // AddInAttribute
using System.Windows; // FrameworkElement
using AddInViews; // IWPFAddInView
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();
}
}
}
Implémentation de l'application hôte
Une fois l'adaptateur côté hôte et la vue hôte créés, 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 illustrées dans le code suivant.
' 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)
// 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);