如何：创建返回 UI 的外接程序
更新：2007 年 11 月
本示例演示如何创建将 Windows Presentation Foundation (WPF)用户界面 (UI) 返回给宿主 WPF 独立应用程序的外接程序。
该外接程序返回一个 UI，该 UI 为 WPF 用户控件。该用户控件的内容为单个按钮，单击该按钮时将显示一个消息框。WPF 独立应用程序承载该外接程序，并将用户控件（由该外接程序返回）显示为主应用程序窗口的内容。
先决条件
本示例重点演示对 .NET Framework 外接程序模型进行的支持此方案的 WPF 扩展，并假设您具备以下条件：
了解 .NET Framework 外接程序模型的相关知识，包括管线、外接程序和宿主开发。如果您对这些概念不熟悉，请参见外接程序概述。有关演示如何实现管线、外接程序和宿主应用程序的教程，请参见演练：创建可扩展的应用程序。
了解 .NET Framework 外接程序模型的 WPF 扩展的相关知识，这些知识可在以下位置找到：Windows Presentation Foundation 外接程序概述。
示例
有关本主题附带的完整示例，请参见外接程序返回 UI 示例。
示例
要创建能够返回 WPFUI 的外接程序，需要为每个管线段、外接程序和宿主应用程序编写特定代码。
实现协定管线段
协定必须定义用于返回 UI 的方法，该方法的返回值必须为 INativeHandleContract 类型。下面代码中的 IWPFAddInContract 协定的 GetAddInUI 方法对此进行了演示。
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();
}
}
实现外接程序视图管线段
由于外接程序实现的UI 是作为 FrameworkElement 的子类提供的，因此与 IWPFAddInView.GetAddInUI 相关的外接程序视图的方法必须返回 FrameworkElement 类型的值。下面的代码演示实现为接口的协定外接程序视图。
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 完成，如下面的代码所示。
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 类型的值。下面的代码演示实现为接口的协定宿主视图。
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 完成，如下面的代码所示。
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>
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 的一个新实例，如下面的代码所示。
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)
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);