如何：创建返回 UI 的外接程序
本示例演示如何创建将 Windows Presentation Foundation (WPF) user interface (UI) 返回给宿主 WPF 独立应用程序的外接程序。
该外接程序返回一个 UI，该 UI 为 WPF 用户控件。 该用户控件的内容为单个按钮，单击该按钮时将显示一个消息框。 WPF 独立应用程序承载该外接程序，并将用户控件（由该外接程序返回）显示为主应用程序窗口的内容。
先决条件
本示例重点演示对 .NET Framework 外接程序模型进行的支持此方案的 WPF 扩展，并假设您具备以下条件：
了解 .NET Framework 外接程序模型的相关知识，包括管线、外接程序和宿主开发。 如果您对这些概念不熟悉，请参见外接程序和扩展性。 有关演示如何实现管线、外接程序和宿主应用程序的教程，请参见演练：创建可扩展的应用程序。
了解 .NET Framework 外接程序模型的 WPF 扩展的相关知识，这些知识可在以下位置找到：WPF 外接程序概述。
示例
要创建能够返回 WPF UI 的外接程序，需要为每个管线段、外接程序和宿主应用程序编写特定代码。
实现协定管线段
协定必须定义用于返回 UI 的方法，该方法的返回值必须为 INativeHandleContract 类型。 下面代码中的 IWPFAddInContract 协定的 GetAddInUI 方法对此进行了演示。
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();
}
}
实现外接程序视图管线段
由于外接程序实现的UIs 是作为 FrameworkElement 的子类提供的，因此与 IWPFAddInView.GetAddInUI 相关的外接程序视图的方法必须返回 FrameworkElement 类型的值。 下面的代码演示实现为接口的协定外接程序视图。
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();
}
}
实现外接程序端适配器管线段
协定方法返回 INativeHandleContract，而外接程序返回 FrameworkElement（如外接程序视图指定的那样）。 因此，在越过隔离边界之前，必须将 FrameworkElement 转换为 INativeHandleContract。 此任务由外接程序端适配器通过调用 ViewToContractAdapter 完成，如下面的代码所示。
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;
}
}
}
实现宿主视图管线段
由于宿主应用程序将显示 FrameworkElement，因此与 IWPFAddInHostView.GetAddInUI 相关的宿主视图的方法必须返回 FrameworkElement 类型的值。 下面的代码演示实现为接口的协定宿主视图。
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();
}
}
实现宿主端适配器管线段
协定方法返回 INativeHandleContract，而宿主应用程序需要 FrameworkElement（如宿主视图指定的那样）。 因此，在越过隔离边界之后，必须将 INativeHandleContract 转换为 FrameworkElement。 此任务由宿主端适配器通过调用 ContractToViewAdapter 完成，如下面的代码所示。
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;
}
}
}
实现外接程序
创建外接程序端适配器和外接程序视图后，外接程序 (WPFAddIn1.AddIn) 必须实现 IWPFAddInView.GetAddInUI 方法以返回 FrameworkElement 对象（在本示例中为 UserControl）。 下面的代码演示 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");
}
}
}
外接程序的 IWPFAddInView.GetAddInUI 实现只需要返回 AddInUI 的一个新实例，如下面的代码所示。
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();
}
}
}
实现宿主应用程序
创建宿主端适配器和宿主视图后，宿主应用程序就可以使用 .NET Framework 外接程序模型来打开管线，获得外接程序宿主视图，也可以调用 IWPFAddInHostView.GetAddInUI 方法。 下面的代码演示这些步骤。
' 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);