Nasıl yapılır: UI Olan Eklenti Oluşturma
Bu örnekte, tek başına bir WPF uygulaması tarafından barındırılan bir Windows Presentation Foundation (WPF) olan bir eklentinin nasıl oluşturularak ilgili bilgi ve içerikler açıklandı.
Eklenti, WPF kullanıcı denetimi olan bir kullanıcı arabirimidir. Kullanıcı denetimi içeriği, tıkıldığında bir ileti kutusu görüntüleyen tek bir düğmedir. WPF tek başına uygulaması, eklenti kullanıcı arabirimini ana uygulama penceresinin içeriği olarak barındırr.
Önkoşullar
Bu örnek, bu senaryoyu etkinleştiren .NET Framework için WPF uzantılarını vurgular ve şunları varsayıyor:
İşlem hattı, .NET Framework ve konak geliştirme dahil olmak üzere farklı eklenti modeli hakkında bilgi. Bu kavramlara yabancısanız bkz. Eklentiler ve Genişletilebilirlik. İşlem hattı, eklenti ve konak uygulaması uygulamasını gösteren bir öğretici için bkz. Adım adım: Genişletilebilir Uygulama Oluşturma.
.NET Framework modele WPF uzantıları hakkında bilgi. Bkz. WPF Add-Ins Genel Bakış.
Örnek
WPF kullanıcı arabirimi olan bir eklenti oluşturmak için her işlem hattı segmenti, eklenti ve konak uygulaması için belirli bir kod gerekir.
Sözleşme İşlem Hattı Segmentini Uygulama
Eklenti bir kullanıcı arabirimi olduğunda, eklentinin sözleşmesinin uygulaması INativeHandleContract gerekir. Örnekte, IWPFAddInContract aşağıdaki INativeHandleContract kodda gösterildiği gibi uygulanır.
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 İşlem Hattı Kesimini Uygulama
Eklenti türün bir alt sınıfı olarak uygulana FrameworkElement olduğundan, eklenti görünümünün de alt sınıfı olması FrameworkElement gerekir. Aşağıdaki kod, sınıf olarak uygulanan sözleşmenin eklenti görünümünü WPFAddInView 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ü'den UserControl türetildi. Sonuç olarak, eklenti kullanıcı arabiriminin de 'den türetmiş olması UserControl gerekir.
Add-In-Side Adapter Pipeline Segmentini Uygulama
Sözleşme bir ise eklenti bir 'tir (eklenti görünümü işlem hattı INativeHandleContractFrameworkElement segmenti tarafından belirtilen şekilde). Bu FrameworkElement nedenle, yalıtım sınırını geçmeden INativeHandleContract önce olarak dönüştürülmesi gerekir. Bu çalışma, aşağıdaki kodda gösterildiği gibi çağrısı ViewToContractAdapter yaparak eklenti tarafı bağdaştırıcısı tarafından 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 ie 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>
[SecurityPermissionAttribute(SecurityAction.Demand, Flags = SecurityPermissionFlag.UnmanagedCode)]
public IntPtr GetHandle()
{
return FrameworkElementAdapters.ViewToContractAdapter(this.wpfAddInView).GetHandle();
}
}
}
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 ie 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>
<SecurityPermissionAttribute(SecurityAction.Demand, Flags:=SecurityPermissionFlag.UnmanagedCode)>
Public Function GetHandle() As IntPtr Implements INativeHandleContract.GetHandle
Return FrameworkElementAdapters.ViewToContractAdapter(Me.wpfAddInView).GetHandle()
End Function
End Class
End Namespace
Eklentinin kullanıcı arabirimi döndüren bir kullanıcı arabirimi döndüren eklenti modelinde (bkz. KullanıcıArabirimi Add-In Bir Kullanıcı Arabirimi Döndüren Bir Kullanıcı Arabirimi Oluşturma) eklenti bağdaştırıcısı çağrısıyla 'yi bir'e INativeHandleContractViewToContractAdapter dönüştürür. ViewToContractAdapter bu modelde de çağrılmalı, ancak bunu çağıracak kodu yazmak için bir yöntem uygulamanız gerekir. Bunu, çağıran kod bir bekliyorsa çağıran kodu QueryContractViewToContractAdapter geçersiz karak ve QueryContract uygulayarak INativeHandleContract gerçekleştirebilirsiniz. Bu durumda, çağıranı, sonraki bir alt bölüm kapsamında yer alan konak tarafı bağdaştırıcısı olur.
Not
Ayrıca konak uygulama kullanıcı arabirimi ile eklenti kullanıcı arabirimi arasında sekmeyi etkinleştirmek QueryContract için bu modelde geçersiz kılma gerekir. Daha fazla bilgi için WPF'de "WPF Add-In Sınırlamaları" genel Add-Ins bakın.
Eklenti tarafı bağdaştırıcısı, 'den türetilen bir arabirim uygulayan bir arabirime sahip olduğundan, geçersiz kılınırken bu yoksayılır ancak bunu INativeHandleContractGetHandle da QueryContract uygulamanız gerekir.
Konak Görünümü İşlem Hattı Kesimini Uygulama
Bu modelde, konak uygulaması genellikle konak görünümünün bir alt sınıf FrameworkElement olmasını bekler. Konak tarafı bağdaştırıcısı, yalıtım sınırını INativeHandleContract aştıktan FrameworkElementINativeHandleContract sonra'ı bir'e dönüştürmeli. Bir yöntemi almak için konak uygulama tarafından çağrılmay olduğundan, konak görünümü onu içeren FrameworkElement tarafından "dönüş" FrameworkElement gerekir. Sonuç olarak, konak görünümü gibi diğer FrameworkElement UI'leri içeren bir alt sınıftan türet UserControl gerekir. Aşağıdaki kod, sınıf olarak uygulanan sözleşmenin ana bilgisayar görünümünü WPFAddInHostView 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ı İşlem Hattı Kesimini Uygulama
Sözleşme bir INativeHandleContract ise, konak uygulaması bir bekler UserControl (konak görünümü tarafından belirtilen şekilde). Sonuç olarak, konak görünümünün içeriği olarak ayarlanmayacak şekilde ('den türetilen) önce yalıtım sınırını aştıktan sonra ' a INativeHandleContractFrameworkElement dönüştürülmesi UserControl gerekir.
Bu çalışma, aşağıdaki kodda gösterildiği gibi konak tarafı bağdaştırıcısı 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 yan bağdaştırıcısının yöntemini çağırarak alır (yalıtım sınırının kesiştir olduğu INativeHandleContractQueryContractINativeHandleContract noktadır).
Ardından, konak tarafı bağdaştırıcısı çağrısıyla INativeHandleContract 'yi FrameworkElement bir'e ContractToViewAdapter dönüştürür. Son FrameworkElement olarak, konak görünümünün içeriği olarak ayarlanır.
Uygulama Add-In
Eklenti yan bağdaştırıcı ve eklenti görünümü yerindeken, 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 örnekten, bu modelin ilginç bir avantajını da görebiliriz: 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.
Konak Uygulamasını Uygulama
Konak tarafı bağdaştırıcısı ve konak görünümü oluşturulduktan sonra, konak uygulaması işlem hattını açmak .NET Framework eklentinin konak görünümünü almak 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 .NET Framework için tipik bir eklenti model kodu kullanır. Bu kod, konak görünümünü konak uygulamasına örtülü olarak döndürür. Konak uygulaması daha sonra bir 'den konak görünümünü (yani UserControl ) Grid görüntüler.
Eklenti kullanıcı arabirimiyle etkileşimleri işleme kodu, eklentinin uygulama etki alanında çalışır. Bu etkileşimler aşağıdakileri içerir:
gösteriliyor. MessageBox
Bu etkinlik, konak uygulamasından tamamen yalıtılmış.