Bagikan melalui

Cara: Membuat Add-In Menjadi UI

Contoh ini menunjukkan cara membuat add-in yang merupakan Windows Presentation Foundation (WPF) yang dihosting oleh aplikasi mandiri WPF.

Add-in adalah antarmuka pengguna (UI) yang berupa kontrol pengguna WPF. Konten kontrol pengguna adalah satu tombol yang, saat diklik, menampilkan kotak pesan. Aplikasi mandiri WPF menghosting UI add-in sebagai konten jendela utama aplikasi.

Prasyarat

Contoh ini menyoroti ekstensi WPF ke model add-in .NET Framework yang mengaktifkan skenario ini, dan mengasumsikan hal berikut:

  • Pengetahuan tentang model add-in .NET Framework, termasuk pipeline (alur kerja), pengembangan add-in, dan pengembangan lingkungan host. Jika Anda tidak terbiasa dengan konsep-konsep ini, lihat Tambahan dan Keterluasan. Untuk tutorial yang menunjukkan implementasi alur, add-in, dan aplikasi host, lihat panduan : Membuat Aplikasi yang Dapat Diperluas.

  • Pengetahuan tentang ekstensi WPF ke model add-in .NET Framework. Lihat WPF Add-Ins Gambaran Umum.

Contoh

Untuk membuat add-in yang merupakan WPF UI memerlukan kode tertentu untuk setiap segmen alur, add-in, dan aplikasi host.

Menerapkan Segmen Jalur Kontrak

Ketika add-in merupakan sebuah antarmuka pengguna, kontrak untuk add-in tersebut harus menerapkan INativeHandleContract. Dalam contoh, IWPFAddInContract mengimplementasikan INativeHandleContract, seperti yang ditunjukkan dalam kode berikut.

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

Menerapkan Segmen Alur Tampilan Add-In

Karena add-in diimplementasikan sebagai subkelas dari jenis FrameworkElement, tampilan add-in juga harus subkelas FrameworkElement. Kode berikut menunjukkan tampilan add-in kontrak, yang diimplementasikan sebagai kelas 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

Di sini, tampilan add-in berasal dari UserControl. Akibatnya, UI add-in juga harus berasal dari UserControl.

Menerapkan Segmen Alur Adaptor Add-In-Side

Meskipun kontrak adalah INativeHandleContract, add-in adalah FrameworkElement (seperti yang ditentukan oleh segmen alur tampilan add-in). Oleh karena itu, FrameworkElement harus dikonversi ke INativeHandleContract sebelum melewati batas isolasi. Pekerjaan ini dilakukan oleh adaptor sisi add-in dengan memanggil ViewToContractAdapter, seperti yang ditunjukkan dalam kode berikut.

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

Dalam model add-in di mana add-in mengembalikan UI (lihat Membuat Add-In yang Mengembalikan UI), adaptor add-in mengonversi FrameworkElement ke INativeHandleContract dengan memanggil ViewToContractAdapter. ViewToContractAdapter juga harus dipanggil dalam model ini, meskipun Anda perlu menerapkan metode untuk menulis kode untuk memanggilnya. Anda melakukan ini dengan mengambil alih QueryContract dan menerapkan kode yang memanggil ViewToContractAdapter jika kode yang memanggil QueryContract mengharapkan INativeHandleContract. Dalam hal ini, pemanggil akan menjadi adaptor sisi host, yang dibahas dalam subbagian berikutnya.

Nota

Anda juga perlu mengambil alih QueryContract dalam model ini untuk mengaktifkan tab antara antarmuka pengguna aplikasi host dan UI add-in. Untuk informasi selengkapnya, lihat "Batasan Add-In WPF" di Gambaran Umum Add-Ins WPF.

Karena adaptor add-in-side mengimplementasikan antarmuka turunan dari INativeHandleContract, Anda juga perlu menerapkan GetHandle, walaupun ini diabaikan saat QueryContract ditimpa.

Menerapkan Segmen Alur Tampilan Host

Dalam model ini, aplikasi host biasanya mengharapkan tampilan host menjadi subkelas FrameworkElement. Adaptor sisi host harus mengonversi INativeHandleContract menjadi FrameworkElement setelah INativeHandleContract melewati batas isolasi. Karena metode ini tidak dipanggil oleh aplikasi host untuk mendapatkan FrameworkElement, tampilan host harus 'mengembalikan' FrameworkElement dengan cara menampungnya. Akibatnya, tampilan host harus berasal dari subkelas FrameworkElement yang dapat berisi UI lain, seperti UserControl. Kode berikut menunjukkan antarmuka host kontrak, yang diimplementasikan sebagai kelas 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

Menerapkan Segmen Alur Adaptor Host-Side

Meskipun kontrak adalah INativeHandleContract, aplikasi induk mengharapkan UserControl (seperti yang ditentukan oleh tampilan induk). Akibatnya, INativeHandleContract harus dikonversi ke FrameworkElement setelah melewati batas isolasi, sebelum ditetapkan sebagai konten tampilan host (yang berasal dari UserControl).

Pekerjaan ini dilakukan oleh adaptor sisi host, seperti yang ditunjukkan dalam kode berikut.

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

Seperti yang Anda lihat, adaptor sisi host memperoleh INativeHandleContract dengan memanggil metode QueryContract adaptor add-in-side (ini adalah titik di mana INativeHandleContract melewati batas isolasi).

Adaptor sisi host kemudian mengonversi INativeHandleContract menjadi FrameworkElement dengan memanggil ContractToViewAdapter. Terakhir, FrameworkElement diatur sebagai konten tampilan host.

Menerapkan Add-In

Dengan adaptor add-in-side dan tampilan add-in di tempat, add-in dapat diimplementasikan dengan turunan dari tampilan add-in, seperti yang ditunjukkan dalam kode berikut.

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

Dari contoh ini, Anda dapat melihat satu manfaat menarik dari model ini: pengembang add-in hanya perlu menerapkan add-in (karena ini adalah UI juga), daripada kelas add-in dan UI add-in.

Menerapkan Aplikasi Host

Dengan adaptor sisi host dan tampilan host yang sudah dibuat, aplikasi host dapat menggunakan model add-in .NET Framework untuk membuka pipeline dan memperoleh tampilan host dari add-in. Langkah-langkah ini ditampilkan dalam kode berikut.

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

Aplikasi host menggunakan kode model add-in .NET Framework umum untuk mengaktifkan add-in, yang secara implisit mengembalikan tampilan host ke aplikasi host. Aplikasi host kemudian menampilkan tampilan host (yang merupakan UserControl) dari Grid.

Kode yang memproses interaksi dengan UI add-in berjalan dalam domain aplikasi add-in. Interaksi ini mencakup hal-hal berikut:

Aktivitas ini sepenuhnya terisolasi dari aplikasi host.

Lihat juga

  • Last updated on