Como já falei há algum tempo, um dos tipos de mensagens suportados pelo WCF é o padrão Duplex. A finalidade desta técnica é permitir uma comunicação bidirecional, ou seja, o cliente invocar método de um serviço, bem como um serviço invocar um método do cliente. Esse tipo de comunicação permite, na maioria das vezes, um determinado serviço notificar o cliente de que algum evento ocorreu, dando a ele, uma chance de conseguir interagir com um cliente específico ou até mesmo vários clientes, através de um sistema publicador-assinante.

Aplicações Silverlight também podem precisar deste tipo de recurso, onde um serviço irá se comunicar com o cliente (que está rodando no navegador) para notificar sobre algum resultado, ou até mesmo para reportar a execução de alguma tarefa mais complexa. Felizmente, a partir da versão 2.0 do Silverlight, ele prove esta funcionalidade, e a partir a versão mais recente, Silverlight 3.0 (ainda em Beta), tornou esse trabalho mais simples. Para quem já está habituado a trabalhar com WCF, utilizar a API do mesmo em uma aplicação Silverlight (independentemente do tipo de comunicação) traz algumas limitações, quais falaremos neste artigo, principalmente dando mais foco no formato Duplex.

Ao utilizar um binding que suporte o tipo de comunicação Duplex, ele criará internamente um endpoint para que o serviço consiga invocar o callback do lado do cliente. Como a aplicação cliente está rodando dentro do navegador, ela não poderá criar um “listener” para receber os eventuais callbacks que o serviço possa disparar, impedindo a utilização dos bindings tradicionais para este cenário. Para resolver essa deficiência, o Silverlight utiliza o recurso conhecido como “poll”. Com esta técnica, o cliente ficará interrogando o serviço para determinar se há alguma mensagem que deve ser recebida por ele.

Antes de falarmos sobre as classes que dão suporte a esta técnica, vamos analisar os assemblies necessários. O Silverlight 2.0 e 3.0 traz dois assemblies com o nome de System.ServiceModel.PollingDuplex.dll, que estão em diretórios diferentes. Um deles contido no diretório %ProgramFiles%Microsoft SDKsSilverlightVERSAOLibrariesServer e outro no diretório %ProgramFiles%Microsoft SDKsSilverlightVERSAOLibrariesClient. Como podemos perceber, um dos assemblies será utilizado pelo lado do serviço, onde trará os tipos necessários para a criação de serviços Duplex, enquanto o segundo deverá ser utilizado por aplicações cliente, para o consumo de serviços Duplex.

O binding responsável por fornecer toda a infraestrutura necessária para a comunicação Duplex no Silverlight é chamado de PollingDuplexHttpBinding. Este binding herda diretamente da classe BasicHttpBinding, e customiza o mesmo para suportar o “poll” através do protocolo HTTP. Este binding utiliza os protocolos abertos Net Duplex e WS-Make Connection (WS-MC). O protocolo Net Duplex é utilizado para estabelecer uma sessão entre o cliente e o serviço, para que seja possível correlacionar as mensagens que serão trocadas. Já o protocolo WS-MC, faz o trabalho necessário para a criação de um canal dentro da sessão previamente criada, e que será utilizado pelo serviço para criar a mensagem que deve ser entregue ao cliente ou para o cliente interrogar o serviço.

Em termos de implementação do serviço nada muda, ou seja, a criação de uma Interface que representará o callback continuará sendo necessária. Além disso, a forma de invocarmos o callback continua sendo através do método GetCallbackChannel<T> da classe OperationContext. Para entender mais detalhes de como implementar um serviço que suporte callbacks, consulte este artigo. Se você já sabe construir serviços que utilizam callbacks, você notará que não há nenhuma diferença na criação destes mesmos serviços para Silverlight.

Depois de criado o contrato do serviço, de callback e da classe que representará o serviço, precisamos configurar o host para expor o serviço através do novo binding que mencionamos acima. Infelizmente, até a versão atual (Silverlight 3.0 Beta), ainda não existe suporte para a configuração deste tipo de serviços através de arquivos de configuração (como o Web.config). Na maioria das vezes o serviço estará hospedado no IIS (mas poderá utilizar outros hosts) e a deficiência na configuração declarativa, nos obrigará a customizar o ServiceHost e o ServiceHostFactoryBase (responsável por criar as instâncias da classe ServiceHost). Aqui não há diferenças em relação a forma que já conhecemos para a configuração de um endpoint, ou seja, continuamos necessitando o endereço, binding e contrato. A única atenção que temos que ter é especificar um binding que suporte este tipo de comunicação.

Utilizaremos o IIS como hosting (via arquivo *.svc), e como mencionado acima, será necessário criarmos uma especialização da classe ServiceHost e também da ServiceHostFactoryBase. Isso é mostrado através do código abaixo, e note que dentro do método InitializeRuntime adicionamos os endpoints necessários (através do método AddServiceEndpoint), incluindo um com um binding customizado, e entre os elementos que irão compor ele, temos a instância da classe PollingDuplexBindingElement, que habilita a comunicação Duplex entre o serviço e o cliente.

public class PollingDuplexServiceHostFactory : ServiceHostFactoryBase
{
    public override ServiceHostBase CreateServiceHost(
        string constructorString, Uri[] baseAddresses)
    {
        return new PollingDuplexServiceHost(baseAddresses);
    }

    private class PollingDuplexServiceHost : ServiceHost
    {
        public PollingDuplexServiceHost(params Uri[] addresses)
            : base(typeof(Servico), addresses)
        {
            this.Description.Behaviors.Add(
                new ServiceMetadataBehavior() { HttpGetEnabled = true });
        }

        protected override void InitializeRuntime()
        {
            this.AddServiceEndpoint(
                typeof(IContrato),
                new CustomBinding(
                    new PollingDuplexBindingElement(),
                    new TextMessageEncodingBindingElement(),
                    new HttpTransportBindingElement()),
                “”);

            this.AddServiceEndpoint(
                typeof(IMetadataExchange),
                MetadataExchangeBindings.CreateMexHttpBinding(),
                “mex”);

            base.InitializeRuntime();
        }
    }
}

É importante dizer ao runtime do WCF que criamos uma factory própria, e para vinculá-la ao serviço, utilizamos a diretiva @ServiceHost no arquivo *.svc. Essa diretiva possui um atributo chamado Factory, onde podemos especificar o tipo de uma classe que implemente a classe base ServiceHostFactoryBase.

<%@ ServiceHost
    Language=”C#”
    Debug=”true”
    Factory=”Web.UI.Host.Network.PollingDuplexServiceHostFactory” %>

Com isso finalizamos tudo o que é necessário por parte do serviço. Com o endereço do mesmo em mãos, devemos referenciá-lo no cliente através da IDE do Visual Studio .NET ou através do utilitário de linha de comando chamado slsvcutil.exe. Ao fazer isso, uma classe que corresponderá ao proxy será criada mas o arquivo de configuração não terá nenhuma informação. Isso se deve ao fato de que a versão atual (Silverlight 3.0 Beta) ainda não traz suporte a este tipo de funcionalidade. Um outro detalhe importante que você notará ao explorar a classe que representa o proxy, é que não haverá a versão síncrona do método, pois o Silverlight não possui isso nativamente. Assim, todos os métodos expostos pelo contrato, o cliente somente terá a versão assíncrona dos mesmos, que é composta por um par de métodos, BeginOperacao e EndOperacao. Apesar destes dois métodos existirem, eles são privados e não estão acessíveis além do proxy, que disponibiliza o modelo baseado em eventos para o consumo. Para maiores detalhes de como o processo assíncrono funciona, consulte este artigo.

Da mesma forma que utilizamos um binding customizado do lado do serviço, temos que fazer o mesmo do lado do cliente. Temos apenas que tomar os devidos cuidados para utilizar o assembly System.ServiceModel.PollingDuplex.dll que está no diretório %ProgramFiles%Microsoft SDKsSilverlightVERSAOLibrariesClient. Veja que estamos montando o binding customizado com os mesmos elementos (e na mesma ordem) que utilizamos na configuração do serviço, apenas nos atentando que a classe PollingDuplexBindingElement está no assembly que faz parte do cliente. O código abaixo mostra como devemos proceder para utilizar o proxy que foi gerado:

private Servico.ContratoClient _proxy;

public MainPage()
{
    InitializeComponent();

    EndpointAddress ea = new EndpointAddress(“http://127.0.0.1.:51116/Servico.svc”);
    CustomBinding cb =
        new CustomBinding(
            new PollingDuplexBindingElement(),
            new TextMessageEncodingBindingElement(),
            new HttpTransportBindingElement());

    _proxy = new ContratoClient(cb, ea);
    _proxy.OnCallbackReceived += (o, e) => MessageBox.Show(e.msg);
}

private void Button_Click(object sender, RoutedEventArgs e)
{
    _proxy.PingAsync(“Teste”);
}

Antes de invocar o método Ping, é necessário nos vincularmos ao evento OnCallbackReceived, que será disparado quando a operação finalizar. Note que as operações são sufixadas com a palavra “Async”, e haverá sempre um evento que corresponde ao término da execução da respectiva operação.

Limites e Timeouts

As classes que vimos acima possuem algumas propriedades que podemos utilizar para ter um maior controle em alguns timeouts, e também na quantidade máxima de sessões e de mensagens que podem ser criadas. Para iniciar vamos falar sobre as propriedades fornecidas pela classe PollingDuplexBindingElement do serviço. As propriedades que gerenciam as quantidades máximas são: MaxPendingSessions e MaxPendingMessagesPerSession. A primeira determina a quantidade máxima de sessões suportadas, enquanto a segunda determina a quantidade máxima de mensagens para cada sessão criada. Com relação aos timeouts, temos as propriedades InactivityTimeout e ServerPollTimeout. A primeira propriedade determina um intervalo de tempo que o serviço pode passar sem nenhuma atividade antes do canal se tornar inválido. Já a segunda propriedade, especifica o tempo em que o serviço irá monitorar o cliente anter de retornar.

Do lado do cliente apenas temos duas propriedades, também fornecidas pela classe PollingDuplexBindingElement: InactivityTimeout e ClientPollTimeout. A primeira propriedade tem a mesma finalidade da propriedade InactivityTimeout do lado do serviço, enquanto a propriedade ClientPollTimeout determina o intervalo de tempo que o cliente ficará interrogando o serviço, para verificar a existência de novas mensagens. Todas essas propriedades devem ser configuradas antes da conexão ser estabelecida entre o cliente e o serviço.

Conclusão: Felizmente o Silverlight já traz suporte à comunicação Duplex. Como vimos no decorrer deste artigo, o único binding que possibilita isso em aplicações Silverlight é o PollingDuplexHttpBinding. Como estamos atualmente na versão Beta, ainda há algumas deficiências, como é o caso da ausência do suporte a configuração declarativa deste binding (via arquivo Web.config), que torna o processo de desenvolvimento um pouco mais trabalhoso e propício a erros. De qualquer forma, conseguimos atingir o nosso objetivo, que é proporcionar uma boa interatividade, já que podemos inicar uma tarefa e o serviço nos notificar quando a mesma finalizar.

SLComWCF.zip (92.46 kb)

O WCF fornece um conjunto de classes que nos permite extrair informações a respeito de um determinado serviço. Como já sabemos, o serviço pode ou não expor as informações (binding, contrato, endereço) através de um documento, que é conhecido como WSDL. Ao extrair essas informações, podemos ter acesso aos contratos, o endereço onde o serviço está publicado e também ao respectivo binding, que define como será o canal de comunicação. Com essas informações, podemos tornar o nosso código mais dinâmico, e menos dependente de uma configuração que, muitas vezes, está em hard-code.

A primeira classe que nos ajudará nisso é a MetadataExchangeClient. Com o endereço até o documento WSDL, ela é capaz de fazer o download do mesmo através do protocolo WS-MetadataExchange. Como podemos notar no exemplo abaixo, ainda em seu construtor especificamos se o modo de requisição será através de uma requisição WS-Transfer GET ou uma requisição HTTP GET. Para capturar o resultado, utilizamos o método GetMetadata, que retorna uma instância da classe MetadataSet, contendo uma coleção de seções (representadas pela classe MetadataSection), que serão utilizadas a seguir, pela classe WsdlImporter.

A classe WsdlImporter converte as informações expostas pelo WSDL, em classes que representam os endpoints, e disponibiliza vários métodos, onde podemos extrair esses endpoints individualmente, ou retornar todos os endpoints encontrados no serviço. O método ImportAllEndpoints retorna uma coleção, onde cada elemento é representado pela classe ServiceEndpoint, que por sua vez, descreve através de várias propriedades, todas as informações que estão relacionadas à um determinado endpoint, ou seja, o famoso ABC.

MetadataExchangeClient proxy =
    new MetadataExchangeClient(
        new Uri("net.tcp://localhost:9292/mex"),
        MetadataExchangeClientMode.MetadataExchange);

ServiceEndpointCollection endpoints = new WsdlImporter(proxy.GetMetadata()).ImportAllEndpoints();

foreach (ServiceEndpoint se in endpoints)
{
    Console.WriteLine("Address: {0}", se.Address);
    Console.WriteLine("Binding: {0}", se.Binding);
    Console.WriteLine("Contract: {0}", se.Contract.Name);

    foreach (OperationDescription od in se.Contract.Operations)
        Console.WriteLine("tOperation: {0} – IsOneWay: {1}", od.Name, od.IsOneWay);
}

Todas as classes utilizadas aqui estão debaixo do namespace System.ServiceModel.Description. Além disso, é importante dizer que isso não substitui o protocolo WS-Discovery, pois conhecemos qual é o endereço até o documento WSDL.

Uma das exceções mais comuns quando se utiliza WCF é a TimeoutException, com a seguinte mensagem:

“The request channel timed out while waiting for a reply after 00:01:00. Increase the timeout value passed to the call to Request or increase the SendTimeout value on the Binding. The time allotted to this operation may have been a portion of a longer timeout.”

Muitas vezes, quando se consome um serviço WCF, muitas pessoas esquecem de fechar o proxy, que é o responsável pela comunicação entre o cliente e o serviço. Por padrão, o modo de gerenciamento de instâncias do serviço é o PerSession. Isso quer dizer que haverá uma instância do serviço para atender cada instância do proxy que é criada pelas aplicações clientes.

O problema que mencionei acima começará acontecer quando a quantidade máxima de conexões for atingida. Por mais que você aumente o throttle, a limitação é imposta pelo sistema operacional. Windows Vista Home e Premium tem um limite de 3 conexões; já o Vista Ultimate e Professional (e acredito que o XP Professional também), estão limitados à 10 conexões; e, por fim, as versões de servidor, possuem um número ilimitado. Somente em ambientes de servidores que o throttle poderá, de forma mais clara, ter uma maior interferência/utilidade.

Ao manter o proxy aberto, fará com que esse “contador” nunca decremente, e facilmente chegará ao limite estabelecido pelo sistema operacional ou pelo throttle, e além desse limite atingido, há sempre recursos que estão sendo presos de forma desnecessária. Sendo assim, sempre feche explicitamente o proxy através do método Close, ou se preferir, basta envolvê-lo em um bloco using (com os devidos cuidados), que implicitamente o método Dispose será chamado, que internamente invocará o método Close.

Em qualquer tecnologia de aplicação distribuída, há vários elementos que trabalham em conjunto para fazer tudo funcionar. Na maioria das vezes que utilizamos alguma dessas tecnologias, não nos preocupamos como o processo acontece nos bastidores. Na verdade, a idéia é essa mesma, ou seja, no primeiro momento, não há necessidade de conhecer níveis mais baixos, justamente porque a tecnologia os abstrai.

Já quando as coisas começam a ficar mais complexas, talvez seja o momento de entender o funcionamento interno de forma mais aprofundada, a fim de analisar o porque daquele determinado comportamento, ou ainda, caso você queira customizar ou interceptar algum ponto da execução. A finalidade deste artigo é demonstrar a classe Message (System.ServiceModel.Channels), responsável por representar o envelope SOAP dentro da infraestrutura do WCF.

Em vários artigos anteriores, eu mencionei a classe Message, principalmente quando falado sobre a codificação e extensibilidade da mensagem. Do lado do remetente da mensagem, haverá um encoder, responsável por recuperar a instância da classe Message, transformá-la em um stream de bytes e enviá-la para o destino através da rede. Já do lado do destinatário, o encoder captura a sequência de bytes da rede e a transforma em uma instância da classe Message novamente, para que a mesma possa ser processada.

A instância da classe Message, que no primeiro momento é criada pelo runtime,  é a forma tipada de acesso ao envelope SOAP, que traz diversas informações importantes. Entre elas temos a operação requisitada pelo cliente, seus respectivos parâmetros e dados contextuais, refletindo o nível de segurança, transações, mensagens confiáveis, etc. O protocolo SOAP é baseado em XML, e sua estrutura consiste basicamente em duas seções: headers e body. Os headers são as informações contextuais da requisição (não confunda headers do SOAP com headers de um protocolo como o HTTP); já o body é a seção dentro do SOAP que armazena as informações (parâmetros) exigidos pela operação que será executada. Abaixo temos a representação XML da classe Message:

<s:Envelope
  xmlns:a="http://www.w3.org/2005/08/addressing&quot;
  xmlns:s="http://www.w3.org/2003/05/soap-envelope"&gt;
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.israelaece.com/srv/cadastrar</a:Action&gt;
  </s:Header>
  <s:Body>
    <Program.Usuario
      xmlns:i="http://www.w3.org/2001/XMLSchema-instance&quot;
      xmlns="http://schemas.datacontract.org/2004/07/ConsoleApplication1"&gt;
      <Nome>Israel Aece</Nome>
    </Program.Usuario>
  </s:Body>
</s:Envelope>

É importante dizer que nem sempre o conteúdo da classe Message vai ser representado por XML baseando-se no SOAP. Em alguns cenários, a serialização da mensagem deverá seguir um outro formato, como por exemplo, quando você expõe um serviço através de POX (Plain Old XML), eliminando a estrutura SOAP. Neste caso, a classe Message conseguirá se adaptar perfeitamente a esse formato.

Antes de analisarmos a estrutura da classe Message, devemos entender sobre alguns novos tipos que foram adicionados junto com o WCF para melhorar a serialização/deserialização da classe Message. A Microsoft adicionou três novos tipos debaixo do namespace System.Xml (Assembly System.Runtime.Serialization.dll): XmlDictionary, XmlDictionaryWriter e XmlDictionaryReader. Como o padrão XML utilizado pelo WCF possue várias características específicas, essas classes foram desenhadas exclusivamente para transformar a classe Message em um encoding específico (Text, Binary e MTOM).

Como o próprio nome diz, a classe XmlDictionary é um dicionário (chave/valor), utilizado pelo WCF para reduzir o tamanho das tags XML (não do conteúdo) que, consequentemente, irá gerar uma mensagem menor. Isso obrigará ambos os lados compartilharem o mesmo dicionário, para conseguir interpretar a mensagem.

A classe XmlDictionaryWriter trabalha diretamente com a serialização e codificação da classe Message. Ela herda da classe XmlWriter, mas ainda continua sendo uma classe abstrata. Essa classe define três métodos estáticos que recebem um stream como parâmetro (que servirá como output) e retornam as implementações concretas desta classe, sendo: CreateTextWriter, CreateBinaryWriter e CreateMtomWriter. Cada um desses métodos retornará uma classe que herda direta ou indiretamente da classe XmlDictionaryWriter, correspondendo as codificações suportadas pelo WCF, que por padrão são: Text, Binary ou MTOM, respectivamente. Ainda há um método estático chamado CreateDictionaryWriter, que serve como um facilitador quando temos um objeto do tipo XmlWriter e queremos “transformá-lo” em XmlDictionaryWriter.

De forma semelhante o XmlDictionaryWriter trabalha o XmlDictionaryReader. O XmlDictionaryReader herda diretamente da classe XmlReader, e serve como base para as classes que são responsáveis por ler o conteúdo serializado e codificado em XML. Esta classe também fornece métodos estáticos que retornam as implementações concretas de cada leitor, sendo: CreateTextReader, CreateBinaryReader, CreateMtomReader e CreateDictionaryReader. Esses métodos recebem como parâmetro um stream ou array de bytes representando o conteúdo codificado em um determinado tipo.

Além destas classes operarem com o formato de XML Documents, elas também podem manipular XML Infosets. O padrão Infosets permite expressar vários formatos de documentos XML (que possuem diferentes estruturas e regras de análise) em um formato único, definindo os elementos e atributos que o documento contém, de uma forma completamente diferente da sua representação. Isso torna tudo muito flexível, já que possibilita novos tipos de codificação. O WCF separa a serialização da codificação, o que faz com ele primeiramente serialize a classe Message em Infosets, e depois disso, codifica esses Infosets em um formato específico, utilizando os que já são fornecidos pela plataforma (Text, Binary ou MTOM), ou criando um customizado. Esse padrão também influencia no envelope SOAP gerado pelo WCF, mas vamos discutir isso mais adiante.

O exemplo a seguir mostra como podemos proceder para testar o funcionamento e analisar a geração de cada um dos tipos que vimos acima. Note que estou utilizando o método CreateMtomWriter, mas poderia ser qualquer um dos outros métodos, obviamente, alterando alguns parâmetros na chamada, de acordo com a exigência de cada um deles. Neste exemplo, ele irá serializar tudo o que estamos digitando em XML Infosets, e em seguida, codificar no padrão MTOM.

using (FileStream fs = new FileStream("Dados.mtom", FileMode.Create))
{
    using (XmlDictionaryWriter writer =
            XmlDictionaryWriter.CreateMtomWriter(fs, Encoding.UTF8, 1024, "application/xop+xml"))
    {
        writer.WriteStartElement("teste");
        writer.WriteString("algum valor");
        writer.WriteEndElement();
    }
}
 
De volta a classe Message, ela está fortemente vinculada a uma das versões do protocolo SOAP existente no mercado. Como já foi falado acima, assim como o envelope SOAP, a classe Message também possui as seções que determinam os headers e o body. As regras para ler e escrever os dados no body e nos headers são diferentes, por exemplo, os headers sempre serão buferizados na memória e podem ser acessados em qualquer ordem e quantas vezes desejar, enquanto o body pode somente ser lido uma única vez e pode ser streamed. Para maiores informações sobre a comparação entre buffered e streamed, consulte este artigo.

Na maioria das vezes, a criação da classe Message é feita pelo próprio WCF. Em alguns cenários, você pode utilizar alguns pontos de extensibilidade para interceptar a mensagem e, consequentemente, extrair e/ou gravar informações nesta classe. Também temos a possibilidade de confeccionar um contrato que aceite ou devolva instâncias das classe Message, e quando isso acontece, há algumas restrições, como por exemplo:

• A operação não pode ter qualquer parâmetro de saída (out) ou de referência (ref).
• Não pode haver mais do que um parâmetro. Se houver um parâmetro, ele deve ser do tipo Message ou ter o ser um contrato de mensagem.
• O retorno de ser void, Message ou um contrato de mensagem.

Para iniciar, vamos analisar as – poucas – propriedades que essa classe fornece. Para começar, vamos analisar as propriedades Headers e Properties. A prmieira delas representa a coleção de headers existentes em uma mensagem e influenciarão no processamento dela, já que podem armazenar informações de correlação, transações, segurança, mensagens confiáveis, etc., tudo de acordo com as especificações WS-*, ou seja, esses headers são utilizados pela própria infraestrutura do WCF e ultrapassam possíveis intermediários, chegando até o seu destino final. Já a propriedade Properties expõe um dicionário de dados, e essas informações são utilizadas "localmente", não ultrapassando possíveis intermediários. O próprio WCF já utiliza isso em alguns casos como, por exemplo, nos protocolos existentes e suportados por ele. Caso o transporte seja realizado através do protocolo HTTP, os detalhes específicos da requisição/protocolo (HTTP Headers) são armazenados neste dicionário, "fora" da mensagem.

Há duas propriedades públicas boleanas, chamada de IsEmpty e IsFault. A primeira delas, indica se a mensagem está ou não vazia, enquanto a segunda, define se a mensagem é ou não uma mensagem que descreve uma falha (Fault).

Como o body da mensagem é um stream, ele pode ser lido ou escrito apenas uma única vez. Para assegurar esse comportamento, o WCF disponibiliza uma propriedade de somente-leitura chamada State. Essa propriedade retorna um dos valores definidos no enumerador MessageState: Created, Read, Written, Copied e Closed. O valor dessa propriedade vai alterando de acordo com o métodos de escrita ou leitura que você invoca a partir da instância.

Por último e não menos importante, temos a propriedade Version. O valor dessa propriedade é definida no momento da criação da mensagem e não pode ser mais alterada. Essa propriedade contém informações à respeito de qual versão do envelope SOAP e o protocolo de endereçamento (WS-Addressing) que será usado pela mensagem.

Atualmente temos duas versões de envelope SOAP: 1.1 e 1.2. Como falamos acima, a escolha do tipo de envelope traz consequências durante a criação da mensagem, ou seja, a versão 1.1 (que é a mais utilizada) é baseada na sintaxe XML, enquanto a versão 1.2 faz uso de XML Infosets.

Já o WS-Addressing é uma especificação que define um mecanismo para permitir o endereçamento e roteamento de mensagens, independentemente de qual protocolo esteja utilizando. Além de definir a estrutura de um endpoint, o WS-Addressing também adiciona vários headers no envelope SOAP, definindo para onde a mensagem está indo, como reagir a esta mensagem e como as mensagens de requisição/resposta estão vinculadas.

Para representar qual versão do SOAP e do WS-Addressing a mensagem vai utilizar, o WCF disponibiliza uma classe chamada MessageVersion. Em seu construtor, você deverá especificar a versão do SOAP e do WS-Addressing que ela irá representar. Para expor qual versão do SOAP e WS-Addressing que a instância da classe MessageVersion está armazenando, ela define duas propriedades de instância e de somente-leitura chamada Envelope (do tipo EnvelopeVersion) e Addressing (do tipo AddressingVersion).

Tanto a classe EnvelopeVersion quanto a AddressingVersion possui propriedades estáticas que retornam a instância dela mesma, pré-configurada com a versões suportadas do SOAP e WS-Addressing. Ainda possuem uma propriedade chamada None, para caso onde não se aplica o SOAP (como é o caso do AJAX/JSON) ou o WS-Addressing. Para ter uma melhor reusabilidade, a classe MessageVersion também possui várias propriedades estáticas (Default, None, Soap11, Soap11WSAddressing10, Soap11WSAddressingAugust2004, Soap12, Soap12WSAddressing10, Soap12WSAddressingAugust2004) que retornam instâncias dela mesma, pré-configurada com as combinações suportadas/mais utilizadas.

A classe OperationContext fornece uma propriedade chamada IncomingMessageVersion, que retorna uma instância da classe MessageVersion, para obter a versão da mensagem que está chegando até o serviço/cliente. Você pode utilizar essa propriedade para criar uma nova mensagem baseando-se na mesma versão da outra parte.

Criando a classe Message

Você não pode criar diretamente a instância da classe Message, pois ela não tem um construtor público. Ao invés disso, ela fornece um método estático chamado CreateMessage que, por sua vez, fornece vários overloads. Obrigatoriamente os overloads deste método recebem, entre os vários parâmetros, uma instância da classe MessageVersion, especificando qual a versão de SOAP e do WS-Addressing que aquela mensagem utilizará. Grande parte destes overloads também recebem uma string, representando a Action da mensagem, informação que o WCF confia e a utiliza para determinar para qual método ele deverá entregar a mensagem.

O overload mais simples recebe apenas a versão e a action, criando uma mensagem com o corpo vazio. Já outro overload recebe também um object, que cria a mensagem serializando aquele objeto como corpo da mensagem. Nestes casos, mensagem utilizará o DataContractSerializer com as configurações padrão para efetuar a serialização do objeto. Caso desejar mudar isso, você pode utilizar um overload específico, que recebe como parâmetro um objeto do tipo XmlObjectSerializer.

O código abaixo ilustra um exemplo simples de criação da classe Message. A finalidade do código é criar uma mensagem que armazena a instância da classe Usuario que possui apenas uma propriedade pública chamada Nome. Inicialmente criamos a instância da classe Message através do overload do método CreateMessage, que recebe a versão (SOAP e WS-Addressing), uma Action e o body. A instância da classe XmlDictionaryWriter recebe em seu construtor um objeto do tipo FileStream, para que o resultado seja armazenado em um arquivo físico. Na sequência, invocamos o método WriteMessage a partir da classe Message, passando a instância do XmlDictionaryWriter, que serializará a mensagem neste objeto.

using (Message msg = Message.CreateMessage(
    MessageVersion.Default, "Cadastrar", new Usuario() { Nome = "Israel" }))
{
    Console.WriteLine(msg.State); //Created

    using (FileStream fs = new FileStream("Message.xml", FileMode.Create))
        using (XmlDictionaryWriter xml = XmlDictionaryWriter.CreateTextWriter(fs))
            msg.WriteMessage(xml);

    Console.WriteLine(msg.State); //Written
}

O método WriteMessage é um dos métodos de escrita que a classe Message disponibiliza. Há outras versões que nos dará um maior controle em como as “partes” da mensagem são escritas. Esses métodos autoexplicativos são: WriteBody, WriteBodyContents, WriteStartBody, WriteStartEnvelope e WriteStartHeaders e todos eles recebem como parâmetro uma instância da classe XmlDictionaryWriter.

Lendo a classe Message

Um dos overloads do método CreateMessage recebe uma instância da classe XmlDictionaryReader. Esse overload é utilizado quando queremos fazer o processo inverso, ou seja, temos a mensagem serializada em algum local (como um arquivo no disco), e desejamos transformá-la novamente em uma classe Message. Além do XmlDictionaryReader, ainda precisamos informar ao método CreateMessage um número inteiro e uma instância da classe MessageVersion.

O número inteiro permite controlar o tamanho máximo do header da mensagem, já que ele é buferizado. A versão da mensagem deve sempre refletir a mesma versão usada quando ela foi serializada. O código abaixo ilustra como podemos recuperar o conteúdo que foi salvo no arquivo “Message.xml” (através do exemplo anterior), e transformá-lo novamente em uma instância da classe Message. Note que utilizamos o método CreateTextReader para criar o XmlDictionaryReader, seguindo o mesmo exemplo acima:

using (FileStream fs = new FileStream("Message.xml", FileMode.Open))
{
    using (XmlDictionaryReader xml =
        XmlDictionaryReader.CreateTextReader(fs, XmlDictionaryReaderQuotas.Max))
    {
        using (Message msg = Message.CreateMessage(xml, 1024, MessageVersion.Default))
        {
            Usuario u = msg.GetBody<Usuario>();
        }
    }
}

Uma vez criado a instância da classe Message, precisamos saber como devemos proceder para extrair o seu conteúdo, ou melhor, extrair o que está contido no body da mensagem. Basicamente temos dois métodos: GetBody<T> e GetReaderAtBodyContents. O primeiro deles, recebe um parâmetro genérico, utilizado pelo mesmo para deserializar o body da mensagem neste tipo especificado, utilizando o DataContractSerializer. Há um overload deste método que aceita uma instância da classe XmlObjectSerializer, que te permitirá customizar o mecanismo de deserialização. Já o método GetReaderAtBodyContents retorna um novo XmlDictionaryReader, posicionado no elemento body do envelope SOAP.

Independentemente de qual dos métodos utilize para ler o body da mensagem, você poderá chamar apenas uma única vez. Chamando duas vezes um dos métodos de leitura, uma exceção do tipo InvalidOperationException será disparada. Em situações onde você precisa processar o body múltiplas vezes, então você precisará criar uma cópia buferizada da mensagem. Para isso, a classe Message fornece um método chamado CreateBufferedCopy que retorna uma instância da classe MessageBuffer. A instância dessa classe representa a mensagem em memória, disponibilizando um método chamado CreateMessage, que retorna uma cópia idêntica da mensagem original. O exemplo abaixo ilustra o seu uso:

using (Message msg = Message.CreateMessage(xml, 1024, MessageVersion.Default))
{
    MessageBuffer mb = msg.CreateBufferedCopy(int.MaxValue);
    Console.WriteLine(mb.CreateMessage().GetBody<Usuario>().Nome);
    Console.WriteLine(mb.CreateMessage().GetBody<Usuario>().Nome);
}

Criando Fault Messages

O método CreateMessage ainda possui dois overloads que permitem a criação de uma instância da classe Message que representa uma mensagem de falha. Um desses overloads aceita como parâmetro uma instância da classe FaultCode e o outro overload recebe uma instância da classe MessageFault. O código abaixo ilustra a criação de uma MessageFault, e em seguida utilizamos o método CreateMessage passando esta fault criada:

MessageFault mf =
    MessageFault.CreateFault(new FaultCode("Receiver"), new FaultReason("Dados inválidos"));

using (Message msg = Message.CreateMessage(MessageVersion.Default, mf, "Cadastrar"))
{
    //…
}

Ao chamar a propriedade IsFault em cima da instância da classe Message criada acima, o valor retornado será True. Ao visualizar o resultado gerado pelo código acima, teremos:

<s:Envelope
  xmlns:s="http://www.w3.org/2003/05/soap-envelope&quot;
  xmlns:a="http://www.w3.org/2005/08/addressing"&gt;
  <s:Header>
    <a:Action s:mustUnderstand="1">Cadastrar</a:Action>
  </s:Header>
  <s:Body>
    <s:Fault>
      <s:Code>
        <s:Value>s:Receiver</s:Value>
      </s:Code>
      <s:Reason>
        <s:Text xml:lang="en-US">Dados inválidos</s:Text>
      </s:Reason>
    </s:Fault>
  </s:Body>
</s:Envelope>

Headers e Properties

A propriedade Headers é uma coleção, enquanto a propriedade Properties é um dicionário e podem ser manipuladas através de métodos como Add, Insert, Remove, etc. Para maiores detalhes sobre a finalidade de cada uma dessas propriedades, consulte este artigo.

Conclusão: Neste artigo vimos como podemos proceder para a criação, leitura e manipulação de uma mensagem, que é utilizada por serviços WCF. É importante conhecer esses detalhes, principalmente quando você desejar interceptar algum ponto durante a execução do serviço. Além disso, é provável que em algum momento você precisará customizar a criação e/ou leitura da mensagem, e para isso, você deverá manipular instâncias da classe Message, ao invés de deixar o WCF criá-las.

Um problema que sempre ocorre quando estamos tentando consumir um serviço WCF no Silverlight, é a ausência do arquivo ClientAccessPolicy.xml dentro do diretório onde está hospedado o serviço. Para que ele seja consumido por uma aplicação Silverlight, você deve criar esse arquivo na raiz do serviço, com a mesma estrutura definida neste artigo. Esse arquivo permite que o Silverlight invoque serviços a partir de um dominío diferente de onde ele reside.

Mas, por algum motivo, você está criando uma aplicação Console ou até mesmo um Windows Service, que servirá como o host para o serviço. Lá você configura a classe ServiceHost expondo o serviço através do BasicHttpBinding. Com isso você já consegue referenciá-lo no Silverlight, mas quando executar a aplicação, você receberá um erro de comunicação. Sabemos que é a ausência do arquivo acima mencionado, mas como estamos utilizando um host que não é o IIS, como devemos proceder para disponibilizar esse arquivo?

O Carlos Figueira criou uma solução interessante para isso, onde definiu uma interface que, quando implementada na classe que representa o serviço, gera a estrutura do arquivo ClientAccessPolicy.xml (ali está também suportando o padrão de arquivo necessário para que o Flash se comunique com o serviço WCF). Com o uso do atributo WebGetAttribute, ele configura a propriedade UriTemplate, redirecionando as requisições de cada um desses arquivos para o método correspondente.

Recentemente eu falei aqui sobre grande parte dos membros expostos pela classe OperationContext. Além de tudo aquilo que foi visto lá, ela ainda fornece um evento chamado OperationCompleted. Ao se vincular a este evento, você será notificado quando a operação corrente foi finalizada, e com isso, poderá executar algo customizado, como alguma notificação, log, calcular o tempo de execução da operação, etc.

Além disso, podemos utilizar este evento para a liberação de recursos que estão sendo utilizados pela classe/serviço. Quando os parâmetros de entrada ou o objeto de retorno (resultado) não implementar a Interface IDisposable, então utilizamos este evento para descartar esses recursos, assim como é exibido no código abaixo:

internal class Servico : IContrato
{
    private FileStream _fs;

    public void ExecutarTarefa()
    {
        OperationContext.Current.OperationCompleted += (o, e) =>
        {
            if (this._fs != null)
                this._fs.Dispose();
        }; 

        //faz uso de _fs.
    }
}