Gewusst wie: Erstellen eines Add-Ins, das eine Benutzeroberfläche zurückgibt
Dieses Beispiel zeigt, wie Sie ein Add-In erstellen, das eine Windows Presentation Foundation (WPF)-user interface (UI) für eine eigenständige WPF-Hostanwendung zurückgibt.
Das Add-In gibt eine UI zurück, bei der es sich um ein WPF-Benutzersteuerelement handelt. Der Inhalt des Benutzersteuerelements ist eine einzelne Schaltfläche, bei der ein Meldungsfeld angezeigt wird, wenn Benutzer darauf klicken. Die eigenständige WPF-Anwendung hostet das Add-In und zeigt das (vom Add-In zurückgegebene) Benutzersteuerelement als Inhalt des Hauptfensters der Anwendung an.
Vorbereitungsmaßnahmen
Dieses Beispiel zeigt die WPF-Erweiterungen des .NET Framework-Add-In-Modells, die dieses Szenario ermöglichen. Dabei wird Folgendes vorausgesetzt:
Kenntnis des .NET Framework-Add-In-Modells, einschließlich Pipeline-, Add-In- und Hostentwicklung. Wenn Sie mit diesen Begriffen nicht vertraut sind, finden Sie weitere Informationen unter Add-Ins und Erweiterbarkeit. Ein Lernprogramm, das die Implementierung einer Pipeline, eines Add-Ins und einer Hostanwendung veranschaulicht, finden Sie unter Exemplarische Vorgehensweise: Erstellen von erweiterbaren Anwendungen.
Kenntnis der WPF-Erweiterungen des .NET Framework-Add-In-Modells. Informationen finden Sie unter: Übersicht über WPF-Add-Ins.
Beispiel
Zum Erstellen eines Add-Ins, das eine WPF-UI zurückgibt, ist spezieller Code für die einzelnen Pipelinesegmente, das Add-In und die Hostanwendung erforderlich.
Implementieren des Vertragspipelinesegments
Im Vertrag muss eine Methode zum Zurückgeben einer UI festgelegt sein, und der Rückgabewert muss vom Typ INativeHandleContract sein. Dies wird durch die GetAddInUI-Methode des IWPFAddInContract-Vertrags im folgenden Code veranschaulicht.
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();
}
}
Implementieren des Add-In-Ansichtspipelinesegments
Da das Add-In die UIs implementiert, die es als Unterklassen von FrameworkElement bereitstellt, muss die Methode der Add-In-Ansicht, die mit IWPFAddInView.GetAddInUI verknüpft ist, einen Wert vom Typ FrameworkElement zurückgeben. Im folgenden Code wird die als Schnittstelle implementierte Add-In-Ansicht des Vertrags gezeigt.
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();
}
}
Implementieren des Add-In-seitigen Adapterpipelinesegments
Durch die Vertragsmethode wird INativeHandleContract zurückgegeben, das Add-In gibt jedoch FrameworkElement zurück (wie durch die Add-In-Ansicht festgelegt). Daher muss FrameworkElement vor dem Überschreiten der Isolationsgrenze in INativeHandleContract umgewandelt werden. Dieser Vorgang wird vom Add-In-seitigen Adapter durch Aufrufen von ViewToContractAdapter ausgeführt, wie im folgenden Code gezeigt.
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;
}
}
}
Implementieren des Host-Ansichtspipelinesegments
Da die Hostanwendung FrameworkElement anzeigt, muss die Methode der Hostansicht, die mit IWPFAddInHostView.GetAddInUI verknüpft ist, einen Wert vom Typ FrameworkElement zurückgeben. Im folgenden Code wird die als Schnittstelle implementierte Hostansicht des Vertrags gezeigt.
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();
}
}
Implementieren des hostseitigen Adapterpipelinesegments
Durch die Vertragsmethode wird INativeHandleContract zurückgegeben, die Hostanwendung erwartet jedoch FrameworkElement (wie durch die Hostansicht festgelegt). Daher muss INativeHandleContract nach dem Überschreiten der Isolationsgrenze in FrameworkElement umgewandelt werden. Dieser Vorgang wird vom hostseitigen Adapter durch Aufrufen von ContractToViewAdapter ausgeführt, wie im folgenden Code gezeigt.
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;
}
}
}
Implementieren des Add-Ins
Wenn der Add-In-seitige Adapter und die Add-In-Ansicht erstellt sind, muss das Add-In (WPFAddIn1.AddIn) die IWPFAddInView.GetAddInUI-Methode implementieren, um ein FrameworkElement-Objekt zurückzugeben (in diesem Beispiel UserControl). Der folgende Code zeigt die Implementierung von UserControl (AddInUI).
<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");
}
}
}
Bei der Implementierung von IWPFAddInView.GetAddInUI über das Add-In muss lediglich eine neue Instanz von AddInUI zurückgegeben werden. Dies ist im folgenden Code gezeigt.
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();
}
}
}
Implementieren der Hostanwendung
Sind der hostseitige Adapter und die Hostansicht erstellt, kann die Hostanwendung das Add-In-Modell von .NET Framework verwenden, um die Pipeline zu öffnen, eine Hostansicht des Add-Ins abzurufen und die IWPFAddInHostView.GetAddInUI-Methode aufzurufen. Diese Schritte werden im folgenden Code gezeigt.
' 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);