Postupy: Vytvoření Add-In, které je uživatelské rozhraní

Tento příklad ukazuje, jak vytvořit doplněk, který je windows Presentation Foundation (WPF), který je hostován samostatnou aplikací WPF.

Doplněk je uživatelské rozhraní, které je uživatelským ovládacím prvkem WPF. Obsah uživatelského ovládacího prvku je jediné tlačítko, které po kliknutí zobrazí okno se zprávou. Samostatná aplikace WPF hostuje uživatelské rozhraní doplňku jako obsah hlavního okna aplikace.

požadavky

Tento příklad zvýrazňuje rozšíření WPF pro model plug-in .NET Framework, která umožňují tento scénář, a předpokládá následující:

• Znalost modelu doplňků pro .NET Framework, včetně vývoje kanálu, doplňku a hostitele. Pokud tyto koncepty neznáte, přečtěte si doplňky a rozšiřitelnost. Pro podrobný návod, který ukazuje implementaci pipeline, doplňku a hostitelské aplikace, viz Návod: Vytvoření rozšiřitelné aplikace.

• Znalost rozšíření WPF pro model doplňků v rámci .NET Framework. Viz přehled Add-Ins WPF.

Příklad

Pokud chcete vytvořit doplněk, který je uživatelským rozhraním WPF, vyžaduje specifický kód pro každý segment kanálu, doplněk a hostitelskou aplikaci.

Implementace segmentu potrubí kontraktu

Pokud je doplněk uživatelským rozhraním, musí kontrakt doplňku implementovat INativeHandleContract. V příkladu IWPFAddInContract implementuje INativeHandleContract, jak je znázorněno v následujícím kódu.

using System.AddIn.Contract;
using System.AddIn.Pipeline;

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

Imports System.AddIn.Contract
Imports System.AddIn.Pipeline

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

Implementace segmentu kanálu zobrazení Add-In

Vzhledem k tomu, že je doplněk implementován jako podtřída typu FrameworkElement, musí zobrazení doplňku být také podtřídou FrameworkElement. Následující kód ukazuje zobrazení doplňku smlouvy, implementovaná jako třída WPFAddInView.

using System.AddIn.Pipeline;
using System.Windows.Controls;

namespace AddInViews
{
    /// <summary>
    /// Defines the add-in's view of the contract.
    /// </summary>
    [AddInBase]
    public class WPFAddInView : UserControl { }
}

Imports System.AddIn.Pipeline
Imports System.Windows.Controls

Namespace AddInViews
    ''' <summary>
    ''' Defines the add-in's view of the contract.
    ''' </summary>
    <AddInBase>
    Public Class WPFAddInView
        Inherits UserControl
    End Class
End Namespace

Zde je zobrazení doplňku odvozeno z UserControl. Uživatelské rozhraní doplňku by proto mělo být odvozeno také z UserControl.

Implementace úseku potrubí adaptéru doplňkuIn-Side

Zatímco kontrakt je INativeHandleContract, doplněk je FrameworkElement (jak je specifikováno segmentem kanálu zobrazení doplňku). Proto musí být FrameworkElement před přechodem hranice izolace převedeny na INativeHandleContract. Tuto práci provádí adaptér na straně doplňku voláním ViewToContractAdapter, jak ukazuje následující kód.

using System;
using System.AddIn.Contract;
using System.AddIn.Pipeline;
using System.Security.Permissions;

using AddInViews;
using Contracts;

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 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, that is, 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>
        public IntPtr GetHandle()
        {
            return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView).GetHandle();
        }
    }
}

Imports System
Imports System.AddIn.Contract
Imports System.AddIn.Pipeline
Imports System.Security.Permissions

Imports AddInViews
Imports Contracts

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 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, that is, overriding ContractBase.QueryContract, 
        ''' as shown above.
        ''' </summary>
        Public Function GetHandle() As IntPtr Implements INativeHandleContract.GetHandle
            Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView).GetHandle()
        End Function

    End Class
End Namespace

V modelu doplňku, ve kterém doplněk vrátí uživatelské rozhraní (viz Vytvoření Add-In, který vrátí uživatelské rozhraní), adaptér doplňku převedl FrameworkElement na INativeHandleContract voláním ViewToContractAdapter. ViewToContractAdapter musí být volána také v tomto modelu, i když potřebujete implementovat metodu, ze které chcete napsat kód, který ho má volat. Provedete to tak, že přepíšete QueryContract a implementujete kód, který volá ViewToContractAdapter, pokud kód, který volá QueryContract, očekává INativeHandleContract. V tomto případě bude volající adaptér na straně hostitele, který je pokryt v následujícím pododdíle.

Poznámka

Musíte také přepsat QueryContract v tomto modelu, abyste mohli povolit přepínání (tabbing) mezi uživatelským rozhraním hostitelské aplikace a uživatelským rozhraním doplňků. Další informace najdete v tématu „WPF Přehled: Omezení Add-In“ v WPF Add-Ins.

Vzhledem k tomu, že adaptér doplňku implementuje rozhraní odvozené z INativeHandleContract, je nutné implementovat také GetHandle, ačkoli je to ignorováno, když je QueryContract přepsáno.

Implementace segmentu kanálu zobrazení hostitele

V tomto modelu hostitelská aplikace obvykle očekává, že zobrazení aplikace hostitele bude podtřídou FrameworkElement. Adaptér na straně hostitele musí převést INativeHandleContract na FrameworkElement poté, co INativeHandleContract překročí hranici izolace. Vzhledem k tomu, že metoda není volána hostitelskou aplikací, aby získala FrameworkElement, musí zobrazení hostitele "vrátit" FrameworkElement tím, že ho obsahuje. V důsledku toho musí zobrazení hostitele odvodit z podtřídy FrameworkElement, která může obsahovat jiná uživatelská rozhraní, například UserControl. Následující kód ukazuje pohled hostitele kontraktu, implementovaný jako třída WPFAddInHostView.

using System.Windows.Controls;

namespace HostViews
{
    /// <summary>
    /// Defines the host's view of the add-in
    /// </summary>
    public class WPFAddInHostView : UserControl { }
}

Imports System.Windows.Controls

Namespace HostViews
    ''' <summary>
    ''' Defines the host's view of the add-in
    ''' </summary>
    Public Class WPFAddInHostView
        Inherits UserControl
    End Class
End Namespace

Implementace segmentu potrubí adaptéru Host-Side

I když je smlouva INativeHandleContract, hostitelská aplikace očekává UserControl (jak je určeno zobrazením hostitelské aplikace). V důsledku toho musí být INativeHandleContract převedeno na FrameworkElement po překročení hranice izolace, než je nastaveno jako obsah hostitelského zobrazení, které je odvozeno od UserControl.

Tuto práci provádí adaptér na straně hostitele, jak je znázorněno v následujícím kódu.

using System.AddIn.Contract;
using System.AddIn.Pipeline;
using System.Windows;

using Contracts;
using HostViews;

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

Imports System.AddIn.Contract
Imports System.AddIn.Pipeline
Imports System.Windows

Imports Contracts
Imports HostViews

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

Jak vidíte, adaptér na straně hostitele získá INativeHandleContract voláním metody QueryContract adaptéru doplňku (to je bod, kde INativeHandleContract překročí hranici izolace).

Adaptér na straně hostitele pak převede INativeHandleContract na FrameworkElement voláním ContractToViewAdapter. Nakonec se FrameworkElement nastaví jako obsah zobrazení hostitele.

Implementace Add-In

S adaptérem přídavného modulu a zobrazením přídavného modulu na místě je možné doplněk implementovat odvozením ze zobrazení přídavného modulu, jak je znázorněno v následujícím kódu.

using System.AddIn;
using System.Windows;

using AddInViews;

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

Imports System.AddIn
Imports System.Windows

Imports AddInViews

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

V tomto příkladu můžete vidět jednu zajímavou výhodu tohoto modelu: vývojáři doplňků potřebují implementovat doplněk (protože je to také uživatelské rozhraní), a ne jak třídu doplňku, tak i uživatelské rozhraní doplňku.

Implementace hostitelské aplikace

S vytvořeným adaptérem na straně hostitele a zobrazením hostitelské strany může hostitelská aplikace použít model doplňků .NET Framework k otevření potrubí a získání hostitelského pohledu na modul. Tyto kroky jsou uvedené v následujícím kódu.

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

' 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)

Hostitelská aplikace používá k aktivaci doplňku typický kód doplňku rozhraní .NET Framework, který implicitně vrací zobrazení hostitele do hostitelské aplikace. Hostitelská aplikace následně zobrazí zobrazení hostitele (což je UserControl) z Grid.

Kód pro zpracování interakcí s uživatelským rozhraním doplňku běží v doméně aplikace doplňku. Mezi tyto interakce patří:

• Zpracování události ButtonClick

• Zobrazuje se MessageBox.

Tato aktivita je zcela izolovaná od hostitelské aplikace.

Viz také

• doplňky a rozšiřitelnost
• WPF Add-Ins přehled