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 la ejecución o comportamiento de la comunicación y características implicadas en la funcionalidad del distribuidor o cliente, comportamientos personalizados, interceptación de mensaje y parámetro, y otras funcionalidades de extensibilidad.
En este tema se describe cómo utilizar las clases ClientRuntime y ClientOperation en una aplicación cliente 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 enviar o recuperarlos desde el nivel del canal. Para obtener más información sobre cómo extender el tiempo de ejecución del servicio, vea Extensión de distribuidores. Para obtener más información sobre los comportamientos que modifican e insertan los objetos de personalización en el tiempo de ejecución del cliente, vea Configuración y extensión del tiempo de ejecución con comportamientos.
Clientes
En un cliente, un objeto de cliente WCF o canal de cliente convierte las invocaciones de método en mensajes salientes y los entrantes en resultados de la operación devueltos a la aplicación que realiza la llamada. (Para obtener más información sobre los tipos de cliente, vea Arquitectura de cliente.)
Los tipos de cliente WCF tienen tipos de tiempo de ejecución que gestionan la funcionalidad en el nivel del extremo y de la 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 en tiempo 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 obtener más información sobre cómo utilizar estos tipos de comportamientos para realizar las personalizaciones de tiempo de ejecución del cliente, vea Configuración y extensión del tiempo 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. Un usuario puede desear tener un modelo de datos o de serialización distinto que el admitido de manera predeterminada en WCF (es decir, los 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 System.ServiceModel.Dispatcher.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, vea Cómo: inspeccionar o modificar parámetros o Client Validation.
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 sólo 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 que se desplazan por 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:
- CallbackClientType
- CallbackDispatchRuntime
Para extender la ejecución del cliente WCF en 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 generar, 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, vea Configuración y extensión del tiempo de ejecución con comportamientos.
Para obtener ejemplos que muestran la interceptación en un cliente WCF, vea Cómo inspeccionar o modificar 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 sólo 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 los objetos personalizados en el sistema 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 sólo en 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 generar, 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 extremo y del contrato para lograr lo mismo buscando OperationDescription para una operación determinada y asociando allí el comportamiento. Para obtener más información, vea Configuración y extensión del tiempo de ejecución con 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 obtener ejemplos que muestran la interceptación por un cliente WCF, vea Cómo: inspeccionar o modificar parámetros.
Consulte también
Tareas
Cómo inspeccionar o modificar mensajes en el cliente
Cómo: inspeccionar o modificar parámetros