Estendendo clientes
Em um aplicativo de chamada, a camada do modelo de serviço é responsável por traduzir invocações de método no código do aplicativo em mensagens de saída, empurrá-las para os canais subjacentes, traduzir resultados de volta em valores de retorno e parâmetros de saída no código do aplicativo e retornar os resultados de volta ao chamador. As extensões do modelo de serviço modificam ou implementam o comportamento de execução ou comunicação e os recursos que envolvem funcionalidade de cliente ou dispatcher, comportamentos personalizados, interceptação de mensagens e parâmetros e outras funcionalidades de extensibilidade.
Este tópico descreve como usar as classes ClientRuntime e ClientOperation em um aplicativo cliente do Windows Communication Foundation (WCF) para modificar o comportamento de execução padrão de um cliente WCF ou interceptar ou modificar mensagens, parâmetros ou retornar valores antes ou subsequentes de enviá-los ou recuperá-los da camada de canal. Para obter mais informações sobre como estender o runtime de serviço, consulte Estendendo dispatchers. Para obter mais informações sobre os comportamentos que modificam e inserem objetos de personalização no runtime do cliente, confira Configurando e estendendo o runtime com comportamentos.
Clientes
Em um cliente, um objeto cliente WCF ou canal cliente converte invocações de método em mensagens de saída e mensagens de entrada em resultados de operação que são retornados ao aplicativo de chamada. (Para obter mais informações sobre tipos de cliente, confira Arquitetura do cliente do WCF.)
Os tipos de cliente do WCF têm tipos de runtime que lidam com essa funcionalidade de ponto de extremidade e nível de operação. Quando um aplicativo chama uma operação, o ClientOperation converte os objetos de saída em uma mensagem, processa interceptadores, confirma que a chamada de saída está em conformidade com o contrato de destino e entrega a mensagem de saída para o ClientRuntime, que é responsável por criar e gerenciar canais de saída (e canais de entrada no caso de serviços duplex), manipulando o processamento de mensagens de saída extra (como modificação de cabeçalho), processando interceptadores de mensagens em ambas as direções e roteando chamadas duplex de entrada para o objeto DispatchRuntime do lado do cliente apropriado. Tanto ClientOperation quanto ClientRuntime fornecem serviços semelhantes quando as mensagens (incluindo falhas) são retornadas ao cliente.
Essas duas classes de runtime são a extensão principal para personalizar o processamento de objetos e canais do cliente WCF. A classe ClientRuntime permite que os usuários interceptem e estendam a execução do cliente em todas as mensagens no contrato. A classe ClientOperation permite que os usuários interceptem e estendam a execução do cliente em todas as mensagens em uma determinada operação.
Modificar as propriedades ou inserir personalizações é feito usando comportamentos de contrato, ponto de extremidade e operação. Para obter mais informações sobre como usar esses tipos de comportamentos para executar personalizações de runtime do cliente, confira Configurando e estendendo o runtime com comportamentos.
Cenários
Há vários motivos para estender o sistema cliente, incluindo:
Validação de mensagem personalizada. Um usuário pode querer impor que uma mensagem seja válida para um determinado esquema. Isso pode ser feito implementando a interface IClientMessageInspector e atribuindo a implementação à propriedade MessageInspectors. Para obter exemplos, consulte Como inspecionar ou modificar mensagens no cliente e Como inspecionar ou modificar mensagens no cliente.
Registro em log de mensagens personalizado. Um usuário pode querer inspecionar e registrar um conjunto de mensagens de aplicativo que fluem por meio de um ponto de extremidade. Isso também pode ser feito com as interfaces do interceptador de mensagens.
Transformações de mensagens personalizadas. Em vez de modificar o código do aplicativo, talvez o usuário queira aplicar determinadas transformações à mensagem no runtime (por exemplo, para controle de versão). Isso pode ser feito, novamente, com as interfaces do interceptador de mensagens.
Modelo de dados personalizado. Um usuário pode querer ter um modelo de dados ou serialização diferente daqueles com suporte por padrão no WCF (ou seja, objetos System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer e System.ServiceModel.Channels.Message). Isso pode ser feito implementando as interfaces do formatador de mensagens. Para obter mais informações, consulte System.ServiceModel.Dispatcher.IClientMessageFormatter e a propriedade ClientOperation.Formatter.
Validação de parâmetro personalizada Um usuário pode querer impor que os parâmetros tipado sejam válidos (em vez de XML). Isso pode ser feito usando as interfaces do inspetor de parâmetros. Para obter um exemplo, confira Como inspecionar ou modificar parâmetros ou Validação de cliente.
Usando a classe ClientRuntime
A classe ClientRuntime é um ponto de extensibilidade ao qual você pode adicionar objetos de extensão que interceptam mensagens e estendem o comportamento do cliente. Objetos de interceptação podem processar todas as mensagens em um contrato específico, processar somente mensagens para operações específicas, executar inicialização de canal personalizado e implementar outro comportamento de aplicativo cliente personalizado.
A propriedade CallbackDispatchRuntime retorna o objeto de tempo de execução de expedição para clientes de retorno de chamada iniciados pelo serviço.
A propriedade OperationSelector aceita um objeto de seletor de operação personalizado.
A propriedade ChannelInitializers habilita a adição de um inicializador de canal que pode inspecionar ou modificar o canal cliente.
A propriedade Operations obtém uma coleção de objetos ClientOperation aos quais você pode adicionar interceptadores de mensagens personalizados que fornecem funcionalidade específica às mensagens dessa operação.
A propriedade ManualAddressing permite que um aplicativo desative alguns cabeçalhos de endereçamento automático para controlar diretamente o endereçamento.
A propriedade Via define o valor do destino da mensagem no nível de transporte para dar suporte a intermediários e outros cenários.
A propriedade MessageInspectors obtém uma coleção de objetos IClientMessageInspector aos quais você pode adicionar interceptadores de mensagens personalizados para todas as mensagens que viajam por um cliente WCF.
Além disso, há várias outras propriedades que recuperam as informações do contrato:
Se o cliente WCF for um cliente WCF duplex, as seguintes propriedades também recuperarão as informações do cliente WCF de retorno de chamada:
Para estender a execução do cliente WCF em um cliente WCF inteiro, examine as propriedades disponíveis na classe ClientRuntime para verificar se modificar uma propriedade ou implementar uma interface e adicioná-la a uma propriedade cria a funcionalidade que você está buscando. Depois de escolher uma extensão específica para compilar, insira sua extensão na propriedade apropriada ClientRuntime implementando um comportamento do cliente que fornece acesso à classe ClientRuntime quando invocado.
Você pode inserir objetos de extensão personalizados em uma coleção usando um comportamento de operação (um objeto que implementa IOperationBehavior), um comportamento de contrato (um objeto que implementa IContractBehavior) ou um comportamento de ponto de extremidade (um objeto que implementa IEndpointBehavior). O objeto de comportamento de instalação é adicionado à coleção apropriada de comportamentos de forma programática, declarativa (implementando um atributo personalizado) ou implementando um objeto personalizado BehaviorExtensionElement para permitir que o comportamento seja inserido usando um arquivo de configuração de aplicativo. Para obter detalhes, confira Configurando e estendendo o runtime com comportamentos.
Para obter exemplos que demonstram interceptação em um cliente WCF, consulte Como inspecionar ou modificar mensagens no cliente.
Usando a classe ClientOperation
A classe ClientOperation é o local para modificações de tempo de execução do cliente e ponto de inserção para extensões personalizadas que têm como escopo apenas uma operação de serviço. (Para modificar o comportamento de tempo de execução do cliente para todas as mensagens em um contrato, use a classe ClientRuntime.)
Use a propriedade Operations para localizar o objeto ClientOperation que representa uma operação de serviço específica. As propriedades a seguir permitem que você insira objetos personalizados no sistema cliente do WCF:
Use a propriedade Formatter para inserir uma implementação personalizada IClientMessageFormatter para uma operação ou modificar o formatador atual.
Use a propriedade ParameterInspectors para inserir uma implementação personalizada IParameterInspector ou modificar a atual.
As propriedades a seguir permitem que você modifique o sistema na interação com o formatador e os inspetores de parâmetros personalizados:
Use a propriedade SerializeRequest para controlar a serialização de uma mensagem de saída.
Use a propriedade DeserializeReply para controlar a desserialização de uma mensagem de entrada.
Use a propriedade Action para controlar a ação WS-Addressing da mensagem de solicitação.
Use BeginMethod e EndMethod para especificar quais métodos de cliente WCF estão associados a uma operação assíncrona.
Use a propriedade FaultContractInfos para obter uma coleção que contenha os tipos que podem aparecer em falhas SOAP como o tipo de detalhe.
Use as propriedades IsInitiating e IsTerminating para controlar se uma sessão é iniciada ou interrompida, respectivamente, quando a operação é chamada.
Use a propriedade IsOneWay para controlar se a operação é uma operação unidirecional.
Use a propriedade Parent para obter o objeto que contém ClientRuntime.
Use a propriedade Name para obter o nome da operação.
Use a propriedade SyncMethod para controlar qual método é mapeado para a operação.
Para estender a execução do cliente WCF em um único serviço de operação, examine as propriedades disponíveis na classe ClientOperation para verificar se modificar uma propriedade ou implementar uma interface e adicioná-la a uma propriedade cria a funcionalidade que você está buscando. Depois de escolher uma extensão específica para compilar, insira sua extensão na propriedade apropriada ClientOperation implementando um comportamento do cliente que fornece acesso à classe ClientOperation quando invocado. Dentro desse comportamento, você pode modificar a propriedade ClientRuntime para atender aos seus requisitos.
Normalmente, implementar um comportamento de operação (um objeto que implementa a interface IOperationBehavior) é suficiente, mas você também pode usar comportamentos de ponto de extremidade e comportamentos de contrato para realizar a mesma coisa localizando o OperationDescription para uma operação específica e anexando o comportamento lá. Para obter detalhes, confira Configurando e estendendo o runtime com comportamentos.
Para usar seu comportamento personalizado na configuração, instale seu comportamento usando um manipulador de seção de configuração de comportamento personalizado. Você também pode instalar seu comportamento criando um atributo personalizado.
Para obter exemplos que demonstram a interceptação em um cliente WCF, consulte Como inspecionar ou modificar parâmetros.