Información general sobre los complementos de WPFWPF Add-Ins Overview

El .NET Framework incluye un modelo de complemento que los desarrolladores pueden utilizar para crear aplicaciones que admitan la extensibilidad de complementos.The .NET Framework includes an add-in model that developers can use to create applications that support add-in extensibility. Dicho modelo permite la creación de complementos que se integran con las aplicaciones y amplían su funcionalidad.This add-in model allows the creation of add-ins that integrate with and extend application functionality. En algunos escenarios, las aplicaciones también necesitan mostrar las interfaces de usuario que proporcionan los complementos. En este tema se muestra cómo WPF amplía el modelo de complemento de .NET Framework para habilitar estos escenarios, la arquitectura subyacente, sus ventajas y sus limitaciones.In some scenarios, applications also need to display user interfaces that are provided by add-ins. This topic shows how WPF augments the .NET Framework add-in model to enable these scenarios, the architecture behind it, its benefits, and its limitations.

Requisitos previosPrerequisites

Es necesario estar familiarizado con el modelo de complemento de .NET Framework.Familiarity with the .NET Framework add-in model is required. Para más información, consulte Complementos y extensibilidad.For more information, see Add-ins and Extensibility.

Información general sobre los complementosAdd-Ins Overview

Para evitar las complejidades de la recompilación y reimplementación de aplicaciones para incorporar la nueva funcionalidad, estas implementan mecanismos de extensibilidad que permiten a los desarrolladores (tanto propios como de terceros) crear otras aplicaciones que se integran con ellas.In order to avoid the complexities of application recompilation and redeployment to incorporate new functionality, applications implement extensibility mechanisms that allow developers (both first-party and third-party) to create other applications that integrate with them. La manera más común de admitir este tipo de extensibilidad es mediante el uso de complementos (también conocido como "complementos" y "módulos").The most common way to support this type of extensibility is through the use of add-ins (also known as "add-ons" and "plug-ins"). Estos son algunos ejemplos de aplicaciones reales que exponen la extensibilidad con complementos:Examples of real-world applications that expose extensibility with add-ins include:

  • Complementos de Internet Explorer.Internet Explorer add-ons.

  • Módulos del Reproductor de Windows Media.Windows Media Player plug-ins.

  • Complementos de Visual Studio.Visual Studio add-ins.

Por ejemplo, el modelo del complemento del Reproductor de Windows Media permite a los desarrolladores de otras empresas implementar "módulos" que extienden el Reproductor de Windows Media de varias formas, entre las que se incluye incluida la creación de descodificadores y codificadores para los formatos multimedia que el Reproductor de Windows Media no admite de forma nativa (por ejemplo, DVD o MP3), efectos de audio y máscaras.For example, the Windows Media Player add-in model allows third-party developers to implement "plug-ins" that extend Windows Media Player in a variety of ways, including creating decoders and encoders for media formats that are not supported natively by Windows Media Player (for example, DVD, MP3), audio effects, and skins. Cada modelo del complemento se crea para exponer la funcionalidad que es única para una aplicación, aunque hay varias entidades y comportamientos que son comunes a todos los modelos de complementos.Each add-in model is built to expose the functionality that is unique to an application, although there are several entities and behaviors that are common to all add-in models.

Las tres entidades principales de las soluciones de extensibilidad de complemento habituales son los contratos, los complementos y las aplicaciones host.The three main entities of typical add-in extensibility solutions are contracts, add-ins, and host applications. Los contratos definen la forma en que los complementos se integran con las aplicaciones host de dos maneras:Contracts define how add-ins integrate with host applications in two ways:

  • Los complementos se integran con la funcionalidad que implementan las aplicaciones host.Add-ins integrate with functionality that is implemented by host applications.

  • Las aplicaciones host exponen la funcionalidad para que los complementos se integren con ella.Host applications expose functionality for add-ins to integrate with.

Para que se usen los complementos, es preciso que las aplicaciones host los encuentren y los carguen en tiempo de ejecución.In order for add-ins to be used, host applications need to find them and load them at run time. En consecuencia, las aplicaciones que admiten complementos tienen las siguientes responsabilidades adicionales:Consequently, applications that support add-ins have the following additional responsibilities:

  • Detección: Buscar complementos que cumplan los contratos admitidos por las aplicaciones host.Discovery: Finding add-ins that adhere to contracts supported by host applications.

  • Activación: Cargar, ejecutar y establecer la comunicación con los complementos.Activation: Loading, running, and establishing communication with add-ins.

  • Aislamiento: Usar dominios de aplicación o procesos para establecer límites de aislamiento que protejan las aplicaciones frente a posibles problemas de seguridad y ejecución con complementos.Isolation: Using either application domains or processes to establish isolation boundaries that protect applications from potential security and execution problems with add-ins.

  • Comunicación: Permitir que los complementos y las aplicaciones host se comuniquen entre sí a través de los límites de aislamiento mediante la llamada a métodos y el paso de datos.Communication: Allowing add-ins and host applications to communicate with each other across isolation boundaries by calling methods and passing data.

  • Administraciónde la duración: Cargar y descargar dominios de aplicación y procesos de forma limpia y predecible (consulte dominios de aplicación).Lifetime Management: Loading and unloading application domains and processes in a clean, predictable manner (see Application Domains).

  • Control de versiones: Asegurarse de que las aplicaciones host y los complementos pueden seguir comunicándose cuando se creen nuevas versiones de.Versioning: Ensuring that host applications and add-ins can still communicate when new versions of either are created.

Por último, el desarrollo de un sólido modelo de complemento es una empresa que no es trivial.Ultimately, developing a robust add-in model is a non-trivial undertaking. Por esta razón, el .NET Framework proporciona una infraestructura para crear modelos de complementos.For this reason, the .NET Framework provides an infrastructure for building add-in models.

Nota

Para más información acerca de los complementos, consulte Complementos y extensibilidad.For more detailed information on add-ins, see Add-ins and Extensibility.

Introducción al modelo de complemento de .NET Framework.NET Framework Add-In Model Overview

El modelo de complemento de .NET Framework, que se encuentra System.AddIn en el espacio de nombres, contiene un conjunto de tipos que están diseñados para simplificar el desarrollo de extensibilidad de complementos.The .NET Framework add-in model, found in the System.AddIn namespace, contains a set of types that are designed to simplify the development of add-in extensibility. La unidad fundamental del modelo de complemento .NET Framework es el contrato, que define cómo una aplicación host y un complemento se comunican entre sí.The fundamental unit of the .NET Framework add-in model is the contract, which defines how a host application and an add-in communicate with each other. Un contrato se expone a una aplicación host mediante una vista específica de la aplicación host del contrato.A contract is exposed to a host application using a host-application-specific view of the contract. Del mismo modo, se expone una vista específica del complemento al complemento.Likewise, an add-in-specific view of the contract is exposed to the add-in. Se usa un adaptador para que una aplicación host y un complemento se comuniquen entre sus respectivas vistas del contrato.An adapter is used to allow a host application and an add-in to communicate between their respective views of the contract. Los contratos, vistas y adaptadores se conocen como segmentos y un conjunto de segmentos relacionados constituye una canalización.Contracts, views, and adapters are referred to as segments, and a set of related segments constitutes a pipeline. Las canalizaciones son la base sobre la que el modelo de complemento de .NET Framework admite la detección, la activación, el aislamiento de la seguridad, el aislamiento de la ejecución (mediante procesos y dominios de aplicación), la comunicación, la administración de la duración y el control de versiones.Pipelines are the foundation upon which the .NET Framework add-in model supports discovery, activation, security isolation, execution isolation (using both application domains and processes), communication, lifetime management, and versioning.

La suma de todo ello permite a los desarrolladores compilar complementos que se integran con la funcionalidad de una aplicación host.The sum of this support allows developers to build add-ins that integrate with the functionality of a host application. Sin embargo, algunos escenarios requieren que las aplicaciones host muestren las interfaces de usuario proporcionadas por los complementos. Dado que cada tecnología de presentación en el .NET Framework tiene su propio modelo para implementar interfaces de usuario, el modelo de complementos de .NET Framework no admite ninguna tecnología de presentación determinada.However, some scenarios require host applications to display user interfaces provided by add-ins. Because each presentation technology in the .NET Framework has its own model for implementing user interfaces, the .NET Framework add-in model does not support any particular presentation technology. En su lugar, WPF amplía el modelo de complemento de .NET Framework con compatibilidad con la interfaz de usuario para complementos.Instead, WPF extends the .NET Framework add-in model with UI support for add-ins.

Complementos WPFWPF Add-Ins

WPF, junto con el modelo de complemento de .NET Framework, le permite abordar una gran variedad de escenarios que requieren que las aplicaciones host muestren las interfaces de usuario de los complementos. En concreto, estos escenarios se abordan con WPF con los dos modelos de programación siguientes:WPF, in conjunction with the .NET Framework add-in model, allows you to address a wide variety of scenarios that require host applications to display user interfaces from add-ins. In particular, these scenarios are addressed by WPF with the following two programming models:

  1. El complemento devuelve una interfaz de usuario.The add-in returns a UI. Un complemento devuelve una interfaz de usuario a la aplicación host a través de una llamada al método, tal y como se define en el contrato.An add-in returns a UI to the host application via a method call, as defined by the contract. Este escenario se utiliza en los casos siguientes:This scenario is used in the following cases:

    • La apariencia de una interfaz de usuario devuelta por un complemento depende de los datos o condiciones que solo existen en tiempo de ejecución, como los informes generados dinámicamente.The appearance of a UI that is returned by an add-in is dependent on either data or conditions that exist only at run time, such as dynamically generated reports.

    • La interfaz de usuario para los servicios que proporciona un complemento difiere de la interfaz de usuario de las aplicaciones host que pueden usar el complemento.The UI for services provided by an add-in differs from the UI of the host applications that can use the add-in.

    • El complemento realiza principalmente un servicio para la aplicación host y notifica el estado a la aplicación host con una interfaz de usuario.The add-in primarily performs a service for the host application, and reports status to the host application with a UI.

  2. El complemento es una interfaz de usuario.The add-in is a UI. Un complemento es una interfaz de usuario, tal y como se define en el contrato.An add-in is a UI, as defined by the contract. Este escenario se utiliza en los casos siguientes:This scenario is used in the following cases:

    • Los complementos solo muestran los servicios que se muestran, como un anuncio.An add-in doesn't provide services other than being displayed, such as an advertisement.

    • La interfaz de usuario para los servicios que proporciona un complemento es común a todas las aplicaciones host que pueden usar ese complemento, como una calculadora o un selector de colores.The UI for services provided by an add-in is common to all host applications that can use that add-in, such as a calculator or color picker.

Estos escenarios requieren que los objetos de interfaz de usuario se puedan pasar entre la aplicación host y los dominios de aplicación de complemento.These scenarios require that UI objects can be passed between host application and add-in application domains. Dado que el modelo de complementos de .NET Framework se basa en la comunicación remota para comunicarse entre los dominios de aplicación, los objetos que se pasan entre ellos deben ser remotos.Since the .NET Framework add-in model relies on remoting to communicate between application domains, the objects that are passed between them must be remotable.

Un objeto que se puede usar de forma remota es una instancia de una clase que realiza una o varias de las siguientes acciones:A remotable object is an instance of a class that does one or more of the following:

Nota

Para obtener más información sobre la creación de objetos de .NET Framework remotos, consulte crear objetosde forma remota.For more information regarding the creation of remotable .NET Framework objects, see Making Objects Remotable.

Los tipos de interfaz de usuario de WPF no son remotos.The WPF UI types are not remotable. Para solucionar el problema, WPF extiende el .NET Framework modelo de complementos para habilitar la interfaz de usuario de WPF creada por los complementos para que se muestren desde las aplicaciones host.To solve the problem, WPF extends the .NET Framework add-in model to enable WPF UI created by add-ins to be displayed from host applications. WPF proporciona esta compatibilidad mediante dos INativeHandleContract tipos: la interfaz y dos métodos estáticos implementados por la FrameworkElementAdapters clase: ContractToViewAdapter y. ViewToContractAdapterThis support is provided by WPF by two types: the INativeHandleContract interface and two static methods implemented by the FrameworkElementAdapters class: ContractToViewAdapter and ViewToContractAdapter. A un nivel alto, estos tipos y métodos se utilizan como se indica a continuación:At a high level, these types and methods are used in the following manner:

  1. WPF requiere que las interfaces de usuario proporcionadas por los complementos sean clases que derivan FrameworkElementdirecta o indirectamente de, como formas, controles, controles de usuario, paneles de diseño y páginas.WPF requires that user interfaces provided by add-ins are classes that derive directly or indirectly from FrameworkElement, such as shapes, controls, user controls, layout panels, and pages.

  2. Siempre que el contrato declare que se va a pasar una interfaz de usuario entre el complemento y la aplicación host, debe declararse INativeHandleContract como ( FrameworkElementno). INativeHandleContract es una representación remota de la interfaz de usuario del complemento que se puede pasar a través de los límites de aislamiento.Wherever the contract declares that a UI will be passed between the add-in and the host application, it must be declared as an INativeHandleContract (not a FrameworkElement); INativeHandleContract is a remotable representation of the add-in UI that can be passed across isolation boundaries.

  3. Antes de que se pasara desde el dominio de aplicación del complemento FrameworkElement , se empaqueta como una INativeHandleContract llamada ViewToContractAdaptera.Before being passed from the add-in's application domain, a FrameworkElement is packaged as an INativeHandleContract by calling ViewToContractAdapter.

  4. Después de pasarse al dominio de aplicación de la aplicación host INativeHandleContract , se debe volver a empaquetar FrameworkElement como ContractToViewAdapterllamando a.After being passed to the host application's application domain, the INativeHandleContract must be repackaged as a FrameworkElement by calling ContractToViewAdapter.

El uso ContractToViewAdapterde ViewToContractAdapter , y depende del escenario específico. INativeHandleContractHow INativeHandleContract, ContractToViewAdapter, and ViewToContractAdapter are used depends on the specific scenario. En las siguientes secciones se proporciona información acerca de cada modelo de programación.The following sections provide details for each programming model.

El complemento devuelve una interfaz de usuarioAdd-In Returns a User Interface

Para que un complemento devuelva una interfaz de usuario a una aplicación host, se requiere lo siguiente:For an add-in to return a UI to a host application, the following are required:

  1. Se deben crear la aplicación host, el complemento y la canalización, como se describe en la documentación de extensibilidad y complementos de .NET Framework.The host application, add-in, and pipeline must be created, as described by the .NET Framework Add-ins and Extensibility documentation.

  2. El contrato debe implementar IContract y, para devolver una interfaz de usuario, el contrato debe declarar un método con un valor devuelto de tipo. INativeHandleContractThe contract must implement IContract and, to return a UI, the contract must declare a method with a return value of type INativeHandleContract.

  3. La interfaz de usuario que se pasa entre el complemento y la aplicación host debe derivar directa o indirectamente de FrameworkElement.The UI that is passed between the add-in and the host application must directly or indirectly derive from FrameworkElement.

  4. La interfaz de usuario que devuelve el complemento se debe convertir de un FrameworkElement a un INativeHandleContract antes de cruzar el límite de aislamiento.The UI that is returned by the add-in must be converted from a FrameworkElement to an INativeHandleContract before crossing the isolation boundary.

  5. La interfaz de usuario que se devuelve se debe convertir INativeHandleContract de un FrameworkElement a un después de cruzar el límite de aislamiento.The UI that is returned must be converted from an INativeHandleContract to a FrameworkElement after crossing the isolation boundary.

  6. La aplicación host muestra el devuelto FrameworkElement.The host application displays the returned FrameworkElement.

Para obtener un ejemplo que muestra cómo implementar un complemento que devuelve una interfaz de usuario, vea crear un complemento que devuelva una interfaz de usuario.For an example that demonstrates how to implement an add-in that returns a UI, see Create an Add-In That Returns a UI.

El complemento es una interfaz de usuarioAdd-In Is a User Interface

Cuando un complemento es una interfaz de usuario, se requiere lo siguiente:When an add-in is a UI, the following are required:

  1. Se deben crear la aplicación host, el complemento y la canalización, como se describe en la documentación de extensibilidad y complementos de .NET Framework.The host application, add-in, and pipeline must be created, as described by the .NET Framework Add-ins and Extensibility documentation.

  2. La interfaz de contrato para el complemento debe implementar INativeHandleContract.The contract interface for the add-in must implement INativeHandleContract.

  3. El complemento que se pasa a la aplicación host debe derivar directa o indirectamente de FrameworkElement.The add-in that is passed to the host application must directly or indirectly derive from FrameworkElement.

  4. El complemento se debe convertir de un FrameworkElement a un INativeHandleContract antes de cruzar el límite de aislamiento.The add-in must be converted from a FrameworkElement to an INativeHandleContract before crossing the isolation boundary.

  5. El complemento se debe convertir de un INativeHandleContract a un FrameworkElement después de cruzar el límite de aislamiento.The add-in must be converted from an INativeHandleContract to a FrameworkElement after crossing the isolation boundary.

  6. La aplicación host muestra el devuelto FrameworkElement.The host application displays the returned FrameworkElement.

Para obtener un ejemplo que muestra cómo implementar un complemento que es una interfaz de usuario, vea crear un complemento que sea una interfaz de usuario.For an example that demonstrates how to implement an add-in that is a UI, see Create an Add-In That Is a UI.

Devolución de varias interfaces de usuario desde un complementoReturning Multiple UIs from an Add-In

A menudo, los complementos proporcionan varias interfaces de usuario para que se muestren las aplicaciones host.Add-ins often provide multiple user interfaces for host applications to display. Por ejemplo, considere un complemento que es una interfaz de usuario que también proporciona información de estado a la aplicación host, también como una interfaz de usuario.For example, consider an add-in that is a UI that also provides status information to the host application, also as a UI. Un complemento como este se puede implementar mediante una combinación de técnicas de los modelos de El complemento devuelve una interfaz de usuario y El complemento es una interfaz de usuario.An add-in like this can be implemented by using a combination of techniques from both the Add-In Returns a User Interface and Add-In Is a User Interface models.

Complementos y aplicaciones del explorador XAMLAdd-Ins and XAML Browser Applications

Hasta ahora, en los ejemplos, la aplicación host ha sido una aplicación independiente instalada.In the examples so far, the host application has been an installed standalone application. Pero Aplicaciones del explorador XAML (XBAPs)XAML browser applications (XBAPs) también pueden hospedar complementos, aunque con los siguientes requisitos adicionales de compilación e implementación:But Aplicaciones del explorador XAML (XBAPs)XAML browser applications (XBAPs) can also host add-ins, albeit with the following additional build and implementation requirements:

  • El XBAPXBAP manifiesto de aplicación debe configurarse de forma especial para descargar la canalización (carpetas y ensamblados) y el ensamblado del complemento en la caché de la aplicación ClickOnce en el XBAPXBAPequipo cliente, en la misma carpeta que.The XBAPXBAP application manifest must be configured specially to download the pipeline (folders and assemblies) and add-in assembly to the ClickOnce application cache on the client machine, in the same folder as the XBAPXBAP.

  • El XBAPXBAP código para detectar y cargar complementos debe usar la caché XBAPXBAP de la aplicación ClickOnce para como la canalización y la ubicación del complemento.The XBAPXBAP code to discover and load add-ins must use the ClickOnce application cache for the XBAPXBAP as the pipeline and add-in location.

  • La XBAPXBAP debe cargar el complemento en un contexto de seguridad especial si el complemento hace referencia a archivos dinámicos que se encuentran en el sitio de origen; cuando los hospedan XBAPsXBAPs, los complementos solo pueden hacer referencia a los archivos dinámico que se encuentran en el sitio de origen de la aplicación host.The XBAPXBAP must load the add-in into a special security context if the add-in references loose files that are located at the site of origin; when hosted by XBAPsXBAPs, add-ins can only reference loose files that are located at the host application's site of origin.

Estas tareas se describen con detalle en las subsecciones siguientes.These tasks are described in detail in the following subsections.

Configuración de la canalización y el complemento para la implementación de ClickOnceConfiguring the Pipeline and Add-In for ClickOnce Deployment

XBAPsXBAPsse descargan y se ejecutan desde una carpeta segura en la caché de implementación de ClickOnce.are downloaded to and run from a safe folder in the ClickOnce deployment cache. Para que una XBAPXBAP hospede un complemento, la canalización y el ensamblado del complemento también se debe descargar en la carpeta segura.In order for an XBAPXBAP to host an add-in, the pipeline and add-in assembly must also be downloaded to the safe folder. Para lograrlo, es preciso que configure el manifiesto de aplicación para incluir tanto la canalización como el ensamblado del complemento en la descarga.To achieve this, you need to configure the application manifest to include both the pipeline and add-in assembly for download. Esto se hace más fácilmente en Programa para la mejoraVisual Studio, aunque el ensamblado de la canalización y del ensamblado debe estar la carpeta raíz del proyecto de XBAPXBAP del host en orden para que Programa para la mejoraVisual Studio detecte los ensamblados de canalización.This is most easily done in Programa para la mejoraVisual Studio, although the pipeline and add-in assembly needs to be in the host XBAPXBAP project's root folder in order for Programa para la mejoraVisual Studio to detect the pipeline assemblies.

Por consiguiente, el primer paso es crear el ensamblado de la canalización y del complemento para la raíz del proyecto XBAPXBAP estableciendo la salida de la compilación de cada proyecto de ensamblado de canalización y ensamblado de complemento.Consequently, the first step is to build the pipeline and add-in assembly to the XBAPXBAP project's root by setting the build output of each pipeline assembly and add-in assembly projects. La siguiente tabla muestra las rutas de la salida de la compilación de los proyectos de ensamblado de canalización el proyecto de ensamblado de complemento que se encuentran en la misma carpeta de solución y raíz que el proyecto de XBAPXBAP del host.The following table shows the build output paths for pipeline assembly projects and add-in assembly project that are in the same solution and root folder as the host XBAPXBAP project.

Tabla 1: Crear rutas de acceso de salida para los ensamblados de canalización que se hospedan en una aplicación XBAPTable 1: Build Output Paths for the Pipeline Assemblies That Are Hosted by an XBAP

Proyecto de ensamblado de canalizaciónPipeline assembly project Ruta de acceso de salida de la compilaciónBuild output path
ContratoContract ..\HostXBAP\Contracts\
Vista de complementoAdd-In View ..\HostXBAP\AddInViews\
Adaptador del lado del complementoAdd-In-Side Adapter ..\HostXBAP\AddInSideAdapters\
Adaptador del lado del hostHost-Side Adapter ..\HostXBAP\HostSideAdapters\
ComplementoAdd-In ..\HostXBAP\AddIns\WPFAddIn1

El siguiente paso es especificar los ensamblados de canalización y el ensamblado del complemento como archivos de contenido de las XBAPsXBAPs en Programa para la mejoraVisual Studio haciendo lo siguiente:The next step is to specify the pipeline assemblies and add-in assembly as the XBAPsXBAPs content files in Programa para la mejoraVisual Studio by doing the following:

  1. Incluir Incluso el ensamblado de la canalización y del complemento en el proyecto haciendo clic con el botón derecho en cada carpeta de la canalización en el Explorador de soluciones y elegir Incluir en el proyecto.Including the pipeline and add-in assembly in the project by right-clicking each pipeline folder in Solution Explorer and choosing Include In Project.

  2. Establecer el acción de compilación de cada ensamblado de canalización y ensamblado de complemento en Contenido desde la ventana Propiedades.Setting the Build Action of each pipeline assembly and add-in assembly to Content from the Properties window.

El paso final es configurar el manifiesto de aplicación para incluir los archivos del ensamblado de la canalización como el archivo del ensamblado del complemento en la descarga.The final step is to configure the application manifest to include the pipeline assembly files and add-in assembly file for download. Los archivos deben encontrarse en carpetas en la raíz de la carpeta en la caché de ClickOnce XBAPXBAP que ocupa la aplicación.The files should be located in folders at the root of the folder in the ClickOnce cache that the XBAPXBAP application occupies. En Programa para la mejoraVisual Studio, para lograr esta configuración es preciso realizar las siguientes acciones:The configuration can be achieved in Programa para la mejoraVisual Studio by doing the following:

  1. Haga clic con el botón derecho en el proyecto de XBAPXBAP, haga clic en Propiedades, Publicar y, después, haga clic en el botón Archivos de aplicación.Right-click the XBAPXBAP project, click Properties, click Publish, and then click the Application Files button.

  2. En el cuadro de diálogo Archivos de aplicación, establezca el estado de la publicación de la DLL de cada canalización y complemento en Incluir (automático) y establezca el grupo de descarga de la DLL de cada canalización y complemento en (Requerido) .In the Application Files dialog, set the Publish Status of each pipeline and add-in DLL to Include (Auto), and set the Download Group for each pipeline and add-in DLL to (Required).

Uso de la canalización y del complemento de la base de aplicaciónUsing the Pipeline and Add-In from the Application Base

Cuando la canalización y el complemento están configurados para la implementación ClickOnce, se descargan en la misma carpeta XBAPXBAPde caché ClickOnce que el.When the pipeline and add-in are configured for ClickOnce deployment, they are downloaded to the same ClickOnce cache folder as the XBAPXBAP. Para usar la canalización y el complemento de la XBAPXBAP, el código de la XBAPXBAP debe obtenerlos de la base de la aplicación.To use the pipeline and add-in from the XBAPXBAP, the XBAPXBAP code must get them from the application base. Los distintos tipos y miembros del modelo de complementos de .NET Framework para usar canalizaciones y complementos proporcionan una compatibilidad especial para este escenario.The various types and members of the .NET Framework add-in model for using pipelines and add-ins provide special support for this scenario. En primer lugar, la ruta de acceso se ApplicationBase identifica mediante el valor de enumeración.Firstly, the path is identified by the ApplicationBase enumeration value. Este valor se utiliza en las sobrecargas de los miembros del complemento pertinentes para usar canalizaciones que incluyan los siguientes:You use this value with overloads of the pertinent add-in members for using pipelines that include the following:

Acceso a sitio de origen del HostAccessing the Host's Site of Origin

Para asegurarse de que un complemento puede hacer referencia a los archivos del sitio de origen, debe cargarse con un aislamiento de seguridad equivalente a la aplicación host.To ensure that an add-in can reference files from the site of origin, the add-in must be loaded with security isolation that is equivalent to the host application. Este nivel de seguridad se identifica mediante AddInSecurityLevel.Host el valor de enumeración y se Activate pasa al método cuando se activa un complemento.This security level is identified by the AddInSecurityLevel.Host enumeration value, and passed to the Activate method when an add-in is activated.

Arquitectura de complemento WPFWPF Add-In Architecture

En el nivel más alto, como hemos visto, WPF permite que los complementos de .NET Framework implementen interfaces de usuario (que derivan FrameworkElementdirecta o INativeHandleContractindirectamente ContractToViewAdapterde) mediante, ViewToContractAdapter y.At the highest level, as we've seen, WPF enables .NET Framework add-ins to implement user interfaces (that derive directly or indirectly from FrameworkElement) using INativeHandleContract, ViewToContractAdapter and ContractToViewAdapter. El resultado es que se devuelve a la aplicación host FrameworkElement un que se muestra desde la interfaz de usuario en la aplicación host.The result is that the host application is returned a FrameworkElement that is displayed from UI in the host application.

En el caso de escenarios sencillos de complementos de la interfaz de usuario, esta es la mayor cantidad de detalles que necesita el desarrollador.For simple UI add-in scenarios, this is as much detail as a developer needs. En el caso de escenarios más complejos, especialmente aquellos que intentan usar servicios adicionales de WPF, como el diseño, los recursos y el enlace de datos, se requiere un conocimiento más detallado de cómo WPF amplía el modelo de complemento de .NET Framework con compatibilidad con la interfaz de usuario para comprender sus ventajas. y limitaciones.For more complex scenarios, particularly those that try to utilize additional WPF services such as layout, resources, and data binding, more detailed knowledge of how WPF extends the .NET Framework add-in model with UI support is required to understand its benefits and limitations.

Fundamentalmente, WPF no pasa una interfaz de usuario de un complemento a una aplicación host; en su lugar, WPF pasa el identificador de ventana de Win32 para la interfaz de usuario mediante la interoperabilidad de WPF.Fundamentally, WPF doesn't pass a UI from an add-in to a host application; instead, WPF passes the Win32 window handle for the UI by using WPF interoperability. Como tal, cuando se pasa una interfaz de usuario de un complemento a una aplicación host, ocurre lo siguiente:As such, when a UI from an add-in is passed to a host application, the following occurs:

  • En el lado del complemento, WPF adquiere un identificador de ventana para la interfaz de usuario que mostrará la aplicación host.On the add-in side, WPF acquires a window handle for the UI that will be displayed by the host application. El identificador de ventana está encapsulado por una clase WPF interna que deriva de HwndSource e INativeHandleContractimplementa.The window handle is encapsulated by an internal WPF class that derives from HwndSource and implements INativeHandleContract. Devuelve una instancia de esta clase ViewToContractAdapter y se calculan las referencias del dominio de aplicación del complemento al dominio de aplicación de la aplicación host.An instance of this class is returned by ViewToContractAdapter and is marshaled from the add-in's application domain to the host application's application domain.

  • En el lado de la aplicación host, WPF empaqueta HwndSource como una clase WPF interna que deriva de HwndHost y consume INativeHandleContract.On the host application side, WPF repackages the HwndSource as an internal WPF class that derives from HwndHost and consumes INativeHandleContract. Devuelve una instancia de esta clase ContractToViewAdapter a la aplicación host.An instance of this class is returned by ContractToViewAdapter to the host application.

HwndHostexiste para mostrar interfaces de usuario, identificadas por identificadores de ventana, de las interfaces de usuario de WPF.HwndHost exists to display user interfaces, identified by window handles, from WPF user interfaces. Para más información, consulte Interoperabilidad de WPF y Win32.For more information, see WPF and Win32 Interoperation.

En Resumen, INativeHandleContract, ViewToContractAdaptery ContractToViewAdapter existen para permitir que el identificador de ventana para una interfaz de usuario de WPF se pase desde un complemento a una aplicación host HwndHost , donde está encapsulado por y mostrando la interfaz de usuario de la aplicación host.In summary, INativeHandleContract, ViewToContractAdapter, and ContractToViewAdapter exist to allow the window handle for a WPF UI to be passed from an add-in to a host application, where it is encapsulated by a HwndHost and displayed the host application's UI.

Nota

Dado que la aplicación host obtiene HwndHost, la aplicación host no puede convertir el objeto devuelto por ContractToViewAdapter en el tipo que implementa el complemento (por ejemplo, un UserControl).Because the host application gets an HwndHost, the host application cannot convert the object that is returned by ContractToViewAdapter to the type it is implemented as by the add-in (for example, a UserControl).

Por su naturaleza, HwndHost tiene ciertas limitaciones que afectan al modo en que las aplicaciones host pueden usarlas.By its nature, HwndHost has certain limitations that affect how host applications can use them. Sin embargo, WPF HwndHost se extiende con varias funcionalidades para escenarios de complementos.However, WPF extends HwndHost with several capabilities for add-in scenarios. A continuación se describen estas ventajas y limitaciones.These benefits and limitations are described below.

Ventajas del complemento de WPFWPF Add-In Benefits

Dado que las interfaces de usuario de los complementos de WPF se muestran desde las aplicaciones host mediante una HwndHostclase interna que deriva de, esas interfaces de usuario están restringidas por las capacidades de con respecto a los servicios de IU de HwndHost WPF como el diseño. representación, enlace de datos, estilos, plantillas y recursos.Because WPF add-in user interfaces are displayed from host applications using an internal class that derives from HwndHost, those user interfaces are constrained by the capabilities of HwndHost with respect to WPF UI services such as layout, rendering, data binding, styles, templates, and resources. Sin embargo, WPF aumenta su subclase interna HwndHost con capacidades adicionales que incluyen lo siguiente:However, WPF augments its internal HwndHost subclass with additional capabilities that include the following:

  • Tabulación entre la interfaz de usuario de una aplicación host y la interfaz de usuario de un complemento.Tabbing between a host application's UI and an add-in's UI. Tenga en cuenta que el modelo de programación "el complemento es una interfaz de usuario" requiere que el adaptador del complemento QueryContract se invalide para habilitar la tabulación, si el complemento es de plena confianza o de confianza parcial.Note that the "add-in is a UI" programming model requires the add-in-side adapter to override QueryContract to enable tabbing, whether the add-in is fully trusted or partially trusted.

  • Respetar los requisitos de accesibilidad de las interfaces de usuario de complementos que se muestran desde las interfaces de usuario de la aplicación host.Honoring accessibility requirements for add-in user interfaces that are displayed from host application user interfaces.

  • Habilitar las aplicaciones de WPF para que se ejecuten de forma segura en varios escenarios de dominio de aplicación.Enabling WPF applications to run safely in multiple application domain scenarios.

  • Impedir el acceso no válido a los identificadores de ventana de la interfaz de usuario de complemento cuando los complementos se ejecutan con aislamiento de seguridad (es decir, un espacio aislado de seguridad de confianza parcial).Preventing illegal access to add-in UI window handles when add-ins run with security isolation (that is, a partial-trust security sandbox). La ViewToContractAdapter llamada garantiza esta seguridad:Calling ViewToContractAdapter ensures this security:

    • En el modelo de programación "el complemento devuelve una interfaz de usuario", la única manera de pasar el identificador de ventana para una interfaz de usuario de complemento a través del ViewToContractAdapterlímite de aislamiento es llamar a.For the "add-in returns a UI" programming model, the only way to pass the window handle for an add-in UI across the isolation boundary is to call ViewToContractAdapter.

    • Para el modelo de programación "el complemento es una interfaz de usuario", QueryContract se requiere invalidar en el adaptador del complemento y ViewToContractAdapter llamar a (como se muestra en los ejemplos anteriores), como llama a la implementación del QueryContract adaptador del complemento desde el adaptador del host.For the "add-in is a UI" programming model, overriding QueryContract on the add-in-side adapter and calling ViewToContractAdapter (as shown in the preceding examples) is required, as is calling the add-in-side adapter's QueryContract implementation from the host-side adapter.

  • Se proporciona protección para la ejecución de varios dominios de aplicaciones.Providing multiple application domain execution protection. Dadas las limitaciones de los dominios de aplicación, las excepciones no controladas que se producen en los dominios de aplicación del complemento provocan que toda la aplicación se bloquee, aunque exista el límite de aislamiento.Due to limitations with application domains, unhandled exceptions that are thrown in add-in application domains cause the entire application to crash, even though the isolation boundary exists. Sin embargo, WPF y el modelo de complemento de .NET Framework proporcionan una manera sencilla de solucionar este problema y mejorar la estabilidad de la aplicación.However, WPF and the .NET Framework add-in model provide a simple way to work around this problem and improve application stability. Un complemento de WPF que muestra una interfaz de usuario crea Dispatcher un para el subproceso en el que se ejecuta el dominio de aplicación, si la aplicación host es una aplicación de WPF.A WPF add-in that displays a UI creates a Dispatcher for the thread that the application domain runs on, if the host application is a WPF application. Puede detectar todas las excepciones no controladas que se producen en el dominio de aplicación mediante UnhandledException el control del evento de los complementos Dispatcherde WPF.You can detect all unhandled exceptions that occur in the application domain by handling the UnhandledException event of the WPF add-in's Dispatcher. Puede obtener el Dispatcher de la CurrentDispatcher propiedad.You can get the Dispatcher from the CurrentDispatcher property.

Limitaciones del complemento de WPFWPF Add-In Limitations

Además de las ventajas que WPF agrega a los comportamientos predeterminados HwndHostproporcionados por HwndSourcelos identificadores de ventana de, y, también hay limitaciones en las interfaces de usuario de complementos que se muestran desde las aplicaciones host:Beyond the benefits that WPF adds to the default behaviors supplied by HwndSource, HwndHost, and window handles, there are also limitations for add-in user interfaces that are displayed from host applications:

  • Las interfaces de usuario de complementos que se muestran desde una aplicación host no respetan el comportamiento de recorte de la aplicación host.Add-in user interfaces displayed from a host application do not respect the host application's clipping behavior.

  • El concepto de espacio aéreo en los escenarios de interoperabilidad también se aplica a los complementos (consulte Información general sobre áreas de la tecnología).The concept of airspace in interoperability scenarios also applies to add-ins (see Technology Regions Overview).

  • Los servicios de interfaz de usuario de una aplicación host, como la herencia de recursos, el enlace de datos y los comandos, no están disponibles automáticamente para las interfaces de usuario de complementos.A host application's UI services, such as resource inheritance, data binding, and commanding, are not automatically available to add-in user interfaces. Para proporcionar estos servicios al complemento, es preciso actualizar la canalización.To provide these services to the add-in, you need to update the pipeline.

  • Una interfaz de usuario de complementos no se puede girar, escalar, sesgar ni verse afectada de ningún modo por una transformación (consulte información general sobretransformaciones).An add-in UI cannot be rotated, scaled, skewed, or otherwise affected by a transformation (see Transforms Overview).

  • El contenido que se encuentra dentro de las interfaces de usuario del complemento que se representa System.Drawing mediante las operaciones de dibujo del espacio de nombres puede incluir la combinación alfa.Content inside add-in user interfaces that is rendered by drawing operations from the System.Drawing namespace can include alpha blending. Sin embargo, una interfaz de usuario de complemento y la interfaz de usuario de la aplicación host que la contiene deben ser de 100% opacas; en otras palabras, la Opacity propiedad en ambos debe establecerse en 1.However, both an add-in UI and the host application UI that contains it must be 100% opaque; in other words, the Opacity property on both must be set to 1.

  • Si la AllowsTransparency propiedad de una ventana de la aplicación host que contiene una interfaz de usuario de complemento está establecida trueen, el complemento es invisible.If the AllowsTransparency property of a window in the host application that contains an add-in UI is set to true, the add-in is invisible. Esto es así incluso si la interfaz de usuario del complemento es 100% opaca (es decir, Opacity la propiedad tiene un valor de 1).This is true even if the add-in UI is 100% opaque (that is, the Opacity property has a value of 1).

  • Una interfaz de usuario de complemento debe aparecer encima de otros elementos de WPF en la misma ventana de nivel superior.An add-in UI must appear on top of other WPF elements in the same top-level window.

  • Ninguna parte de la interfaz de usuario de un complemento puede representarse mediante VisualBrush.No portion of an add-in's UI can be rendered using a VisualBrush. En su lugar, el complemento puede tomar una instantánea de la interfaz de usuario generada para crear un mapa de bits que se puede pasar a la aplicación host mediante métodos definidos por el contrato.Instead, the add-in may take a snapshot of the generated UI to create a bitmap that can be passed to the host application using methods defined by the contract.

  • Los archivos multimedia no se pueden reproducir MediaElement desde un en una interfaz de usuario de complemento.Media files cannot be played from a MediaElement in an add-in UI.

  • Los eventos del mouse generados para la interfaz de usuario del complemento no se han recibido ni generado por la IsMouseOver aplicación host, y la propiedad de la interfaz falsede usuario de la aplicación host tiene un valor de.Mouse events generated for the add-in UI are neither received nor raised by the host application, and the IsMouseOver property for host application UI has a value of false.

  • Cuando el foco se desplaza entre los controles de una interfaz de usuario del GotFocus complemento LostFocus , la aplicación host no recibe ni genera los eventos y.When focus shifts between controls in an add-in UI, the GotFocus and LostFocus events are neither received nor raised by the host application.

  • La parte de una aplicación host que contiene una interfaz de usuario de complemento aparece en blanco cuando se imprime.The portion of a host application that contains an add-in UI appears white when printed.

  • Todos los distribuidores (consulte Dispatcher) creados por la interfaz de usuario del complemento deben cerrarse manualmente antes de que se descargue el complemento propietario si la aplicación host continúa la ejecución.All dispatchers (see Dispatcher) created by the add-in UI must be shut down manually before the owner add-in is unloaded if the host application continues execution. El contrato puede implementar métodos que permitan que la aplicación host señale el complemento antes de que se descargue el complemento, lo que permite que la interfaz de usuario del complemento cierre sus distribuidores.The contract can implement methods that allow the host application to signal the add-in before the add-in is unloaded, thereby allowing the add-in UI to shut down its dispatchers.

  • Si una interfaz de usuario del complemento es InkCanvas o InkCanvascontiene, no puede descargar el complemento.If an add-in UI is an InkCanvas or contains an InkCanvas, you cannot unload the add-in.

Optimización del rendimientoPerformance Optimization

De forma predeterminada, cuando se usan varios dominios de aplicación, se cargan todos los ensamblados .NET Framework necesarios para cada aplicación en el dominio de esa aplicación.By default, when multiple application domains are used, the various .NET Framework assemblies required by each application are all loaded into that application's domain. Como consecuencia, el tiempo requerido para crear nuevos dominios de aplicación e iniciar aplicaciones en ellas puede afectar al rendimiento.As a result, the time required for creating new application domains and starting applications in them might affect performance. Sin embargo, el .NET Framework proporciona una manera de reducir las horas de inicio, ya que indica a las aplicaciones que compartan los ensamblados entre los dominios de aplicación si ya se han cargado.However, the .NET Framework provides a way for you to reduce start times by instructing applications to share assemblies across application domains if they are already loaded. Para ello, se usa el LoaderOptimizationAttribute atributo, que se debe aplicar al método de punto de entradaMain().You do this by using the LoaderOptimizationAttribute attribute, which must be applied to the entry point method (Main). En este caso, solo debe usar el código para implementar la definición de aplicación (consulte Información general sobre la administración de aplicaciones).In this case, you must use only code to implement your application definition (see Application Management Overview).

Vea tambiénSee also