Extensión de clientes
En una aplicación que realiza la llamada, el nivel de modelo de servicio es responsable de traducir invocaciones de método en el código de la aplicación a mensajes salientes, insertarlos en los canales subyacentes, traducir los resultados en valores devueltos y los parámetros de salida en el código de la aplicación, y devolver los resultados al autor de la llamada. Las extensiones de modelo de servicio modifican o implementan el comportamiento de la comunicación o la ejecución y características implicadas en la funcionalidad de distribuidor o cliente, comportamientos personalizados, interceptación de mensajes y parámetros, y otra funcionalidad de extensibilidad.
En este tema se describe cómo usar las clases ClientRuntime y ClientOperation en una aplicación cliente de Windows Communication Foundation (WCF) para modificar el comportamiento de ejecución predeterminado de un cliente WCF o para interceptar o modificar mensajes, parámetros o valores devueltos antes o después de enviarlos o recuperarlos de la capa de canal. Para más información sobre cómo extender el entorno de ejecución del servicio, consulte Extensión de instancias de Dispatcher. Para más información sobre los comportamientos que modifican e insertan objetos de personalización en el entorno de ejecución del cliente, consulte Configuración y extensión del entorno de ejecución con comportamientos.
Clientes
En un cliente, un objeto de cliente o un canal de cliente WCF convierte las invocaciones de método en mensajes entrantes y salientes para los resultados de la operación devueltos a la aplicación que realiza la llamada. (Para más información sobre los tipos de cliente, consulte Arquitectura de cliente WCF).
Los tipos de cliente WCF tienen tipos de entorno de ejecución que controlan esta funcionalidad de nivel de punto de conexión y operación. Cuando una aplicación llama a una operación, ClientOperation traduce los objetos salientes en un mensaje, procesa los interceptores, confirma que la llamada saliente cumple con el contrato de destino y entrega el mensaje saliente a ClientRuntime, que es responsable de crear y administrar los canales salientes (y canales entrantes en el caso de los servicios dúplex), administrar el procesamiento de mensajes salientes adicionales (como la modificación del encabezado), procesar los interceptores de mensajes en ambas direcciones y enrutar las llamadas dúplex entrantes hacia el objeto DispatchRuntime en el lado del cliente adecuado. ClientOperation y ClientRuntime proporcionan servicios similares cuando los mensajes (incluidos los errores) se devuelven al cliente.
Estas dos clases de entorno de ejecución son la extensión principal para personalizar el procesamiento de objetos y canales de cliente WCF. La clase ClientRuntime permite a los usuarios interceptar y extender la ejecución del cliente por todos los mensajes en el contrato. La clase ClientOperation permite a los usuarios interceptar y extender la ejecución del cliente para todos los mensajes en una operación determinada.
La modificación de las propiedades o la inserción de personalizaciones se realiza mediante los comportamientos del contrato, del extremo y de la operación. Para más información sobre cómo usar estos tipos de comportamientos para realizar las personalizaciones del entorno de ejecución del cliente, consulte Configuración y extensión del entorno de ejecución con comportamientos.
Escenarios
Hay varias razones para extender el sistema cliente, incluidas:
Validación personalizada del mensaje. Un usuario puede querer exigir que un mensaje sea válido para un determinado esquema. Esto se puede hacer implementando la interfaz IClientMessageInspector y asignando la implementación en la propiedad MessageInspectors. Para obtener ejemplos, vea Cómo: Inspeccionar o modificar mensajes en el cliente y Cómo: Inspeccionar o modificar mensajes en el cliente.
Registro personalizado de mensajes. Un usuario puede desear inspeccionar y registrar un conjunto de mensajes de la aplicación que fluyen a través de un extremo. Esto también se puede lograr con las interfaces del interceptor de mensajes.
Transformaciones personalizadas del mensaje. En lugar de modificar el código de aplicación, el usuario puede querer aplicar ciertas transformaciones al mensaje en el tiempo de ejecución (por ejemplo, para controlar las versiones). Esto también se puede lograr, de nuevo, con las interfaces del interceptor de mensajes.
Modelo de datos personalizado. A un usuario le puede interesar tener un modelo de datos o de serialización distinto que el admitido de manera predeterminada en WCF (es decir, objetos System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer y System.ServiceModel.Channels.Message). Esto se puede hacer implementando las interfaces del formateador de mensajes. Para obtener más información, vea System.ServiceModel.Dispatcher.IClientMessageFormatter y la propiedad ClientOperation.Formatter.
Validación personalizada de parámetros. Un usuario puede querer exigir que los parámetros con tipo sean válidos (por oposición a XML). Esto puede hacerse mediante las interfaces del inspector de parámetros. Para ver un ejemplo, consulte Inspección o modificación de parámetros o Validación del cliente.
Uso de la clase ClientRuntime
La clase ClientRuntime es un punto de extensibilidad al que puede agregar objetos de extensión que interceptan los mensajes y extienden el comportamiento del cliente. Los objetos de interceptación pueden procesar todos los mensajes de un contrato determinado, procesar solo los mensajes para operaciones determinadas, realizar la inicialización personalizada de canales e implementar otro comportamiento de aplicación cliente personalizado.
La propiedad CallbackDispatchRuntime devuelve el objeto en tiempo de ejecución de envío para los clientes de devolución de llamada iniciados por el servicio.
La propiedad OperationSelector acepta un objeto de selector de operación personalizado.
La propiedad ChannelInitializers habilita la adición de un inicializador de canales que puede inspeccionar o modificar el canal del cliente.
La propiedad Operations obtiene una colección de objetos ClientOperation a la que puede agregar interceptores de mensajes personalizados que proporcionan funcionalidad específica a los mensajes de esa operación.
La propiedad ManualAddressing permite a una aplicación desactivar algunos encabezados de direccionamiento automáticos para controlar directamente el direccionamiento.
La propiedad Via establece el valor del destino del mensaje en el nivel de transporte para admitir intermediarios y otros escenarios.
La propiedad MessageInspectors obtiene una colección de objetos IClientMessageInspector a la que puede agregar interceptores de mensajes personalizados para todos los mensajes recorren un cliente WCF.
Además, hay varias propiedades que recuperan la información del contrato:
Si el cliente WCF es un cliente WCF dúplex, las propiedades siguientes también recuperan la información del cliente WCF de devolución de llamada:
Para extender la ejecución del cliente WCF a un cliente WCF completo, revise las propiedades disponibles en la clase ClientRuntime para ver si modificando una propiedad o implementando una interfaz y agregándola a una propiedad se crea la funcionalidad que está buscando. Una vez que haya elegido una extensión determinada que desea crear, inserte su extensión en la propiedad ClientRuntime adecuada implementando un comportamiento de cliente que proporciona el acceso a la clase ClientRuntime cuando se invoca.
Puede insertar los objetos de extensión personalizados en una colección utilizando un comportamiento de la operación (un objeto que implementa IOperationBehavior), un comportamiento del contrato (un objeto que implementa IContractBehavior) o un comportamiento del extremo (un objeto que implementa IEndpointBehavior). El objeto de comportamiento de instalación se agrega mediante programación a la colección adecuada de comportamientos, mediante declaración (implementando un atributo personalizado) o implementando un objeto BehaviorExtensionElement personalizado para permitir insertar el comportamiento con un archivo de configuración de la aplicación. Para obtener más información, consulte Configuración y extensión del tiempo de ejecución mediante comportamientos.
Para ver ejemplos que muestran la interceptación en un cliente WCF, consulte Inspección y modificación de mensajes en el cliente.
Uso de la clase ClientOperation
La clase ClientOperation es la ubicación para las modificaciones del cliente en tiempo de ejecución y el punto de inserción para las extensiones personalizadas cuyo ámbito es solo una operación de servicio. (Para modificar el comportamiento del tiempo de ejecución del cliente para todos los mensajes de un contrato, use la clase ClientRuntime.)
Use la propiedad Operations para buscar el objeto ClientOperation que representa una operación de servicio determinada. Las propiedades siguientes le permiten insertar objetos personalizados en el sistema del cliente WCF:
Use la propiedad Formatter para insertar una implementación personalizada de IClientMessageFormatter para una operación o modificar el formateador actual.
Use la propiedad ParameterInspectors para insertar una implementación personalizada de IParameterInspector o modificar la actual.
Las propiedades siguientes le permiten modificar el sistema interactuando con el formateador y los inspectores de parámetro personalizados:
Use la propiedad SerializeRequest para controlar la serialización de un mensaje saliente.
Use la propiedad DeserializeReply para controlar la deserialización de un mensaje entrante.
Utilice la propiedad Action para controlar la acción de WS-Addressing del mensaje de solicitud.
Use las propiedades BeginMethod y EndMethod para especificar qué métodos de cliente WCF están asociados a una operación asincrónica.
Use la propiedad FaultContractInfos para obtener una colección que contiene los tipos que pueden aparecer en errores de SOAP como tipo de detalle.
Use las propiedades IsInitiating y IsTerminating para controlar si una sesión se inicia o se anula, respectivamente, cuando se llama a la operación.
Utilice la propiedad IsOneWay para controlar si la operación es unidireccional.
Use la propiedad Parent para obtener el objeto ClientRuntime contenedor.
Use la propiedad Name para obtener el nombre de la operación.
Use la propiedad SyncMethod para controlar qué método se asigna a la operación.
Para extender la ejecución del cliente WCF a solo una operación de servicio, revise las propiedades disponibles en la clase ClientOperation para ver si modificando una propiedad o implementando una interfaz y agregándola a una propiedad se crea la funcionalidad que está buscando. Una vez que haya elegido una extensión determinada que desea crear, inserte su extensión en la propiedad ClientOperation adecuada implementando un comportamiento de cliente que proporciona el acceso a la clase ClientOperation cuando se invoca. Dentro de ese comportamiento, podrá modificar a continuación la propiedad ClientRuntime para ajustarse a sus requisitos.
Normalmente, implementar un comportamiento de la operación (un objeto que implementa la interfaz IOperationBehavior) es suficiente, pero también puede utilizar comportamientos del punto de conexión y del contrato para lograr lo mismo buscando OperationDescription para una operación determinada y adjuntando allí el comportamiento. Para obtener más información, consulte Configuración y extensión del tiempo de ejecución mediante comportamientos.
Para utilizar su comportamiento personalizado de la configuración, instale el comportamiento mediante un controlador de la sección de configuración de comportamiento personalizado. También puede instalar su comportamiento creando un atributo personalizado.
Para ver ejemplos que muestran la interceptación en un cliente WCF, consulte Inspección o modificación de parámetros.