Postupy: Vytvoření doplňku tvořící 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 prvek 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ýrazní rozšíření WPF pro doplněk .NET Framework, který tento scénář povolí, a předpokládá následující:
Znalost modelu doplňku .NET Framework, včetně kanálu, doplňku a vývoje hostitelů Pokud tyto koncepty neznáte, přečtěte si téma Doplňky a rozšiřitelnost. Kurz, který ukazuje implementaci kanálu, doplňku a hostitelské aplikace, naleznete v části Návod: Vytvoření rozšiřitelné aplikace.
Znalost rozšíření WPF pro doplněk .NET Framework Viz přehled doplňků 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 kanálu kontraktu
Pokud je doplněk uživatelské rozhraní, kontrakt doplňku musí 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í doplňku
Vzhledem k tomu, že je doplněk implementován jako podtřída FrameworkElement typu, musí zobrazení doplňku také podtřídu FrameworkElement. Následující kód ukazuje zobrazení doplňku kontraktu, implementované jako WPFAddInView
třída.
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. V důsledku toho by mělo uživatelské rozhraní doplňku také odvodit .UserControl
Implementace segmentu kanálu kanálu adaptéru doplňku na straně
Zatímco kontrakt je INativeHandleContract, doplněk je ( FrameworkElement jak je určeno segmentem kanálu zobrazení doplňku). FrameworkElement Proto musí být převeden na před přechodem INativeHandleContract hranice izolace. Tuto práci provádí adaptér doplňku voláním ViewToContractAdapter, jak je znázorněno v následujícím kódu.
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, kde doplněk vrací uživatelské rozhraní (viz Vytvoření doplňku, který vrací uživatelské rozhraní), adaptér doplňku převeďte na FrameworkElementINativeHandleContract volání ViewToContractAdapter. ViewToContractAdapter musí být také volána v tomto modelu, i když potřebujete implementovat metodu, ze které chcete napsat kód, který ho má volat. Provedete to přepsáním QueryContract a implementací kódu, 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í pododdílu.
Poznámka:
V tomto modelu je také potřeba přepsat QueryContract , abyste povolili tabbing mezi uživatelským rozhraním hostitelské aplikace a uživatelským rozhraním doplňků. Další informace naleznete v tématu "Omezení doplňku WPF" v přehledu doplňků WPF.
Vzhledem k tomu, že adaptér doplňku na straně implementuje rozhraní, které je odvozeno , INativeHandleContractje také nutné implementovat GetHandle, i když je ignorován při QueryContract přepsání.
Implementace segmentu kanálu zobrazení hostitele
V tomto modelu hostitelská aplikace obvykle očekává, že zobrazení hostitele bude podtřídou FrameworkElement . Adaptér na straně hostitele musí převést INativeHandleContract na za FrameworkElementINativeHandleContract křížkem hranice izolace. Vzhledem k tomu, že metoda není volána hostitelskou aplikací, aby získala FrameworkElement, musí zobrazení hostitele "vrátit" tím FrameworkElement , že ji obsahuje. V důsledku toho musí být zobrazení hostitele odvozeno z podtřídy FrameworkElement , která může obsahovat jiné uživatelské rozhraní, například UserControl. Následující kód ukazuje zobrazení hostitele kontraktu implementované jako WPFAddInHostView
třída.
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 kanálu adaptéru na straně hostitele
Zatímco kontrakt je INativeHandleContract, hostitelská aplikace očekává UserControl (jak je určeno zobrazením hostitele). V důsledku toho INativeHandleContract musí být převedena na FrameworkElement po překročení hranice izolace před nastavením jako obsah zobrazení hostitele (který je odvozen 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 adaptéru doplňku na straně QueryContract (to je bod, kde INativeHandleContract překračuje hranice izolace).
Adaptér na straně hostitele pak převede na INativeHandleContract volání FrameworkElementContractToViewAdapter. FrameworkElement Nakonec se nastaví jako obsah zobrazení hostitele.
Implementace doplňku
S adaptérem doplňku a integrovaným zobrazením doplňku je možné doplněk implementovat odvozením z zobrazení doplňku, 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 hostitele může hostitelská aplikace použít model doplňku .NET Framework k otevření kanálu a získání zobrazení hostitele doplňku. 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 objektu 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ří:
Zobrazuje se .MessageBox
Tato aktivita je zcela izolovaná od hostitelské aplikace.
Viz také
.NET Desktop feedback
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro