Procedura: creare un componente aggiuntivo che costituisce un'interfaccia utente
In questo esempio viene illustrato come creare un componente aggiuntivo che costituisce un'user interface (UI) di Windows Presentation Foundation (WPF) ed è ospitato da un'applicazione WPF autonoma.
Il componente aggiuntivo è un'UI che rappresenta un controllo utente di WPF. Il contenuto del controllo utente è costituito da un unico pulsante che consente di visualizzare una finestra di messaggio. L'UI del componente aggiuntivo viene ospitata come contenuto della finestra principale dell'applicazione WPF autonoma.
Prerequisiti
In questo esempio vengono evidenziate le estensioni WPF al modello di componente aggiuntivo .NET Framework responsabile dell'attivazione di tale scenario e si presuppongono le seguenti condizioni:
Conoscenza del modello di componente aggiuntivo .NET Framework, incluso lo sviluppo di pipeline, componenti aggiuntivi e host. Per informazioni su questi concetti, vedere Componenti aggiuntivi ed estensibilità. Per un'esercitazione in cui venga illustrata l'implementazione di una pipeline, un componente aggiuntivo e un'applicazione host, vedere Procedura dettagliata: creazione di un'applicazione estendibile.
Conoscenza delle estensioni WPF al modello di componente aggiuntivo .NET Framework, disponibile in: Cenni preliminari sui componenti aggiuntivi di WPF.
Esempio
La creazione di un componente aggiuntivo che costituisce un'UI di WPF richiede l'utilizzo di codice specifico per ciascun segmento di pipeline, per il componente aggiuntivo e per l'applicazione host.
Implementazione del segmento di pipeline di contratto
Quando un componente aggiuntivo rappresenta un'UI, il contratto per tale componente deve implementare INativeHandleContract. Nell'esempio, IWPFAddInContract implementa INativeHandleContract come illustrato nel codice seguente.
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 {}
}
Implementazione del segmento di pipeline di visualizzazione del componente aggiuntivo
Poiché il componente aggiuntivo viene implementato come sottoclasse del tipo FrameworkElement, anche la visualizzazione del componente deve creare una sottoclasse di FrameworkElement. Nel codice seguente viene illustrata la visualizzazione del componente aggiuntivo del contratto, implementata come 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 { }
}
In questo caso, la visualizzazione del componente aggiuntivo deriva da UserControl. Di conseguenza, anche l'UI del componente aggiuntivo deve derivare da UserControl.
Implementazione del segmento di pipeline dell'adattatore sul lato componente aggiuntivo
Il contratto rappresenta INativeHandleContract, mentre il componente aggiuntivo rappresenta FrameworkElement, come specificato dal segmento di pipeline della visualizzazione del componente aggiuntivo. Sarà pertanto necessario convertire FrameworkElement in INativeHandleContract prima di oltrepassare il limite di isolamento. La conversione viene eseguita dall'adattatore sul lato componente aggiuntivo mediante una chiamata a ViewToContractAdapter, come illustrato nel codice seguente.
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();
}
}
}
Nel modello di componente aggiuntivo in cui il componente restituisce un'UI (vedere Procedura: creare un componente aggiuntivo che restituisce un'interfaccia utente), l'adattatore del componente aggiuntivo ha eseguito la conversione di FrameworkElement in INativeHandleContract mediante una chiamata a ViewToContractAdapter. In questo modello occorre chiamare anche ViewToContractAdapter, benché sia necessario implementare un metodo dal quale scrivere il codice per la chiamata. A tale scopo occorre eseguire l'override di QueryContract e implementare il codice che chiama ViewToContractAdapter, nel caso in cui il codice che effettua la chiamata a QueryContract preveda un oggetto INativeHandleContract. In questo caso il chiamante sarà l'adattatore sul lato host, trattato in una sottosezione successiva.
.gif "Nota") Nota |
|---|
In questo modello occorre inoltre eseguire l'override di QueryContract per consentire il passaggio dall'UI dell'applicazione host all'UI del componente aggiuntivo e viceversa.Per ulteriori informazioni, vedere "Limitazioni dei componenti aggiuntivi WPF" in Cenni preliminari sui componenti aggiuntivi di WPF. |
Poiché l'adattatore sul lato componente aggiuntivo implementa un'interfaccia che deriva da INativeHandleContract, è necessario implementare anche GetHandle, nonostante questo venga ignorato durante l'override di QueryContract.
Implementazione del segmento di pipeline di visualizzazione host
In questo modello, nell'applicazione host è previsto in genere che la visualizzazione host sia una sottoclasse di FrameworkElement. L'adattatore sul lato host deve convertire INativeHandleContract in FrameworkElement una volta che INativeHandleContract abbia oltrepassato il limite di isolamento. Dal momento che l'applicazione host non chiama alcun metodo per ottenere FrameworkElement, la visualizzazione host deve "restituire" l'oggetto FrameworkElement contenendolo. Di conseguenza, la visualizzazione host deve derivare da una sottoclasse di FrameworkElement in grado di contenere altre UIs, ad esempio UserControl. Nel codice riportato di seguito viene illustrata la visualizzazione host del contratto, implementata come 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 { }
}
Implementazione del segmento di pipeline dell'adattatore sul lato host
Il contratto rappresenta INativeHandleContract, mentre l'applicazione host prevede UserControl, come specificato dalla visualizzazione host. Di conseguenza, l'oggetto INativeHandleContract deve essere convertito in FrameworkElement dopo avere oltrepassato il limite di isolamento e prima di essere impostato come contenuto della visualizzazione host, derivante da UserControl.
La conversione viene eseguita dall'adattatore sul lato host, come illustrato nel codice seguente.
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;
}
}
}
Come si può notare, l'adattatore sul lato host acquisisce INativeHandleContract mediante una chiamata al metodo QueryContract dell'adattatore sul lato componente aggiuntivo; questo è il punto in cui INativeHandleContract oltrepassa il limite di isolamento.
L'adattatore sul lato host converte quindi INativeHandleContract in FrameworkElement mediante una chiamata a ContractToViewAdapter. Infine, FrameworkElement viene impostato come contenuto della visualizzazione host.
Implementazione del componente aggiuntivo
Una volta creati l'adattatore sul lato componente aggiuntivo e la visualizzazione del componente, questo può essere implementato mediante derivazione dalla relativa visualizzazione, come illustrato nel codice seguente.
<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");
}
}
}
Dall'esempio risulta evidente un interessante vantaggio di questo modello: gli sviluppatori di componenti aggiuntivi devono unicamente implementare il componente aggiuntivo, dal momento che rappresenta anche l'UI, anziché una classe e un'UI del componente in questione.
Implementazione dell'applicazione host
Una volta creato l'adattatore sul lato host e la visualizzazione host, nell'applicazione host è possibile utilizzare il modello di componente aggiuntivo .NET Framework per aprire la pipeline e acquisire una visualizzazione host del componente aggiuntivo. Nel codice riportato di seguito vengono illustrati i diversi passaggi.
' 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);
In genere, nell'applicazione host viene utilizzato un codice tipico del modello di componente aggiuntivo .NET Framework per l'attivazione del componente aggiuntivo, il quale restituisce implicitamente la visualizzazione host all'applicazione. Successivamente, nell'applicazione host viene visualizzata la visualizzazione host, ovvero un oggetto UserControl, da un oggetto Grid.
Il codice di elaborazione delle interazioni con l'UI del componente aggiuntivo viene eseguito nel dominio dell'applicazione di tale componente. Di seguito vengono riportati alcuni esempi di interazione:
Visualizzazione di MessageBox.
Questa attività è completamente isolata dall'applicazione host.