Criei este novo blog já que o anterior não estava me ajudando muito na criação de posts maiores.

O WordPress parece ser bem mais amigo nestas horas e com isso acho que posso conseguir mais ânimo para redigir.

Boa leitura.

Para os desenvolvedores mais exigentes, a ferramenta wsdl.exe dá um pouco mais de opções antes de criar o proxy, como o nome da classe que será gerada, seu namespace, dentre outras opções.

Existem ainda outros geradores de proxy para WebServices feitos por terceiros, mas qualquer gerador de proxy faz a geração baseado no conteúdo do Web Service Description Language (wsdl), que nada mais é que um XML schema descrevendo o WebService, seus métodos, os tipos necessários para o envio de um envelope ao invocar um método e os tipos que o envelope de resposta irá conter.

Em geral, tudo isso é muito simples e fácil (ou deveria ser).

Vou contar um pouco de história para que entendam como esse tipo de estratégia pode ser útil, em que tipo de cenário ela pode ser uma opção a ser avaliada. Caso você apenas queira saber como implementar, você pode pular este bloco.

Na empresa onde trabalho, por exemplo, apareceu uma necessidade de fazermos o consumo de um WebService, cujo WSDL estava simplesmente impossível de se usar para a criação do Proxy através de ferramenta. WSDL’s podem referenciar outros XSD’s de apoio (para tipos de objetos que são compartilhados para uso em outros WebServices), e no caso deste em particular haviam mais de 150 XSD’s descrevendo tipos para os mais diversos métodos contidos no WebService, e no meio desta multidão de tipos, alguns referenciavam a outros e estes aos primeiros novamente, sendo difícil detectar todas as referências circulares que estavam espalhadas pelos XSD’s, o que deixava os geradores de proxy perdidos.

Tentamos usar os geradores de proxies convencionais (WebReference – wsdl e wsewsdl* – que é o gerador de proxies para uma API chamada WSE – Web Services Enhancements) mas nenhum deles obteve sucesso, ora apresentando problemas para referências a tipos contidos em XSD’s não declarados (exigindo a inclusão destes na linha de comando do gerador) e a cada XSD que se incluía, um novo era exigido até que nenhum outro era pedido mas o gerador dava um erro de StackOverflow. Usando o wsdl.exe, o resultado foi este. Já usando o wsewsdlx.exe, a inclusão dos XSD’s satélites não foi necessária. Contudo o StackOverflow também ocorria.

O problema do StackOverflow era devido a algumas implicações que os XSD’s apresentavam por não seguirem o que chamamos de Basic Profile, que é um acordo comum entre algumas empresas do mercado que definiram uma espeficação de Interoperabilidade entre plataformas usando WebServices (WS-I – WebServices Interoperability). As ferramentas de geração de proxy se baseiam na especificação do Basic Profile, por que consideram que os WebServices (que são usados justamente para estabelecer uma comunicação entre aplicações de qualquer plataforma) obedeçam as normas estabelecidas.

Agora imaginem ter que inspecionar cada um dos 150 XSD’s procurando por todos os pontos onde a especificação do Basic Profile não foi obedecida.

O problema é que tudo que precisávamos era de apenas um único método simples do WebService, que recebia 4 strings e devolvia um objeto simples com 6 valores entre strings e inteiros. Decidimos fazer nosso próprio proxy sem a ajuda de um gerador. Agora, consumir um webservice na mão pode parecer uma atitude meio ignorante, mas o seu Proxy fica limpo, deixando apenas aquilo que você irá usar.

Esta técnica é novidade para mim, mas o pessoal da empresa já estava acostumado a lidar com essa situação, visto que tiveram os mesmos problemas em outros WebServices do mesmo cliente. A técnica adotada por eles anteriormente é diferente da que vou apresentar aqui, já que eles usam o SoapToolKit, que usarei em um outro exemplo mais tarde.

Agora chega de papo-furado e vamos colocar a mão na massa.

Primeiro Exemplo de Criação de Proxy – Derivando a classe WebClientProtocol

Neste primeiro exemplo faremos exatamente o que o wsdl faz. Significa que seu Proxy ficará muito parecido com o que seria se fôsse gerado com o wsdl.

Vamos ao WebService primeiro. Eu criei um projeto MiscServices usando o template Asp.Net Web Service Application.

O VisualStudio já vai criar para você uma classe que herda de System.Web.Services.WebService, que é o que caracteriza um WebService em uma solução .Net.

Note que já existe um método no nosso WebService chamado HelloWorld. Manteremos este afim de fazer um teste simples e criaremos outros para aumentar gradualmente a complexidade dos testes.

Note que o webservice é criado com um namespace inicial Default. É extremamente recomendável que você mude aquele namespace para um que caracterize o webservice como parte do seu domínio.

Eu mudei o nome da classe e o namespace para WebServiceTeste, mas ao fazer isso você precisa corrigir o arquivo asmx, alterando o nome da classe antigo para o novo nome.

Também criei uma classe simples para fazer um teste com objetos no WebService:

E finalmente, os demais métodos do nosso webservice de teste:

Nosso WebService está pronto. Você já pode compilá-lo. Vamos agora criar um novo projeto para ser o client. No caso vou criar um Console Application.

O primeiro passo é obter o WSDL. Sem o qual não faria o menor sentido criar um proxy. O WSDL é peça fundamental para quem pretende consumir um WebService e, conseqüentemente, sua publicação é fundamental para que o fornecedor permita que seu cliente o acesse.

Ao abrir o WSDL você precisa reparar em alguns elementos imprenscindíveis: O namespace, Os elementos de operação (operation name=…) que são os métodos e os Tipos (complexType name…) dos objetos que os métodos esperam receber e pretendem incluir na resposta.

O segundo passo é criar uma classe que derive direta ou indiretamente de WebClientProtocol, no nosso caso usaremos a SoapHttpClientProtocol por que ela usa envelopes Soap para fazer a troca de mensagens, e o Soap é um protocolo feito sob medida para WebServices, embora seja possível usar outros protocolos, como o HTTP. Estas classes podem ser encontradas se você fizer uma referência ao assembly System.Web.Services. Elas se encontram no namespace System.Web.Services.Protocols.

Esta classe será o proxy do WebService que você tem, então obviamente você precisa declarar nela um método que representará a invocação do método que você precisa consumir do webService. Neste exemplo, os métodos HelloWorld, Soma, GetBook e PostBook são os métodos que queremos consumir, portanto criaremos no proxy os métodos equivalentes para consumí-los. Os métodos no nosso proxy não precisam ter o mesmo nome definido no wsdl, embora precisem anotar um binding ao mesmo schema, como irei mostrar depois. No entanto eu criarei os métodos de acordo com seus nomes no wsdl.

Digamos que você não tenha o conhecimento da classe implementada do webservice (que é o que naturalmente iria acontecer num cenário real), então você precisa pegar a definição do método no WSDL. Basta procurar pelas definições de operação “operation name=”.

Note que cada elemento de operação possui uma definição de parametros de entrada e de saída (wsdl:input message e wsdl:output message). Se você pegar o método HelloWorld, por exemplo, em wsdl:input a descrição da mensagem assina o schema “tns:HelloWorldSoapIn”. “tns” é o prefixo usado para o namespace do próprio WebService, o que significa que este schema está declarado neste mesmo documento. Basta procurar por ele e você verá que ele remete a um outro schema: tns:HelloWorld. O wsdl:output assina o schama HelloWorldSoapOut que remete ao tns:HelloWorldResponse. Se procurar pelo schema tns:HelloWorld vê que ele é um complexType vazio, por que o método não recebe parametros. Já o tns:HelloWorldResponse contem um complexType com uma string chamada HelloWorldResult que pode ocorrer no mínimo nenhuma vez e no máximo uma vez, significando que ela pode ser nula. O que nos indica a assinatura do nosso método HelloWorld no proxy: Método sem parâmetros que retorna uma string.

Mas no caso dos nossos métodos PostBook e GetBook que usam um objeto como parâmetro de entrada e como resposta respectivamente? De acordo com o schema na figura acima eles apontam para GetBookSoapOut na saída do GetBook (que devolve um objeto Book) e PostBookSoapIn na entrada do PostBook (que recebe um objeto Book). Estes apontam para GetBookResponse e PostBook respectivamente. E procurando por estes outros dois você enxerga o problema:

Notem que o GetBookResponse possui um objeto chamado GetBookResult do tipo tns:Book que está declarado logo abaixo. O type Book possui duas propriedades: Title e Author e ambas são string. Daí você já sabe: precisa implementar uma classe parecida para conter estes valores. Agora você já tem condições de, pelo menos, declarar os métodos corretamente.

Sua classe ainda não compila, pois ainda é necessário fazer a implementação dos métodos. A classe SoapHttpClientProtocol possui um facilitador: um método protected chamado Invoke que executa um método no WebService. Ele recebe como parâmetros uma string contendo o nome do método a ser invocado e um array de objects contendo tudo o que ele espera por parâmetros, e devolve um array de objects contendo todos os objetos da resposta. Segue a implementação:

Estamos chegando perto de concluir nosso Proxy. Mas se você rodar ele agora ele ainda não vai funcionar. Primeiro por que você vai precisar setar a propriedade Url que está na classe base. Faça isso como quiser mas o mais indicado é criar um construtor que recupere este parâmetro de um arquivo de configuração. Como estamos apenas fazendo um exemplo, eu vou definir a Url no próprio código:

O nosso compilador vai quebrar um galhão pra gente na hora de compilar o projeto, mas ele precisa de algumas orientações para fazer isso. A primeira delas vai na classe do proxy, que precisa de uma anotação com um atributo de Binding. O atributo em questão é o System.Web.Services.WebServiceBindingAttribute e os parâmetros necessários são Name, que pode ter qualquer valor que você quiser usar para identificá-lo, e Namespace, que precisa ser o mesmo namespace do wsdl.

Por fim, os métodos também precisam ser decorados com um atributo, o
System.Web.Services.Protocols.SoapDocumentMethodAttribute recebe como principal argumento a definição do método no namespace, para tanto você precisa colocar o namespace completo acompanhado de uma barra “/” e o nome do método.

Os outros parametros para este atributo são RequestNamespace e ResponseNamespace, que recebem o mesmo valor de namespace do wsdl. Tudo isso precisa bater com os nomes dos schemas dentro do wsdl para que o proxy funcione.

Tá na hora de testar seu proxy:

A implementação do seu próprio Proxy faz com que você possa fazer o código dele integrado à sua solução e não isolado como normalmente acontece com os proxies construídos pelas ferramentas que os geram. Além de ficar mais limpo e flexível, contendo apenas o que você vai usar.

Se quiser saber mais sobre a estrutura e o conteúdo dos WSDL’s, segue uma documentaçãoi detalhada a respeito deles: http://www.w3.org/TR/wsdl

Em breve, postarei as formas de reproduzir o mesmo feito no Web Service Enhancements, que atende especificações de extensão para os web services e também para o SoapToolKit. Até lá você pode se divertir praticando esta técnica com webservices mais complexos que recebem e devolvem objetos contendo outros objetos, ou lendo melhor a respeito dos outros derivados de WebClientProtocol, e de outros usos dos atributos WebServiceBindingAttribute e SoapDocumentMethodAttribute.

Até lá.

E resolvi dar uma traduzida por cima para compartilhar com todos, uma vez que todas as lições, até mesmo as que já são do conhecimento de todos, sempre são boas para ser relembradas.

Lição 1: Todo Software é falho

Lição 2: Faça o check-in com frequência

Lição 3: Testes, você tem que amá-los.

Lição 4: Refatore, faça o check-in e repita

Lição 5: Codificar é fácil, humanos é que são teimosos

Lição 6: Quanto mais olhos em seu código, melhor

Lição 7: Continue aprendendo e melhorando

Lição 8: Simples é belo

Lição 9: Aprenda desenvolvimento de software sem codificar

Lição 10: Pense no seu público

Lição 1: Todo Software é falho
Qualquer um que tenha escrito um software maior que “hello world” sabe que haverão bugs. Isto é um fato no desenvolvimento de software. Estas falhas ocorrem porque a forma em que um pedaço de software é escrito é um reflexo de como o desenvolvedor pensa e quais desafios ele ou ela está tentando resolver. O fato dos pensamentos humanos não serem logicamente perfeitos o tempo todo, erros irão ocorrer. Além disso, o desenvolvimento de software é sempre um conflito entre tempo/dinheiro e aspectos que levam a items deixados parcialmente codificados ou feitos às pressas. O que nos leva à próxima lição…

Lição 2: Faça o check-in com frequência
Todo mundo usa Source Control, certo? Se você não usa, comece agora. Quando estiver desenvolvendo software ou fazendo refactoring massivo, source control é seu amigo. Quanto mais frequênte você fizer check-ins em porções utilizáveis de código, mais fácil será para recuar se você tiver bagunçado completamente algo. Em equipes que requerem revisão de código antes do check-in ou eles congelam check-ins, crie um servidor de source control local. É muito fácil e rápido. Eu sempre penso no source control como um botão “desfazer” e ele libera parcialmente o desenvolvedor do medo de fazer uma bagunça publicamente. Se você usa source control e faz testes unitários, quase todo o medo vai embora.

Lição 3: Testes, você tem que amá-los.
Ahh Testes unitários… Todo mundo diz que você tem que usá-los e eles são a melhor coisa desde que criaram o pão pré-fatiado. Eu acabei concordando com a maior parte. Quando desenvolvo livremente (NT: O autor usou greenfield developement para se referir a desenvolmento à vontade, ou seja, da forma como ele bem entender, sem restrições) eu me certifico de que os testes unitários são sempre escritos e usados. Contudo, a idéia de testes unitários como parte do ciclo normal de desenvolvimento tem se tornado apenas semi-comum nos últimos 5 anos e bons softwares foram construídos antes deles. Manter uma lista de testes comuns que deveriam ser rodados fora de uma IDE também é algo muito bom de se ter. Eu acho que a maior vantagem dos testes unitários é que contanto que eles sejam rápidos ao rodar, eles permitem uma rápida verificação da sanidade do desenvolvedor. Se o source control é o botão “desfazer”, então testes unitários são a babá que te dá uma bronca por ter feito algo que você não faria se seus pais estivessem por perto.

Lição 4: Refatore, faça o check-in e repita
Nenhuma porção de código é perfeita mas ela pode melhorar (e, claro, pode piorar) se você voltar ao código e fizer a si mesmo as perguntas “o que posso fazer para que isso fique mais curto, fácil de entender, etc…?” As pessoas fazem isso o tempo todo quando escrevem textos mas não acontece o mesmo quando escrevem código. Depois de cada intervalo, faça o check-in no código no caso de você ir muito longe e ter removido algum porção necessária de código. Dependendo do tamanho do código sendo refatorado poderão haver muitas iterações.

Lição 5: Codificar é fácil, humanos é que são teimosos
Não me leve a mal, existem alguns problemas difíceis na codificação mas eles não são tão difíceis quanto descobrir o que nosso companheiro quis fazer quando escreveu uma porção de código. Humanos tem uma tendência para serem inconstantes e contradizerem o que eles dizem. No topo disto é muito difícil se comunicar claramente e existe uma barreira entre discurso de nerd (NT: aqui o autor usou o termo geek-speak para se referir ao vocabulário normalmente usado num diálogo de programadores) e o vocabulário normal. Isto torna xtremamente difícil descobrir o que os usuários estão pedindo.

Lição 6: Quanto mais olhos em seu código, melhor
Toda vez que inicio uma nova base de código, ou volto para uma que não tenho usado por algumas semanas eu sempre gasto alguns minutos navegando em busca de coisas a melhorar. Quando eu encontro algo que foi uma má implementação ou apenas um bug eu mando um email para o desenvolvedor dizendo como aquilo poderia ser melhorado (eu também mudo a implementação para fazê-la melhor). Eu peço e espero que a mesma coisa de qualquer desenvolvedor que trabalhe comigo. Porque? Porque isso nos faz honestos e nos ensina maneiras de fazer nossos programas melhores. Claro, isto pode não ser como “sentarmos juntos e revisarmos o código”, mas eu acho que isto funciona bem no mínimo para pequenas equipes. Code-reviews formais são bons e possuem um objetivo similar: Maior qualidade no código e os bugs são encontrados antes que o QA os encontre. Eu acho que tudo depende do ambiente em que você está.

Lição 7: Continue aprendendo e melhorando
A lição parece óbvia mas precisa ser dita. Se você não aprender e/ou continuar melhorando você corre o risco de se tornar um obsoleto (NT: aqui o autor usou a palavra “fez” que se refere a um chapéu pouco usado atualmente no Marrocos e na Turquia, mas que já foi amplamente usado pela população destes países durante muito tempo), o que eu duvido que alguém queira. Minhas métricas normalmente são:

* Que novas linguagens / tecnologias / técnicas eu aprendi no último mês?

* Quando eu olho para o meu código antigo, eu consigo encontrar melhores maneiras para fazer as coisas?

Eu acho que a segunda métrica é muito importante. Se você não consegue pensar em maneiras de melhorar o código – ainda que não seja praticável na base de código atual – então você deveria se preocupar como se isso fôsse um sinal de que você não está crescendo.

Lição 8: Simples é belo
O acrônimo KISS (Keep It Simple, Stupid) é muito bom e eu tento seguí-lo quando estou desenvolvendo software desde que eu também acredite na idéia de que conforme o software cresce ele se torna mais complexo. Toda vez que eu tiver que corrigir uma questão ou escrever código eu sempre me pergunto “isso não pode ser mais simples?” Simplicidade tem muitos benefícios e não só de uma perspectiva de desenvolvimento. Alguns são:

* Código fica mais fácil de entender
* Manutenção tende a ser mais fácil
* UI (interface com o usuário – telas) simples tende a fazer os programas mais fácil de usar

Lição 9: Aprenda desenvolvimento de software sem codificar
Particularmente eu faço uma distinção entre codificar e realmente desenvolver software. Eu acho que existem muitíssimas pessoas que focam somente na porção de codificação e não para o panorama mais amplo da figura. Muitas pessoas podem escrever código mas parece que poucas conseguem desenhar um sistema, testar um sistema, escrever o código, documentar a arquitetura, falar com os usuários para descobrir os requisitos, criar estimativas semi-precisas, ajudar outros membros da equipe e, quando desenhar a interface com o usuário, saber o básico da iteração com o mesmo. Existem coisas que todos os desenvolvedores deveriam saber sobre codificação também, mas eu sinto que melhorar e refinar seu código é bem fácil e é feito conforme você desenvolve software. Aprender e melhorar em relação ao desenvolvimento de software não é necessariamente o suficiente para manter alguém em uma vaga de programador.

Lição 10: Pense no seu público
Quando chegar neste ponto você vai pensar imediatamente nos usuários do programa para os quais ele está sendo criado, não é? Se você pensou você esqueceu uma porção de outros públicos . Toda vez que você codifica eu acho que existem pelo menos 4 públicos: O compilador, os outros programadores / você mesmo no futuro, hackers e usuários maliciosos e então os usuários do programa. Todos estes públicos requerem diferentes coisas e o público mais fácil de satisfazer é o compilador. Os outros públicos dão um pouco mais e trabalho quando se cria software. Por exemplo, o público de hackers nós queremos mesmo é chatear invés de agradar e chatear um hacker é bem fácil simplesmente não confiando na entrada de dados e devidamente encriptando a saída (nota: isto não vai te proteger de tudo no arsenal de um hacker mas vai tomar cuidado com uma porção enorme deles). O públic de desenvolvedores é bem teimoso conforme nós temos uma tendência de achar que todo código de outro programador é estúpido ou pelo menos ter uma opinião sobre ele, isso se baseia na diferença em como cada pessoa pensa (pelo menos esta é minha opinião). Commentando regras de negócio, escrevendo código limpo e claro e mantendo-o simples normalmente ajuda o público desenvolvedor. Para os verdadeiros usuários do programa, eles são um grupo interessante. Existem muitos livros sobre usabilidade e design então eu estou apenas sugerindo que você pegue alguns livros bons nesse quesito (se você precisar de alguma sugestão, sinta-se livre para me contactar [NT: Quem faz o convite é o autor, eu, o tradutor, não conheço nenhum livro bom a este respeito, embora tenha muito interesse em obter).