كيفية القيام بما يلي: إنشاء الوظيفة الإضافية التي هي واجهة مستخدم
يوضح هذا المثال كيفية إنشاء الوظيفة الإضافية التي هي هي Windows Presentation Foundation (WPF) واجهة المستخدم (UI)التي تتم استضافتها بواسطة التطبيق المستقل WPFالتطبيق المستقل.
الوظيفة الإضافية هي واجهة المستخدم والذي عنصر تحكم WPF للمستخدم. محتوى عنصر تحكم المستخدم هو عبارة عن زر واحد ، وعند النقر فوقه يعرض مربع رسالة. التطبيق المستقل WPF يقوم باستضافة الوظيفة الإضافية واجهة المستخدم كالمحتوى من إطار التطبيق الرئيسي.
المتطلبات الأساسية
يوضح هذا المثال ملحقات WPF للوظيفة الاضافية .NET Framework التى تتيح هذا السيناريو ويفترض ما يلي:
معرفة طراز الوظيفة الاضافية .NET Framework بما في ذلك pipeline ، الوظيفة الاضافية ، وتطوير المضيف. إذا كنت غير معتاد على هذه المفاهيم ، راجع الوظائف الإضافية ووحدات الامتداد. للحصول على برنامج تعليمي يوضح تطبيق pipeline والوظيفة الاضافية ، والتطبيق المضيف ، راجع الإرشادات التفصيلية: إنشاء تطبيقات القابلة للتوسيع.
معرفة الملحقات WPF لطراز الوظيفة الاضافية .NET Framework الذي يمكن العثور عليه هنا: نظرة عامة على الوظائف الإضافية لـ WPF.
مثال
لإنشاء وظيفة اضافية التي هي WPF واجهة المستخدم تتطلب تعليمات برمجية خاصة من أجل كل قطعة pipeline والوظيفة الاضافية ، التطبيق المضيف.
تطبيق اتفاق قطعة pipeline
عندما تكون الوظيفة الإضافية واجهة المستخدم ،يجب عقد تنفيذ الوظيفة الإضافية لــ INativeHandleContract. في المثال ، IWPFAddInContract يقوم بتطبيق INativeHandleContract كما هو موضح في المثال التالي:
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInContractAttribute
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInContractAttribute
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 {}
}
تطبيق الوظيفة الاضافية عرض مقطع pipeline
لأن الوظيفة الإضافية يتم تطبيقها كفئة فرعية لنوع FrameworkElement ، عرض الوظيفة الإضافية يجب أن يكون الفئة الفرعية FrameworkElement. تُظهر التعليمات البرمجية التالية عرض الوظيفة الإضافية للعقد مُطبق كفئة WPFAddInView.
Imports System.AddIn.Pipeline ' AddInBaseAttribute
Imports System.Windows.Controls ' UserControl
Namespace AddInViews
''' <summary>
''' Defines the add-in's view of the contract.
''' </summary>
<AddInBase>
Public Class WPFAddInView
Inherits UserControl
End Class
End Namespace
using System.AddIn.Pipeline; // AddInBaseAttribute
using System.Windows.Controls; // UserControl
namespace AddInViews
{
/// <summary>
/// Defines the add-in's view of the contract.
/// </summary>
[AddInBase]
public class WPFAddInView : UserControl { }
}
هنا، عرض الوظيفة الإضافية مشتق من UserControl. وبالتالي، فالوظيفة الإضافية واجهة المستخدم يجب أيضاً أن تنحدر من UserControl.
تطبيق الوظيفة الاضافية مكيف مقطع pipeline
بينما العقد هو INativeHandleContract ، الوظيفة الإضافية داخلها هي FrameworkElement (كما هو محدد بواسطة مقطع pipeline الخاص بطريقة عرض الوظيفة الإضافية ). وبالتالي، يجب أن يتم تحويل FrameworkElement إلى INativeHandleContract قبل عبور حاجز العزل. يتم إجراء هذا العمل بواسطة محول الوظيفة الاضافية عن طريق استدعاء ViewToContractAdapter ، كما هو موضح في التعليمات البرمجية التالية.
Imports System ' IntPtr
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
Imports System.Security.Permissions
Imports AddInViews ' WPFAddInView
Imports 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
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 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
using System; // IntPtr
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // AddInAdapterAttribute, FrameworkElementAdapters, ContractBase
using System.Security.Permissions;
using AddInViews; // WPFAddInView
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
{
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 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();
}
}
}
في إضافة-في الطراز الموقع إضافة-في إرجاع واجهة المستخدم(seeكيفية القيام بما يلي: إنشاء الوظائف الإضافية التي تقوم بإرجاع UI) ، إضافة-في محول تحويل FrameworkElementإلى INativeHandleContractبواسطة استدعاء ViewToContractAdapter. ViewToContractAdapterيجب أن يسمى أيضا بهذه الطريقة، على الرغم من أن تحتاج إلى تنفيذ أسلوب منها إلى كتابة تعليمات برمجية إلى استدعاء it. يمكنك القيام بذلك عن طريق تجاوز QueryContract وتنفيذ التعليمات البرمجية التي تستدعي ViewToContractAdapter إذا كانت التعليمات البرمجية التي تقوم ياستدعاء QueryContract تتوقع INativeHandleContract. في هذه الحالة، سيكون المتصل محول على جانب المضيف ، والذي تم تغطيته في القسم الفرعي ضمن القسم اللاحق .
.gif "ملاحظة") ملاحظة |
|---|
تحتاج أيضاً إلى تجاوز QueryContract في هذا الطراز لتمكين التبويب بين التطبيق المضيف واجهة المستخدم و الوظيفة الإضافية واجهة المستخدم.لمزيد من المعلومات، راجع "قيود الوظيفة الإضافية WPF" في نظرة عامة على الوظائف الإضافية لـ WPF. |
لأن محول جانب الوظيفة الإضافية يقوم بتطبيق واجهة تشتق من INativeHandleContract ، تحتاج أيضاً إلى تطبيق GetHandle ، على الرغم من ذلك يتم تجاهل ذلك عند إبطال QueryContract .
تطبيق عرض مقطع pipeline المضيف
في هذا الطراز ، التطبيق المضيف عادةً يتوقع العرض المضيف أن يكون فئة فرعية FrameworkElement . محول جانب المضيف عليه تحويل INativeHandleContract إلى FrameworkElement بعد INativeHandleContract أن يتقاطع مع حد العزل . لأنه لم يتم استدعاء أسلوب بواسطة التطبيق المضيف للحصول على FrameworkElement ، يجب على عرض المضيف أن يقوم "بإرجاع" FrameworkElement بواسطة احتواءه . وبالتالي، يجب أن يتم اشتقاق عرض المضيف من الفئات فرعية لـ FrameworkElement التي يمكنها أن تحتوي واجهات المستخدم أخرى , مثل UserControl. تُظهر التعليمات البرمجية التالية عرض المضيف للعقد مُطبق كفئة WPFAddInHostView.
Imports System.Windows.Controls ' UserControl
Namespace HostViews
''' <summary>
''' Defines the host's view of the add-in
''' </summary>
Public Class WPFAddInHostView
Inherits UserControl
End Class
End Namespace
using System.Windows.Controls; // UserControl
namespace HostViews
{
/// <summary>
/// Defines the host's view of the add-in
/// </summary>
public class WPFAddInHostView : UserControl { }
}
تطبيق الوظيفة الاضافية مكيف جانب مقطع pipeline
عندما يكون العقد INativeHandleContract ، يتوقع التطبيق المضيف UserControl (كما تم تحديده من قبل طريقة العرض المضيف). وبالتالي، INativeHandleContract يجب تحويله إلى FrameworkElement بعد عبور حد العزل قبل تعيينه كمحتويات من طريقة عرض المضيف (المشتق من UserControl).
يتم إجراء هذا العمل بواسطة محول الجانب الخاص بالمضيف ، كما هو موضح في التعليمات البرمجية التالية.
Imports System.AddIn.Contract ' INativeHandleContract
Imports System.AddIn.Pipeline ' HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
Imports System.Windows ' FrameworkElement
Imports Contracts ' IWPFAddInContract
Imports HostViews ' WPFAddInHostView
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
using System.AddIn.Contract; // INativeHandleContract
using System.AddIn.Pipeline; // HostAdapterAttribute, FrameworkElementAdapters, ContractHandle
using System.Windows; // FrameworkElement
using Contracts; // IWPFAddInContract
using HostViews; // WPFAddInHostView
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;
}
}
}
كما يمكنك مشاهدة محول جانب المضيف يكتسب INativeHandleContract عن طريق استدعاء أسلوب QueryContract الخاص بمحول على جانب الوظيفة الإضافية (هذة هي النقطة حيث INativeHandleContract يتجاوز حد العزل).
محول جانب المضيف بعدها يقوم بتحويل INativeHandleContract إلى FrameworkElement بواسطة استدعاء ContractToViewAdapter. وفي النهاية، FrameworkElement يتم تعيينه كالمحتوى لطريقة عرض المضيف .
تطبيق الوظيفة الاضافية
مع "محول جانب الوظيفة الإضافية" و "عرض الوظيفة الإضافية" في مكانهما ، يمكن تطبيق الوظيفة الإضافية خلال الاشتقاق من عرض الوظيفة الاضافية, كما هو موضح في التعليمات البرمجية التالية.
<addInViews:WPFAddInView
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
xmlns:addInViews="clr-namespace:AddInViews;assembly=AddInViews"
x:Class="WPFAddIn1.AddInUI">
<Grid>
<Button Click="clickMeButton_Click" Content="Click Me!" />
</Grid>
</addInViews:WPFAddInView>
Imports System.AddIn ' AddInAttribute
Imports System.Windows ' MessageBox, RoutedEventArgs
Imports AddInViews ' WPFAddInView
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
using System.AddIn; // AddInAttribute
using System.Windows; // MessageBox, RoutedEventArgs
using AddInViews; // WPFAddInView
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");
}
}
}
من هذا المثال، يمكنك مشاهدة فائدة واحدة مثيرة للاهتمام لهذا الطراز: مطورين الوظيفة الإضافية فقط يحتاجوا لتنفيذ الوظيفة الإضافية (حيث إنه واجهة المستخدم أيضاً) ، بدلاً من كليهما الوظيفة الإضافية و فئتها في واجهة المستخدم.
تنفيذ التطبيق المضيف
مع المحول المضيف من جانب والمضيف لطريقة العرض التي تم إنشاؤها، يمكن استخدام تطبيق المضيف .NET Frameworkطراز الوظيفة الإضافية إلى فتح خط أنابيب والحصول على طريقة عرض مضيف الوظيفة الإضافية الأداة تظهر هذه الخطوات فى التعليمات البرمجية التالية.
' 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)
// 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);
يستخدم التطبيق المضيف تعليمات برمجية خاصة بطراز الوظيفة الإضافية .NET Framework النموذجية لتنشيط الوظيفة الإضافية ، والتي تُرجع عرض المضيف ضمنياً إلى التطبيق المضيف. يعرض التطبيق المضيف فيما بعد العرض المضيف (الذي هو UserControl) من Grid.
التعليمات البرمجية لمعالجة التفاعلات مع الوظيفة الإضافية واجهة المستخدم يعمل في مجال التطبيق للوظيفة الإضافية . تتضمن هذه التفاعلات ما يلي:
إظهار MessageBox.
هذا النشاط يتم عزله بالكامل من التطبيق المضيف.