Expanda os limites do Office usando Web Services

Integre os dados de suas planilhas e documentos com a Internet usando o Office Web Services Toolkit.

por Luiz Cláudio Cosenza V. Rocha

Introdução

Que tal ampliar os horizontes do Microsoft Office, permitindo que o usuário interaja com outros sistemas de sua empresa e com a Internet? A tecnologia ideal para isto são os Web Services, que podem ser facilmente programados no Office por meio do Web Services Toolkit, disponível para as versões XP e 2003.

Este artigo foi escrito usando a versão 2003, mas se você trabalhar com a XP, pode seguir exatamente o mesmo passo a passo.

Office Web Services Toolkit

O Microsoft Office 2003 Web Services Toolkit é uma ferramenta que pode ser adicionada ao editor VBA do Office para simplificar o trabalho com XML Web Services. Trata-se de um recurso que cria um módulo de classe a partir de um WSDL (Web Service Description Language) para a geração e transmissão de mensagens SOAP, deixando o trabalho de codificação muito mais simples para o programador.

Para conhecer melhor o funcionamento do Web Services Toolkit, vamos trabalhar em uma pasta de trabalho do Excel que consome um Web Service de cotação de moedas estrangeiras (CurrencyConvertor), por meio do qual o usuário pode atualizar sua listagem de preços com a cotação do dia e, mais que isto, pode atualizar sua listagem para diferentes moedas.

Downloads necessários

Para seguir o passo a passo deste artigo, você deve fazer agora o download do seguinte material:

• Web Services Toolkit: pode ser obtido a partir do site Microsoft Download Center, no endereço www.microsoft.com/downloads. Faça a busca por palavra-chave, digitando Office Web Services Toolkit.
• Pasta de trabalho Cotação.xls: o arquivo está contido no material de exemplo deste artigo, disponível para download.

Obviamente, após baixar o Web Services Toolkit, você deve fazer a instalação do mesmo, para que o Web Service References seja adicionado ao menu de ferramentas do editor VBA.

Conhecendo o arquivo de exemplo

O arquivo de exemplo (Cotação.xls – Figura 1) contém uma lista de produtos com duas colunas de preços. Na primeira, o valor original em dólares (US$). Na segunda, o valor correspondente em moeda estrangeira. O objetivo proposto é exibir ao usuário uma lista de moedas estrangeiras para ele escolher, e então atualizar os dados da segunda coluna conforme a cotação do dia em relação ao dólar (que é a coluna fixa).

Figura 1: Planilha de exemplo - Cotacao.xls

Ao longo do artigo, será criado o código VBA necessário para automatizar a planilha e integrar com o Web Service CurrencyConvertor, disponível no site www.webservicex.net.

Codificando o UserForm

Com a pasta de trabalho Cotação.xls aberta, acesse o editor VBA do Excel (menu Ferramentas > Macro > Editor do Visual Basic). Veja na janela do Project Explorer (Figura 2) que, além das três planilhas (Plan1, Plan2 e Plan3), o projeto já tem dois formulários criados: UserForm1 e UserForm2.

Figura 2: Project Explorer

Dê um duplo clique sobre o ícone UserForm1 para exibi-lo. Veja que ele contém uma listbox (Listbox1) e um botão de comando (cmdSubmit), que serão codificados a seguir.

Novamente no ícone UserForm1, clique com o botão direito e selecione a opção Exibir código. Na primeira linha, digite:

Option Explicit

Em seguida, insira um procedimento no evento Initialize do UserForm para carregar os itens da listbox (código a seguir). Estes itens nada mais são que o nome das moedas e suas respectivas siglas (veremos mais adiante que estes valores são definidos pelo Web Service). A listagem dos valores foi colocada na planilha Moedas, dentro da própria pasta de trabalho.

Private Sub UserForm_Initialize()

"Carrega a listbox com os itens da planilha Moedas

Dim linha As Integer

On Error GoTo ErrHandler

linha = 1

With Worksheets("Moedas")

Do Until .Cells(linha, 1).Value = Empty

"Exemplo: BRL - Brazilian Real

Me.ListBox1.AddItem .Cells(linha, 1) & " - " _

& .Cells(linha, 2)

linha = linha + 1

Loop

End With

ExitHere:

Exit Sub

ErrHandler:

MsgBox Err.Description

Resume ExitHere

End Sub

Este código percorre as linhas da planilha Moedas até encontrar a primeira célula vazia e vai carregando item a item na listbox, no seguinte formato: “CAD – Canadian Dollar”.

Agora que a listbox está pronta, insira (acima da rotina anterior) o código para o evento Click do botão de comando. Ele deverá fazer o seguinte: obter a sigla da moeda (de três caracteres) e seu nome, retornar a cotação da moeda e preencher a planilha Preços com todas essas informações.

Private Sub cmdSubmit_Click()

Dim strSigla As String

Dim strMoeda As String

"Mouse ampulheta

Me.MousePointer = fmMousePointerHourGlass

"Sigla da moeda

strSigla = Left$(Me.ListBox1.Value, 3)

"Nome da moeda

strMoeda = Mid$(Me.ListBox1.Value, 7, _

Len(Me.ListBox1.Value) - 6)

"Preenche a cotação na planilha Preços

Worksheets("Preços").Range("D3").Value = Cotacao(strSigla)

If Err = 0 Then

"Preenche a sigla da moeda na planilha

Worksheets("Preços").Range("D5") = "Preço " & strSigla

"Preenche o nome da moeda na planilha

Worksheets("Preços").Range("B3") = strMoeda

Else

Worksheets("Preços").Range("D5") = "Preço XXX"

Worksheets("Preços").Range("B3") = Empty

End If

ExitHere:

"Mouse normal

Me.MousePointer = fmMousePointerDefault

"Fecha o formulário

Unload Me

Exit Sub

ErrHandler:

"Se ocorreu erro, a moeda é XXX

strSigla = "XXX"

MsgBox Err.Description

Resume ExitHere

End Sub

Resumindo, este código é responsável pelo preenchimento de três células:

B3: nome da moeda (exemplo: Brazilian Real)

D5: sigla da moeda (exemplo: Preço BRL)

D3: valor da cotação em relação ao dólar (exemplo: 3,01)

Se você mandar compilar o projeto, ocorrerá erro na seguinte linha:

"Preenche a cotação na planilha Preços

Worksheets("Preços").Range("D3").Value = Cotacao(strSigla)

O erro se deve ao fato da função Cotacao() ainda não ter sido definida (ela será criada mais adiante). Como o nome já diz, esta função é responsável por descobrir a cotação da moeda (usando o Web Service CurrencyConvertor).

Apenas para encerrar o módulo do UserForm1, crie uma rotina (logo após cmdSubmit_Click) para ativar o botão de comando apenas quando algum item tiver sido selecionado. Uma linha basta:

Private Sub ListBox1_Change()

"Habilita o botão

Me.cmdSubmit.Enabled = Not IsNull(Me.ListBox1)

End Sub

Na planilha Preços há um botão rotulado Troca moeda, cuja única função é abrir o UserForm1. Para isto, vá ao módulo Plan1 (Preços) e digite:

Option Explicit

Sub AbreForm()

UserForm1.Show vbModal

End Sub

Aproveitando que está no módulo da Plan1, já inclua o código para abrir o UserForm2, que é a janela de diálogo Sobre:

Sub AbreSobre()

UserForm2.Show vbModal

End Sub

Estes dois procedimentos estão associados, respectivamente, aos botões Troca moeda e Sobre..., ambos na planilha Preços.

Usando a ferramenta Web Service Reference

Agora que o código do UserForm1 está pronto, vamos então entrar na parte dos Web Services.

No editor VBA, clique no menu Ferramentas > Web Service References, utilitário que foi instalado com o Toolkit. Será aberta uma janela semelhante a da Figura 3.

Este utilitário permite localizar Web Services (área Web Service Search) em um UDDI Business Registry por palavra-chave (campo Keywords) ou por nome do negócio (campo Business Name).

Para este exemplo, será utilizado um Web Service de endereço já conhecido, portanto não será necessário fazer pesquisa. Selecione a área Web Service URL e digite na caixa URL o seguinte endereço:

http://www.webservicex.net/CurrencyConvertor.asmx?WSDL

Figura 3: Web Service Reference Tool

Clique no botão Search para localizar o Web Service CurrencyConverter e sua descrição. No painel de resultados, assinale o item CurrencyConverter e selecione seu subitem ConversionRate. Para abrir a página de teste (Figura 4), clique no botão Test (obs.: os dados da planilha Moedas foram copiados desta página de teste).

Figura 4: Página de teste ConversionRate

Por fim, volte ao Web Service Reference Tool e clique no botão Add. Aqui a ferramenta cumpre sua verdadeira finalidade, que é a criação de um módulo de classe (clsWS_CurrencyConvertor), responsável por receber e enviar os parâmetros, traduzir os tipos de dados do SOAP para o VBA e submeter a chamada.

Analisando o módulo de classe, temos os seguintes elementos:

· Declaração de uma variável SoapClient30 (sc_CurrencyConvertor): corresponde à uma instância do XML Web Service.

· Uma constante que corresponde ao URL do Web Service WSDL (c_WSDL_URL).

· Constantes usadas na inicialização do Web Service (c_SERVICE, c_PORT, c_SERVICE_NAMESPACE).

· Evento Class_Initialize: instancia o objeto proxy SoapClient, usado para passar as chamadas entre o aplicativo e o servidor Web.

· Evento Class_Terminate: limpa a variável de instância.

· Tratamento de erro (CurrencyConvertorErrorHandler).

· Uma função pública para cada método exposto pelo Web Service (wsm_ConversionRate): é a declaração do próprio método do Web Service, onde serão passados os parâmetros.

Consumindo o Web Service

Na seção anterior você viu que o módulo de classe com a principal parte do código foi criado automaticamente. O trabalho do desenvolvedor, agora, é o de consumir este Web Service, o que será feito pela função Cotacao().

No editor de VBA, crie um módulo padrão (menu Inserir > Módulo) e digite o seguinte código:

Option Explicit

Function Cotacao(SiglaMoeda As String) As Currency

Dim objWS As clsws_CurrencyConvertor "classe criada

"automaticamente pelo Web Services Toolkit

On Error GoTo ErrHandler

"Instancia a classe

Set objWS = New clsws_CurrencyConvertor

Cotacao = objWS.wsm_ConversionRate("USD", SiglaMoeda)

ExitHere:

Exit Function

ErrHandler:

MsgBox Err.Description

Resume ExitHere

End Function

Ao digitar o código, você deve ter notado uma das vantagens em se trabalhar com o módulo de classe clsws_CurrencyConvertor (ou qualquer outro gerado pelo Toolkit): em razão do Early Binding (Dim objWS As clsws_CurrencyConvertor), o recurso do IntelliSense deixa o trabalho do desenvolvedor mais simples para chamar o método do Web Service e passar os parâmetros.

O primeiro parâmetro é “USD”, pois a planilha usa a coluna do dólar como sendo a fixa. O segundo parâmetro é SiglaMoeda, valor que virá do UserForm1.

Compile o projeto (agora sim ele pode ser compilado) e salve o módulo com o nome basCotacao.

Testando o código

Para testar o código, vá à primeira planilha e clique no botão Troca moeda. Será aberto o UserForm1 (Figura 5), com as moedas disponíveis. Ao selecionar uma moeda, o botão Submeter será ativado.

Figura 5: UserForm1 em execução

Selecione uma moeda (ex: BRL – Brazilian Real) e clique em Submeter. O evento Click do botão chamará a função Cotacao(), que por sua vez instanciará a classe clsws_CurrencyConvertor, cujo método wsm_ConversionRate submete a moeda de origem (dólar americano) e destino (selecionada na listbox) e retorna a cotação. O código volta ao Click do botão, que preenche as células D3 (cotação), B3 (nome da moeda) e D5 (sigla). O resultado pode ser visto na Figura 6.

Figura 6: Resultado final

Limpando os dados

Foi visto o passo a passo de como obter o valor da cotação e alterar a planilha. O usuário, entretanto, pode querer limpar a pesquisa, restabelecendo o seu estado original. Para isto, vá ao módulo da Plan1 (Preços) e insira o seguinte procedimento de evento (logo após a rotina AbreSobre):

Sub LimpaCalculo()

On Error GoTo ErrHandler

"Limpa os cálculos de conversão

Range("D3").Value = 1

Range("D5").Value = "Preço XXX"

Range("B3").Value = Empty

ExitHere:

Exit Sub

ErrHandler:

MsgBox Err.Description

Resume ExitHere

End Sub

Esta rotina está associada ao botão Limpa cálculo, na planilha Preços.

Conclusão

Este artigo mostrou como desenvolver uma solução no Office para consumo de Web Services por meio do Office Web Services Toolkit.

O Toolkit simplifica significativamente o trabalho do desenvolvedor, pois faz todo o trabalho de envelopamento e tratamento dos parâmetros, além de possibilitar o uso de IntelliSense. Desta forma, é possível trabalhar com XML Web Services da mesma forma que se faz com classes internas.

O uso destes recursos amplia bastante as funcionalidades dos documentos, agregando valor ao usuário final e possibilitando novos cenários para o desenvolvimento com Office.