Como: Criar um suplemento que retorna uma interface do usuário

Artigo
08/25/2010

This example shows how to create an add-in that returns a Windows Presentation Foundation (WPF) interface do usuário (UI) to a host WPF standalone application.

O suplemento retorna um UI Isto é um WPF controle de usuário. O conteúdo do controle de usuário é um único botão que, quando clicada, exibe uma caixa de mensagem. The WPF aplicativo autônomo hospeda o suplemento e exibe o controle de usuário (retornado pelo add-in) sistema autônomo o conteúdo da janela principal do aplicativo.

Pré-requisitos

Este exemplo realça o WPF extensões para o .NET Framework suplemento do modelo que permitem esse cenário e pressupõe o seguinte:

Conhecimento sobre o .NET Framework suplemento do modelo, incluindo pipeline, suplementos e desenvolvimento de host. Se não estão familiarizados com esses conceitos, consulte Adicionar-em Visão geral. Para obter um tutorial que demonstra a implementação de um pipeline, um suplemento e um aplicativo host, consulte Demonstra Passo a passo: Criando um aplicativo extensível.
Conhecimento sobre o WPF extensões para o .NET Framework modelo de suplemento, que pode ser encontrado aqui: Visão Geral dos Suplementos do Windows Presentation Foundation.

Exemplo

Para o exemplo completo que acompanha este tópico, consulte Adicionar-Em retorna um exemplo de interface do usuário.

Exemplo

To create an add-in that returns a WPF UI requires specific code for each pipeline segment, the add-in, and the host application.

Implementando o segmento de pipeline do contrato

Um método deve ser definido pelo contrato para retornar um UI, e seu valor de retorno deve ser do tipo INativeHandleContract. Isto é demonstrado pelo método GetAddInUI do contrato IWPFAddInContract no código seguinte.

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();
    }
}

Implementando o segmento de Pipeline View de suplemento

Pelo suplemento implementar o UIs que isso fornece como subclasses de FrameworkElement, o método da exibição do suplemento que se correlaciona com IWPFAddInView.GetAddInUI deve retornar um valor do tipo FrameworkElement. O seguinte código mostra a exibição do suplemento do contrato, implementado como uma interface.

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();
    }
}

Implementando o suplemento-side adaptador pipeline segmento

O método do contrato retorna um INativeHandleContract, mas o suplemento retorna um FrameworkElement (como especificado pela exibição do suplemento). Consequentemente, o FrameworkElement deve ser convertido em um INativeHandleContract antes de cruzar o limite de isolamento. O trabalho é executado pelo adaptador no lado do suplemento chamando ViewToContractAdapter, como exibido no código a seguir.

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;
        }
    }
}

Implementando o segmento de pipeline exibir host

Como o aplicativo de host irá exibir um FrameworkElement, o método no modo de host que se correlaciona com IWPFAddInHostView.GetAddInUI deve retornar um valor do tipo FrameworkElement. O seguinte código mostra o modo de host do contrato, implementado como uma interface.

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();
    }
}

Implementando o segmento de pipeline do adaptador no lado do host

O método do contrato retorna um INativeHandleContract, mas o aplicativo de host espera um FrameworkElement (como especificado pelo modo de host). Consequentemente, o INativeHandleContract deve ser convertido em um FrameworkElement antes de cruzar o limite de isolamento. O trabalho é executado pelo adaptador do lado do host chamandoContractToViewAdapter, como exibido no código seguinte.

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;
        }
    }
}

Implementando o Suplemento

Com o adaptador do lado do suplemento e a exibição de suplemento criados, o suplemento (WPFAddIn1.AddIn) deve implementar o método IWPFAddInView.GetAddInUI para retornar um objeto FrameworkElement (um UserControl nesse exemplo). A implementação do UserControl, AddInUI, é mostrado pelo seguinte código.

    <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");
        }
    }
}

A implementação do IWPFAddInView.GetAddInUI pelo suplemento simplesmente precisa retornar uma nova instância do AddInUI, conforme mostrado pelo seguinte código.

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();
        }
    }
}

Implementando o Aplicativo Host

Com o adaptador do lado do host e o modo de host criados, o aplicativo host pode utilizar o .NET Framework modelo de suplemento para abrir a pipeline, adquirir um modo de host do suplemento e chamar o método IWPFAddInHostView.GetAddInUI. Esses passos são mostrados no seguinte código:

// 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);

Consulte também

Tarefas

Adicionar-Em retorna um exemplo de interface do usuário

Conceitos

Adicionar-em Visão geral

Visão Geral dos Suplementos do Windows Presentation Foundation

Partilhar via