Aracılığıyla paylaş

Kılavuz: Kullanıcı Arayüzü Olan bir Add-In Oluşturma

Bu örnekte, tek başına WPF uygulaması tarafından barındırılan bir Windows Presentation Foundation (WPF) olan bir eklentinin nasıl oluşturulacağı gösterilmektedir.

Eklenti, WPF kullanıcı denetimi olan bir kullanıcı arabirimidir. Kullanıcı denetiminin içeriği, tıklandığında bir ileti kutusu görüntüleyen tek bir düğmedir. WPF tek başına uygulaması, ana uygulama penceresinin içeriği olarak eklenti kullanıcı arabirimini barındırıyor.

Önkoşullar

Bu örnek, bu senaryoyu etkinleştiren .NET Framework eklenti modelinin WPF uzantılarını vurgular ve aşağıdakileri varsayar:

Örnek

WPF kullanıcı arabirimi olan bir eklenti oluşturmak için her işlem hattı kesimi, eklenti ve konak uygulaması için belirli bir kod gerekir.

Sözleşme Boru Hattı Segmentini Uygulamak

Eklenti bir kullanıcı arabirimi olduğunda, eklentinin sözleşmesi INativeHandleContractuygulamalıdır. Örnekte, IWPFAddInContract aşağıdaki kodda gösterildiği gibi INativeHandleContractuygular.

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

Add-In Görünüm İşlem Hattı Segmentini Uygulama

Eklenti, FrameworkElement türünün alt sınıfı olarak uygulandığından, eklenti görünümünün de FrameworkElementalt sınıfı olmalıdır. Aşağıdaki kod, WPFAddInView sınıfı olarak uygulanan sözleşmenin eklenti görünümünü gösterir.

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

Burada, eklenti görünümü UserControl'dan türetilmiştir. Sonuç olarak, eklenti kullanıcı arabirimi aynı zamanda UserControl'dan türetilmelidir.

Add-In-Side Adaptör İşlem Hattı Kesitini Uygulama

Sözleşme bir INativeHandleContractolsa da, ek bileşen, eklenti görünüm işlem hattı parçası tarafından belirtildiği gibi bir FrameworkElement'dir. Bu nedenle, yalıtım sınırını aşmadan önce FrameworkElement bir INativeHandleContract dönüştürülmelidir. Bu işlem, aşağıdaki kodda gösterildiği gibi, eklenti tarafındaki bağdaştırıcı tarafından ViewToContractAdapterçağrılarak gerçekleştirilir.

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

Eklentinin bir kullanıcı arabirimi döndürdüğü eklenti modelinde (bkz. Kullanıcı ArabirimiDöndüren Add-In Oluşturma ), eklenti bağdaştırıcısı çağırarak bir dönüştürdü. ViewToContractAdapter bu modelde de çağrılmalıdır, ancak kodu çağıracak şekilde yazabileceğiniz bir yöntem uygulamanız gerekir. QueryContract'ı geçersiz kılarak ve ViewToContractAdapter'yi çağıran kodun bir QueryContractbeklemesi durumunda INativeHandleContract'i çağıran kodu uygulayarak bunu yaparsınız. Bu durumda çağıran, sonraki bir alt bölümde ele alınacak olan ana bilgisayar tarafı bağdaştırıcısı olacaktır.

Uyarı

Ayrıca konak uygulama kullanıcı arabirimi ile eklenti kullanıcı arabirimi arasında sekme oluşturmayı etkinleştirmek için bu modeldeki QueryContract geçersiz kılmanız gerekir. Daha fazla bilgi için bkz. WPF Add-Ins Genel Bakış"WPF Add-In Sınırlamaları".

Eklenti tarafı bağdaştırıcısı INativeHandleContract'den türetilen bir arabirim uyguladığından, bu nedenle GetHandle'i de uygulamanız gerekir, ancak QueryContract geçersiz kılındığında bu yoksayılır.

Ana Bilgisayar Görünümünü İşlem Hattı Segmenti Uygulama

Bu modelde, ana uygulama genellikle ana görünümün FrameworkElement alt sınıfı olmasını bekler. Konak tarafı bağdaştırıcısı, INativeHandleContract yalıtım sınırını aştıktan sonra FrameworkElement'ı INativeHandleContract'e dönüştürmelidir. FrameworkElementalmak için konak uygulama tarafından bir yöntem çağrılmadığından, konak görünümü bunu içererek FrameworkElement "döndürmelidir". Sonuç olarak, ana görünüm FrameworkElementgibi diğer UI'leri içerebilen bir UserControl alt sınıfından türetilmelidir. Aşağıdaki kod, WPFAddInHostView sınıfı olarak uygulanan sözleşmenin ana bilgisayar görünümünü gösterir.

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

Host-Side Bağdaştırıcısı Boru Hattı Segmentini Uygulama

Sözleşme bir INativeHandleContractolsa da, ana bilgisayar uygulaması bir UserControl bekler (ana bilgisayar görünümü tarafından belirtildiği gibi). Sonuç olarak, yalıtım sınırını geçtikten sonra INativeHandleContract, FrameworkElement olarak dönüştürülmeli ve daha sonra (UserControl'den türeyen) konak görünümünün içeriği olarak ayarlanmalıdır.

Bu çalışma, aşağıdaki kodda gösterildiği gibi konak tarafındaki bağdaştırıcı tarafından gerçekleştirilir.

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

Gördüğünüz gibi, konak tarafı bağdaştırıcısı, eklenti tarafı bağdaştırıcının INativeHandleContract yöntemini çağırarak QueryContract alır (bu, INativeHandleContract'nin yalıtım sınırını geçtiği noktadır).

Konak tarafı bağdaştırıcısı daha sonra INativeHandleContract'yi çağırarak FrameworkElement'ı ContractToViewAdapter'e dönüştürür. Son olarak, FrameworkElement konak görünümünün içeriği olarak ayarlanır.

Add-In uygulaması yapmak

Eklenti tarafı bağdaştırıcısı ve eklenti görünümü kurulduktan sonra, eklenti aşağıdaki kodda gösterildiği gibi eklenti görünümünden türeterek uygulanabilir.

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

Bu örnekte, bu modelin ilginç avantajlarından birini görebilirsiniz: eklenti geliştiricilerinin hem eklenti sınıfı hem de eklenti kullanıcı arabirimi yerine yalnızca eklentiyi (kullanıcı arabirimi olduğu için) uygulaması gerekir.

Ana Uygulamayı Gerçekleştirme

Sunucu tarafı adaptörü ve sunucu görünümü oluşturulduğunda, sunucu uygulaması işlem hattını açmak ve eklentinin sunucu görünümünü elde etmek için .NET Framework eklenti modelini kullanabilir. Bu adımlar aşağıdaki kodda gösterilmiştir.

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

Konak uygulaması, eklentiyi etkinleştirmek için tipik .NET Framework eklenti modeli kodunu kullanır ve bu da konak görünümünü örtük olarak konak uygulamasına döndürür. Konak uygulaması daha sonra bir UserControlana bilgisayar görünümünü bir Grid'den görüntüler.

Eklenti kullanıcı arabirimiyle etkileşimleri işlemeye yönelik kod, eklentinin uygulama etki alanında çalışır. Bu etkileşimler şunları içerir:

Bu faaliyet ana uygulamadan tamamen yalıtılmıştır.

Ayrıca bakınız

  • Last updated on