Comment : créer un complément qui est une interface utilisateur
Cet exemple explique comment créer un complément qui est une Windows Presentation Foundation (WPF)user interface (UI) hébergée par une application autonome WPF.
Le complément est 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 l'UI du 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 est 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
Lorsqu'un complément est une UI, le contrat du complément doit implémenter INativeHandleContract. Dans l'exemple, IWPFAddInContract implémente INativeHandleContract, comme illustré dans le code suivant.
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInContractAttribute
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInContractAttribute
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 {}
}
Implémentation du segment de pipeline de la vue du complément
Étant donné que le complément est implémenté comme une sous-classe du type FrameworkElement, la vue du complément doit également sous-classer FrameworkElement. Le code suivant illustre la vue du complément du contrat, implémentée comme la classe WPFAddInView.
Imports System.AddIn.Pipeline ' AddInBaseAttribute
Imports System.Windows.Controls ' UserControl
Namespace AddInViews
''' <summary>
''' Defines the add-in's view of the contract.
''' </summary>
<AddInBase>
Public Class WPFAddInView
Inherits UserControl
End Class
End Namespace
using System.AddIn.Pipeline; // AddInBaseAttribute
using System.Windows.Controls; // UserControl
namespace AddInViews
{
/// <summary>
/// Defines the add-in's view of the contract.
/// </summary>
[AddInBase]
public class WPFAddInView : UserControl { }
}
Ici, la vue du complément est dérivée de UserControl. Par conséquent, l'UI du complément doit également être dérivée de UserControl.
Implémentation du segment d'adaptateur côté complément du pipeline
Le contrat est un INativeHandleContract, alors que le complément est un FrameworkElement (comme spécifié par le segment de pipeline de 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 indiqué dans le code suivant.
Imports System ' IntPtr
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
Imports System.Security.Permissions
Imports AddInViews ' WPFAddInView
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 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 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 ie 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>
<SecurityPermissionAttribute(SecurityAction.Demand, Flags:=SecurityPermissionFlag.UnmanagedCode)>
Public Function GetHandle() As IntPtr Implements INativeHandleContract.GetHandle
Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView).GetHandle()
End Function
End Class
End Namespace
using System; // IntPtr
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
using System.Security.Permissions;
using AddInViews; // WPFAddInView
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
{
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 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 ie 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>
[SecurityPermissionAttribute(SecurityAction.Demand, Flags = SecurityPermissionFlag.UnmanagedCode)]
public IntPtr GetHandle()
{
return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView).GetHandle();
}
}
}
Dans le modèle de complément qui implique qu'un complément retourne une UI (voir Comment : créer un complément qui retourne une interface utilisateur), l'adaptateur du complément convertit le FrameworkElement en un INativeHandleContract en appelant ViewToContractAdapter. ViewToContractAdapter doit également être appelé dans ce modèle, même si vous devez implémenter une méthode depuis laquelle écrire le code pour l'appeler. Pour ce faire, vous remplacez QueryContract et implémentez le code qui appelle ViewToContractAdapter si le code qui appelle QueryContract attend un INativeHandleContract. Dans ce cas, l'appelant sera l'adaptateur côté hôte, qui sera abordé dans une sous-section ultérieure.
.gif "Remarque") Remarque |
|---|
Vous devez également remplacer QueryContract dans ce modèle pour permettre la tabulation entre l'UI de l'application hôte et l'UI du complément.Pour plus d'informations, consultez « Limitations des compléments WPF » dans Vue d'ensemble des compléments WPF. |
Comme l'adaptateur côté complément implémente une interface dérivée de INativeHandleContract, vous devez également implémenter GetHandle, bien que cette opération soit ignorée lors du remplacement de QueryContract.
Implémentation du segment de pipeline de la vue hôte
L'application hôte attend en général que la vue hôte soit une sous-classe FrameworkElement dans ce modèle. L'adaptateur côté hôte doit convertir le INativeHandleContract en un FrameworkElement après que le INativeHandleContract est passé par la limite d'isolation. Étant donné qu'une méthode n'est pas appelée par l'application hôte pour obtenir le FrameworkElement, la vue hôte doit "retourner" le FrameworkElement en le contenant. Par conséquent, la vue hôte doit dériver d'une sous-classe de FrameworkElement qui peut contenir d'autres UIs, comme UserControl. Le code suivant illustre la vue hôte du contrat, implémentée comme la classe WPFAddInHostView.
Imports System.Windows.Controls ' UserControl
Namespace HostViews
''' <summary>
''' Defines the host's view of the add-in
''' </summary>
Public Class WPFAddInHostView
Inherits UserControl
End Class
End Namespace
using System.Windows.Controls; // UserControl
namespace HostViews
{
/// <summary>
/// Defines the host's view of the add-in
/// </summary>
public class WPFAddInHostView : UserControl { }
}
Implémentation du segment d'adaptateur côté hôte du pipeline
Le contrat est un INativeHandleContract, alors que l'application hôte attend un UserControl (comme spécifié par la vue hôte). Par conséquent, le INativeHandleContract doit être converti en un FrameworkElement après avoir traversé la limite d'isolation, avant d'être défini comme contenu de la vue hôte (lequel est dérivé de UserControl).
Cette opération est exécutée par l'adaptateur côté hôte, comme indiqué 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 ' WPFAddInHostView
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
using System.Windows; // FrameworkElement
using Contracts; // IWPFAddInContract
using HostViews; // WPFAddInHostView
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;
}
}
}
Comme vous pouvez le voir, l'adaptateur côté hôte acquiert le INativeHandleContract en appelant la méthode QueryContract de l'adaptateur côté complément (c'est à ce niveau que le INativeHandleContract passe par la limite d'isolation).
L'adaptateur côté hôte convertit ensuite le INativeHandleContract en un FrameworkElement en appelant ContractToViewAdapter. Enfin, le FrameworkElement est défini comme le contenu de la vue hôte.
Implémentation du complément
Avec l'adaptateur côté complément et la vue du complément en place, le complément peut être implémenté par dérivation de la vue du complément, comme illustré dans le code suivant.
<addInViews:WPFAddInView
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
xmlns:addInViews="clr-namespace:AddInViews;assembly=AddInViews"
x:Class="WPFAddIn1.AddInUI">
<Grid>
<Button Click="clickMeButton_Click" Content="Click Me!" />
</Grid>
</addInViews:WPFAddInView>
Imports System.AddIn ' AddInAttribute
Imports System.Windows ' MessageBox, RoutedEventArgs
Imports AddInViews ' WPFAddInView
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
using System.AddIn; // AddInAttribute
using System.Windows; // MessageBox, RoutedEventArgs
using AddInViews; // WPFAddInView
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");
}
}
}
Il ressort de cet exemple un avantage intéressant de ce modèle : les développeurs de compléments ne doivent implémenter que le complément (puisqu'il s'agit également de l'UI), et non une classe et l'UI du complément.
Implémentation de l'application hôte
Avec 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 et acquérir une vue hôte du complément. 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(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)
// 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);
L'application hôte utilise le code du modèle de complément .NET Framework classique pour activer le complément, ce qui implicitement retourne la vue hôte à l'application hôte. L'application hôte affiche ensuite la vue hôte (qui est un UserControl) à partir d'un Grid.
Le code requis pour le traitement des interactions avec l'UI du complément s'exécute dans le domaine d'application de ce dernier. Ces interactions sont les suivantes :
Affichage du MessageBox.
Cette activité est complètement isolée de l'application hôte.