Como criar um suplemento que seja uma interface do usuário
Este exemplo mostra como criar um suplemento que é um Windows Presentation Foundation (WPF) que é hospedado por um aplicativo autônomo WPF.
O suplemento é uma interface do usuário que é um controle de usuário WPF. O conteúdo do controle de usuário é um único botão que, quando clicado, exibe uma caixa de mensagem. O aplicativo autônomo WPF hospeda a interface do usuário do suplemento como o conteúdo da janela principal do aplicativo.
Pré-requisitos
Este exemplo destaca as extensões WPF para o modelo de suplemento do .NET Framework que habilitam esse cenário e pressupõe o seguinte:
Conhecimento do modelo de suplemento do .NET Framework, incluindo pipeline, suplemento e desenvolvimento de host. Se você não estiver familiarizado com esses conceitos, consulte Suplementos e extensibilidade. Para ver um tutorial que demonstra a implementação de um pipeline, um suplemento e um aplicativo host, consulte Instrução passo a passo: criando um aplicativo extensível.
Conhecimento das extensões WPF para o modelo de suplemento do .NET Framework. Consulte Visão geral de suplementos do WPF.
Exemplo
Para criar um suplemento que seja uma interface do usuário do WPF, é necessário um código específico para cada segmento de pipeline, o suplemento e o aplicativo host.
Implementando o segmento de pipeline de contrato
Quando um suplemento é uma interface do usuário, o contrato para o suplemento deve implementar INativeHandleContract. No exemplo, implementa INativeHandleContract, IWPFAddInContract conforme mostrado no código a seguir.
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
Implementando o segmento de pipeline de exibição de suplemento
Como o suplemento é implementado como uma subclasse do tipo, o FrameworkElement modo de exibição do suplemento também deve subclasse FrameworkElement. O código a seguir mostra a exibição de suplemento do contrato, implementada como a 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
Aqui, a exibição do suplemento é derivada de UserControl. Consequentemente, a interface do usuário do suplemento também deve derivar do UserControl.
Implementando o segmento de pipeline do adaptador no lado do suplemento
Enquanto o contrato é um , o suplemento é um INativeHandleContractFrameworkElement (conforme especificado pelo segmento de pipeline de exibição de suplemento). Portanto, o deve ser convertido em um INativeHandleContract antes de cruzar o FrameworkElement limite de isolamento. Esse trabalho é executado pelo adaptador do lado do suplemento chamando ViewToContractAdapter, conforme mostrado no código a seguir.
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
No modelo de suplemento em que um suplemento retorna uma interface do usuário (consulte Criar um suplemento que retorna uma interface do usuário), o adaptador de suplemento converteu o FrameworkElement em um INativeHandleContract chamando ViewToContractAdapter. ViewToContractAdapter também deve ser chamado neste modelo, embora você precise implementar um método a partir do qual escrever o código para chamá-lo. Você faz isso substituindo QueryContract e implementando o código que chama ViewToContractAdapter se o código que está chamando QueryContract está esperando um INativeHandleContractarquivo . Nesse caso, o chamador será o adaptador do lado do host, que é abordado em uma seção mais adiante.
Observação
Você também precisa substituir QueryContract nesse modelo para habilitar a tabulação entre a interface do usuário do aplicativo host e a interface do usuário do suplemento. Para obter mais informações, consulte "Limitações de suplementos WPF" em Visão geral de Suplementos do WPF.
Como o adaptador do lado do suplemento implementa uma interface derivada do INativeHandleContract, você também precisa implementar GetHandleo , embora isso seja ignorado quando QueryContract for substituído.
Implementando o segmento de pipeline de exibição de host
Nesse modelo, o aplicativo host normalmente espera que a exibição do host seja uma FrameworkElement subclasse. O adaptador do lado do host deve converter o em um FrameworkElement após cruzar INativeHandleContract o INativeHandleContract limite de isolamento. Como um método não está sendo chamado pelo aplicativo host para obter o , a exibição do host deve "retornar" o contendo o , que o FrameworkElementFrameworkElement contém. Consequentemente, a exibição do host deve derivar de uma subclasse que FrameworkElement pode conter outras interfaces do usuário, como UserControl. O código a seguir mostra a exibição de host do contrato, implementada como a 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
Implementando o segmento de pipeline do adaptador no lado do host
Enquanto o contrato é um , o aplicativo host espera um INativeHandleContractUserControl (conforme especificado pela exibição do host). Consequentemente, o deve ser convertido em um FrameworkElement depois de cruzar o INativeHandleContract limite de isolamento, antes de ser definido como conteúdo da exibição do host (que deriva de UserControl).
O trabalho é executado pelo adaptador no lado do host, conforme mostrado no código a seguir.
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
Como você pode ver, o adaptador do lado do host adquire o chamando o método do adaptador do lado do QueryContract suplemento (este é o ponto em que o cruza o INativeHandleContractINativeHandleContract limite de isolamento).
Em seguida, o adaptador do lado do host converte o INativeHandleContract em um FrameworkElement chamando ContractToViewAdapter. Finalmente, o é definido como o FrameworkElement conteúdo da exibição do host.
Implementando o suplemento
Com o adaptador no lado do suplemento e a exibição de suplemento em vigor, o suplemento pode ser implementado derivando da exibição de suplemento, conforme mostrado no código a seguir.
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
Neste exemplo, você pode ver um benefício interessante desse modelo: os desenvolvedores de suplementos só precisam implementar o suplemento (já que também é a interface do usuário), em vez de uma classe de suplemento e uma interface do usuário de suplemento.
Implementando o aplicativo host
Com o adaptador do lado do host e a exibição de host criados, o aplicativo host pode usar o modelo de suplemento do .NET Framework para abrir o pipeline e adquirir uma exibição de host do suplemento. Essas etapas são mostradas no código a seguir.
// 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)
O aplicativo host usa o código de modelo de suplemento típico do .NET Framework para ativar o suplemento, que retorna implicitamente a exibição do host para o aplicativo host. O aplicativo host exibe subsequentemente a exibição do host (que é um ) de um UserControlGridarquivo .
O código para processar interações com a interface do usuário do suplemento é executado no domínio do aplicativo do suplemento. Essas ações incluem o seguinte:
Mostrando o MessageBoxarquivo .
Esta atividade é completamente isolada do aplicativo host.
Confira também
.NET Desktop feedback