Abril de 2009

T UTORIAIS PARA O
DESENVOLVIMENTO DE
W EB SERVICES SOAP
E REST FUL
Na plataforma .NET

Este documento apresenta conceitos básicos sobre a arquitetura SOAP

e REST e desenvolve, passo-a-passo, serviços web em cada uma das
arquiteturas, explorando suas vantagens e explicitando algumas
desvantagens entre as estruturas.

Mauricio Cirelli
Abril de 2009

Grupo de Estudos em interação do LTS

Escola Politécnica da Universidade de São Paulo
 Abril de 2009

TUTORIAIS PARA DESENVOLVER W EBSERVICES SOAP E

RESTFUL

SOAP

Criando, Publicando e Consumindo ASP.NET WebServices utilizando

C#

Vamos utilizar o Visual Studio 2008 Professional como ferramenta para construção de
nosso WebService.

Primeiramente, devemos abrir o Visual Studio 2008 e criar um novo projeto usando C#.
Selecione ASP.NET WebService Application, como na figura abaixo:

De o nome de TutorialWebService e clique em OK.

Você será redirecionado para uma tela onde poderá observar o código padrão de seu
WebService. Ao lado direito, no Solution Explorer, você encontrará todos os arquivos da
sua Solução.

Seu serviço chama-se Service1, vamos mantê-lo para facilitar. Caso deseje alterar, você terá
que modificar o nome da Classe criada automaticamente e terá que alterar todas as
referências deste Serviço nos arquivos de projeto, como o web.config.

Além disto, o Visual Studio criou um WebMethod para a função HelloWorld();. Vamos
adicionar um novo WebMethod ao nosso programa:

[WebMethod]
public double Soma(double a, double b)
{
return a + b;
}

Um WebMethod é uma função do WebService que será chamada pelos clients. Veremos
mais adiante como fazemos para que um programa client utilize esta função e trate os
valores recebidos. No caso, a função Soma() recebe dois valores do tipo double e retorna a
soma deles.
 Abril de 2009

Pronto, nosso WebService está completo. Vamos criar agora um programa (Windows
Application) que se relaciona com este WebService.

Antes disto, devemos publicar nosso WebService, pois ele não teria utilidade alguma se
ficasse preso ao localhost em determinada porta aleatória criada pelo Visual Studio.

Para isso, compile seu projeto e salve todos os arquivos. Vamos atualizar nosso IIS
(Internet Information Services) adicionando o conteúdo da pasta Meus Documentos/Visual
Studio 2008/Projects/TutorialWebService/ , ou a pasta escolhida para você para o projeto,
em um WebSite na pasta C:/Inetpub/wwwroot/TutorialWebServices/. Será necessário criar
esta pasta.

Abra o IIS em Iniciar > Painel de Controle > Ferramentas Administrativas > Internet
Information Services. Expanda a guia Sites da Web > WebSite Padrão. Crie um novo
Diretório Virtual, chamado TutorialWebServices, como nas figuras abaixo:

Especifique o local de origem (criado acima) e ative todas as opções (Execução, Procura,
Gravação e Leitura) e finalize.

Para testar, abra seu browser e digite o endereço: //localhost/TutorialWebServices/. Você

deverá ser encaminhado para uma tela como esta (esquerda) e, ao clicar em Service1.asmx,
será redirecionado para a tela da figura da direita.
 Abril de 2009

Nesta tela, você poderá testar suas funções (WebMethods) criados. Basta clicar em um dos
links (Soma ou HelloWorld).

Agora que já criamos nosso Webservice e o publicamos, devemos criar uma aplicação que
o utilize de alguma maneira.

Volte ao Visual Studio 2008. Na guia Solution Explorer, clique com botão direito e
adicione um novo Projeto (Add > New Project). Escolha a opção Windows Application e dê
o nome de UsarWebServices.

Um formulário
foi criado e novos arquivos adicionados junto ao novo projeto. Adicione um botão
(CalcularButton) e 2 TextBox (Num1TextBox e Num2TextBox). Adicione outro botão
(HelloWorldButton), pois vamos aproveitar para testar o WebMethod padrão criado
anteriormente.

Com nosso formulário pronto, devemos criar a referência ao nosso WebService. Desta
maneira, poderemos utilizar seus objetos e WebMethods como se fossem funções internas
ao nosso programa.

Para isto, clique com botão direito do mouse no projeto UsarWebService, na Solution
Explorer. Procure Add > Service Reference. Procure o botão Advanced e, na guia que se
abrir, clique no botão Add Web Reference. Você será redirecionado para uma tela como
esta:
 Abril de 2009

Escolha Web Services in this Solution. Nesta tela deverão aparecer os WebServices do
nosso projeto, no caso, Service1. Ao selecioná-lo, veremos seus 2 methods, como
anteriormente quando testamos nosso WebService após publicá-lo.

Nota: Você pode criar aplicações e adicionar referências de quaisquer WebServices que
você tenha acesso. Basta, para isto, saber a URL em que este WebService está hospedado.
O site http://www.webservicex.net/WS/wscatlist.aspx, por exemplo, contém um grande
acervo de WebServices que você pode referenciar em uma aplicação e utilizar seus
WebMethods. No nosso exemplo, seria possível buscar e adicionar nossa referência pelo
endereço: //localhost/TutorialWebServices/.

Dê o nome de localhost para nossa referência ao WebService e adicione.

Agora vamos dar utilidade aos nossos WebMethods criados. Vamos adicionar um evento
ao clique do botão Calcular:

private void CalcularButton_Click(object sender, EventArgs e)

{
double num1, num2, res;
double.TryParse(Num1TextBox.Text, out num1);
double.TryParse(Num2TextBox.Text, out num2);

//Instanciando um objeto da classe do nosso WebService,

//adicionada ao projeto por meio de Web reference
localhost.Service1 MeuWebService = new localhost.Service1();

//Chamando o metodo Soma(double a, double b) de nosso

//objeto
res = MeuWebService.Soma(num1, num2);
//Exibe o resultado em uma Message Box.
MessageBox.Show("A soma é: " + res);
return;
}

Agora para o botão HelloWorld:

private void HelloWorldButton_Click(object sender, EventArgs e)

{
//Instanciando um objeto da classe do nosso WebService,
//adicionada ao projeto por meio de Web reference
localhost.Service1 MeuWebService = new localhost.Service1();

//Chamando e exibindo o resultado do metodo HelloWorld() de

 Abril de 2009

//nosso objeto
MessageBox.Show(MeuWebService.HelloWorld().ToString());
return;
}

Antes de compilar nossa solução, defina o projeto

UsarWebServices como StartUp Project, na Solution Explorer.

Compile e execute a solução para testar. Seu projeto deverá

retornar algo assim ao clicar em ambos os botões:

Concluído. Nas próximas páginas, iremos nos aprofundar nos WebMethods, criando
funções que recebem e retornam Arrays, Objetos, fazem consultas a bancos de dados, entre
outras funcionalidades. Será importante que você tenha adicionado nossa Web Reference
buscando por WebServices dentro do projeto. Caso contrário, você terá que sempre
atualizar a pasta compartilhada do IIS, atualizando o WebService publicado, com as novas
funções que adicionaremos.

Vale ressaltar que é possível adicionar quantas referências quisermos de quantos

WebServices diferentes forem necessários. No entanto, devemos lembrar sempre de
instanciar os objetos de cada serviço de cada um deles.

Criaremos agora um exemplo um pouco mais prático. Imagine que você tenha um
formulário de inscrição para vagas de emprego no site de sua empresa. Este formulário
deverá receber muitas informações, como as empresas que o candidato já trabalhou.
Queremos armazenar estes dados em uma String Array e, posteriormente, cadastrá-la em
um banco de dados.

Começaremos adicionando uma base de dados ao projeto TutorialWebServices. Faça isso

pela Solution Explorer, adicionando um novo item ao App_data. Escolha SQL Server
Database e dê o nome de candidatos.mdf.

Agora editaremos nossa base de dados adicionando uma nova tabela e alguns campos.
Restringiremos, para efeito de tutorial, que o candidato poderá ter atuado em até quatro
empresas.
 Abril de 2009

Após adicionar os campos, clique com botão direito na guia criada para a tabela e salve a
tabela com o nome de empresas. Você terá algo assim ao final:

Vamos editar o código do nosso Service1.asmx. Deveremos adicionar duas referências no

início do código:

using System.Data;
using System.Data.SqlClient;

Criaremos nosso WebMethod:

[WebMethod]
public Busca BuscaEscolaPorID(string id)
{
string strSQL;
 Abril de 2009

//String SQL
strSQL = "SELECT * FROM tblEscola WHERE IDEscola= '" + id + "'";

//Conecta ao banco de dados

string connString = "Initial Catalog=DATABASENAME;data
source=HOST\\SQLEXPRESS;uid=user;password=senha;";
SqlConnection conn = new SqlConnection(connString);
Busca res = new Busca();
//Tenta realizar a operacao
try
{
conn.Open();
SqlDataAdapter dataAdapter = new SqlDataAdapter(strSQL,
conn);
DataSet dataSet = new DataSet();
dataAdapter.Fill(dataSet);

foreach (DataRow dataRow in dataSet.Tables[0].Rows)

{
res.IDEscola = dataRow["IDEscola"].ToString();
res.nomeEscola = dataRow["nomeEscola"].ToString();
res.enderecoEscola =
dataRow["enderecoEscola"].ToString();
res.cidadeEscola = dataRow["cidadeEscola"].ToString();
res.CEPEscola = dataRow["CEPEscola"].ToString();
res.bairroEscola = dataRow["bairroEscola"].ToString();
res.tipo = dataRow["tipo"].ToString(); ;
}
res.ex = "";
return res;
}
//Em caso de erro retorna o erro
catch (Exception ex)
{
Busca except = new Busca();
except.ex = ex.ToString();
return except;

}
}
}

Este método realiza uma busca pelos dados de uma dada tabela tblEscola e armazena o
conteúdo de cada campo em um objeto do tipo Busca, cujos atributos correspondem aos
campos da tabela, associados pelo método dataRow. Repare que o método retorna como
resultado TODO o objeto res, do tipo Busca, instanciado.

Para que ele funcione, devemos adicionar esta classe Busca ao código. Vá pelo Solution
Explorer em Add New Item e selecione Class. Dê o nome de Busca e adicione o código:

public class Busca

{
public string IDEscola,
nomeEscola,
enderecoEscola,
CEPEscola,
cidadeEscola,
bairroEscola,
tipo,
ex;
}

Agora vamos chamar este método e tratar sua resposta através de nosso form client.
Adicione um campo IDEscolaTextBox e um botão BuscarButton.

private void BuscarButton_Click(object sender, EventArgs e)

{
BuscaWebService.Service1 MeuWebService = new
BuscaWebService.Service1();
BuscaWebService.Busca resultados = new BuscaWebService.Busca();

Proj.RT.NNN.vv 8
 Abril de 2009

resultados =
MeuWebService.BuscaEscolaPorID(IDEscolaTextBox.Text.ToString());
if (resultados.ex != "")
MessageBox.Show("ID: " + resultados.IDEscola + "\nNome: " +
resultados.nomeEscola + "\nCidade: " + resultados.cidadeEscola +
"\nEndereço: " + resultados.enderecoEscola + "\nBairro: " +
resultados.bairroEscola + "\nCEP: " + resultados.CEPEscola, "Resultados da
Busca");
else
MessageBox.Show(resultados.ex.ToString(), "Erro!");
}

Ao criarmos a WebReference, temos acesso a todos os objetos públicos do WebService. Em

particular, temos o Service1, que é nosso serviço e contém nossos WebMethods. Entretanto,
temos acesso a outras classes públicas, como é o caso da classe Busca.

Neste procedimento, instanciamos um objeto da classe Busca e um outro da classe

Service1. MeuWebService continuará sendo nosso objeto de conexão entre o client e os
WebMethods. Neste exemplo, resultados foi instanciado como objeto da classe Busca, que
possui os atributos que serão recolhidos da SELECT executada no banco de dados, pelo
método BuscaEscolaPorID.

Este WebMethod realiza a busca e retorna para o client um objeto do tipo Busca. Este
objeto é público e foi lido pelo client, que armazenou e tratou seus atributos exibindo-os em
uma MessageBox.

Agora que já sabemos criar e utilizar WebServices, trataremos um pouco sobre os conceitos
envolvidos na tecnologia.

“Web service é uma solução utilizada na integração de sistemas e na comunicação entre

aplicações diferentes. Com esta tecnologia é possível que novas aplicações possam
interagir com aquelas que já existem e que sistemas desenvolvidos em plataformas
diferentes sejam compatíveis. Os Web services são componentes que permitem às
aplicações enviar e receber dados em formato XML. Cada aplicação pode ter a sua
própria "linguagem", que é traduzida para uma linguagem universal, o formato XML.” –
da Wikipedia.

Vale ressaltar que esta não é a única maneira de gerar interoperabilidade entre plataformas.
RMI, RPC, Corba, entre outras tecnologias também existem para isto, onde cada uma tem
suas limitações e vantagens.

A principal função dos WebServices é garantir interoperabilidade entre aplicações. Estas

aplicações podem ser desenvolvidas em diferentes plataformas, como .NET e Java, o que
torna esta tecnologia extremamente útil. Em nossos exemplos estudamos como criar e
utilizar (consumir) serviços web dentro da plataforma de desenvolvimento da Microsoft, o
.NET, porém, a maneira com a qual criaríamos uma aplicação .NET para consumir um
serviço desenvolvido em Java é exatamente a mesma. Assim como é possível consumir
serviços feitos em .NET a partir de clients Java. Mas como tudo isso é possível?

WebServices utilizam um novo padrão de transferência de dados, o SOAP (Simple Object

Access Protocol), o qual se baseia no princípio de distribuição e descentralização de
plataforma. Para isto, ele empacota as informações a serem transferidas em um arquivo
XML, que é uma linguagem universal, sendo portável em todas as plataformas de
desenvolvimento atuais. Há também a possibilidade de se utilizar o padrão Restful, porém
não o abordaremos neste tutorial.

Proj.RT.NNN.vv 9
 Abril de 2009

O SOAP padronizou a estrutura destes arquivos XML, de forma que fosse possível a cada
framework criar suas bibliotecas de interpretação e uso destes dados. Abaixo segue uma
figura que ilustra como esta arquitetura funciona.

Mas quais desvantagens os WebServices possuem?

Uma delas, com certeza, é o próprio arquivo XML. Por utilizar muitos caracteres especiais
e, usualmente, conter muitas informações, trata-se de um arquivo de tamanho considerável
para ficar sendo transmitido pela rede. Se imaginarmos uma grande aplicação ou um
serviço web de grande popularidade, por exemplo, isto se torna um grande problema, pois
as requisições estarão mais sujeitas a falhas e à lentidão.

Basicamente, o client (que pode ser qualquer dispositivo, desenvolvido em qualquer

plataforma que suporte XML) envia uma requisição ao Servidor, via HTTP utilizando o
padrão do protocolo SOAP em forma de um arquivo XML que contém o método e os
parâmetros necessários para a execução do método no Servidor (WebServices), além de
outros dados.

O Servidor recebe esta chamada, interpreta o WebMethod requisitado e retorna o resultado

através de outro arquivo XML contendo o tipo de dado e o dado, além de outras
informações.

Como este XML deve ser escrito está definido em outro arquivo XML, o WSDL (Web
Services Definition Language) que descreve o WebService em questão, fornecendo seus
métodos, quais tipos de parâmetros de entrada e saída ele trata, especifica como acessá-lo e
 Abril de 2009

os objetos e métodos disponíveis. Toda esta comunicação pode ser criptografada, por meio
de Certificados de Segurança, para tentar garantir que a informação não seja rastreada por
hackers, por exemplo.

Este arquivo foi criado pela Ariba, IBM e Microsoft e, posteriormente, doado à W3C para
que ficasse livre para utilização pública. Estas especificações podem ser encontradas em:
http://www.w3.org/TR/wsdl.

Exemplos de código-fontes podem ser encontrados nos Anexo B – WebService Modelo e

Anexo B – TutorialWebService.

REST
Criando RESTful WebServices com C# 2008
Requisitos:

1. Visual Studio 2008 (VS2008);

2. .NET Framework 3.5;
3. IIS (Internet Information Services 6.0 ou mais atual);
4. Conhecimentos sobre formulários HTML;

REST: Representational State Transfer

Primeiramente, abra o VS2008 e crie um novo projeto de Web Site (ASP.NET Web
Application). Chame o projeto de RESTWebService. Se preferir, remova o arquivo
Default.aspx, pois ele não é necessário (ele seria necessário ao consumir o WebService, se
isto fosse feito por esta solução mesmo, trataremos disto mais adiante).

Adicione um novo item ao projeto, do tipo General Handler. Nomeie-o de RESTWS.ashx:

Proj.RT.NNN.vv 11
 Abril de 2009

Nosso WebService fará algo bem básico: Somará 10 a um dado número, no entanto,
devemos salientar que a função (WebMethod) poderá executar qualquer tarefa que uma
aplicação comum pode executar, como consulta a bancos de dados, por exemplo.

Adicione o seguinte trecho de código ao nosso RESTWS.ashx:

namespace RESTWebService
{
/// <summary>
/// Summary description for $codebehindclassname$
/// </summary>
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class RESTWS : IHttpHandler
{

public void ProcessRequest(HttpContext context)

{

int count;
//Executa o serviço apenas se algo foi dado como
entrada;
try
{
count =
Int32.Parse(context.Request.QueryString["num"].ToString());
context.Response.ContentType = "text/plain";
context.Response.Write("Este webservice soma 10 ao
número digitado: \n");
context.Response.Write((count + 10).ToString());
 Abril de 2009

}
catch (Exception ex)
//Retorno caso nada tenha sido digitado.
{
context.Response.Write("Uma excessão não tratada foi
encontrada: \n\n");
context.Response.Write("Parâmetro de entrada nulo ou
não é número. \n\n");
context.Response.Write(ex.ToString());
}

public bool IsReusable

{
get
{
return false;
}
}
}
}

Note que o método Request.QueryString[] é análogo ao QueryString que utilizamos em

páginas ASP ou ASP.NET, quando executamos uma chamada pelo método GET,
armazenando em uma variável o valor de um dado campo de formulário. Para este exemplo
foi usada o método GET (QueryString). Caso quiséssemos usar o método POST,
deveríamos utilizar o método Request.Form[].

Estando habituado ao ambiente Web, podemos querer que nosso WebMethod trate do valor
de alguma Session que esteja aberta. Isto também é possível.

Response.Write é um método, da mesma forma, análogo do ASP e do ASP.NET, não há

novidade nenhuma quanto a isso, para quem está familiarizado com websites. Esta é uma
grande vantagem do uso do REST em relação ao SOAP, pois torna a construção do
WebService algo bastante análogo ao que já existia, ao invés de grandes quantidades de
parâmetros trazidos na forma XML.

Da mesma forma que isto é uma vantagem, em contrapartida, oferece uma grande
desvantagem: não é possível utilizar o método ProcessRequest com outro tipo diferente de
void. Ou seja, este método não pode retornar valores.

Por que devemos usar REST?

REST postula que devemos trabalhar SEMPRE com os métodos nativos do http (os mais
comuns: GET e POST) e evitar utilizar métodos de APIs complexas como o SOAP faz.
Desta maneira o código fica mais claro.

Outro motivo, já mencionado, é sua interação óbvia com páginas web. Como ele realiza sua
comunicação através de métodos nativos do http, podemos realizar chamadas e tratá-las
através de formulários HTML (ou, AJAX/JSON), de forma que todo o processo se torne
independente de plataforma, reconhecido por todos os browsers e tratado da maneira mais
conveniente para os WebDesigners e programadores.

É possível tratar de valores de variáveis e objetos restritos ao ambiente Web, como strings
de formulários e sessões de usuários, bem como Cookies.

REST impõe uma troca de informações mais simples, deixando sua aplicação mais rápida e
menos sujeita a erros de interpretação por parte das aplicações.

Proj.RT.NNN.vv 13
 Abril de 2009

Limitações do REST:

Como a comunicação é feita somente através dos métodos POST e GET, ou seja, troca de
strings, não é possível enviar ou receber objetos complexos, como imagens, arrays ou
objetos de classes criadas pelas aplicações envolvidas de forma direta. Um Webservice
baseado na arquitetura REST deverá receber uma string de entrada e tratá-la de forma a
retornar valores que uma página web apresentaria.

Outra limitação se dá na questão dos WebMethods. Um RESTful WebService pode conter

apenas um WebMethod.

Ou seja, é necessário criar WebMethods mais complexos para atender estes requisitos.

Consumindo um RESTful WebService:

Esta é a parte mais simples. Para consumir um RESTful WebService, devemos apenas criar
um formulário HTML com o parâmetro action definido para o WebService.ashx, utilizando
o method no qual o WebService foi projeto.

Também é possível consumi-lo, no caso de GET, indo diretamente à URL

http://www.meuwebservice.com/webservice.ashx?parametro1=x&parametro2=y(...)

A Microsoft disponibilizou um kit para desenvolvimento de RESTful Applications, não

somente destinado a WebServices, o qual pode ser encontrado aqui:
http://aspnet.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=24644

Este kit possui a estrutura da Windows Communication Foundation pré-montada, sendo

apenas necessário especificar as URL’s e definir os métodos a serem executados a cada tipo
de requisição Http. Mais detalhes podem ser encontrados no artigo Entendendo e
Desenvolvendo Restful WebServices no Framework X-Gov.

Referência Bibliográfica:

Site da MSDN: REST e a WCF:

http://msdn.microsoft.com/en-us/netframework/cc950529.aspx

Proj.RT.NNN.vv 14