Exportar (0) Imprimir
Expandir Tudo

Criando um aplicativo de nota fiscal do Excel usando o Visual Studio Tools for Office, versão 2005

J. Jason De Lorme
Simplesheet, Inc.

Outubro de 2004

Aplica-se a:

  • Microsoft Visual Studio 2005

  • Microsoft Visual Studio Tools for the Microsoft Office System, versão 2005

  • Microsoft Office Excel 2003

Resumo: Leia este artigo para ver uma demonstração de uma solução de nota fiscal do Excel criada no Microsoft Visual C# usando o Microsoft Visual Studio Tools for the Microsoft Office System, versão 2005 Beta 1, e o Microsoft Visual Studio, versão 2005 Beta 1. Este artigo também contém links para páginas em inglês. (19 páginas impressas).

Observação: Este artigo é uma documentação anterior ao lançamento e está sujeito a alterações em lançamentos futuros. O Visual Studio Tools for Office, versão 2005 Beta 1 está incluído no Microsoft Visual Studio, versão 2005 Beta 1.

Baixe VSTOExcelInvoice.msi.

Nesta página

Visão geral do aplicativo de nota fiscal do Excel
Considerações sobre a arquitetura na criação da solução
Desenvolvendo o aplicativo de nota fiscal do Excel
Implantando o aplicativo de nota fiscal do Excel
Segurança de código
Recursos adicionais
Sobre o autor

Visão geral do aplicativo de nota fiscal do Excel

Como proprietário de uma pequena empresa de consultoria, eu vivo imerso em notas fiscais. Embora fundamental na minha atividade, a preparação de notas fiscais pode ser uma das últimas tarefas na minha lista de favoritos. O motivo para isso é o tempo que posso levar para compilar as notas fiscais de um único mês. Para organizar nosso tempo, minha empresa usa um aplicativo de quadro de horários proprietário baseado na Web. Como um bom cidadão do Microsoft .NET Framework, adicionei recentemente alguns serviços da Web que tornaram possível que outros aplicativos comerciais compartilhassem dados de tempo, projetos e clientes básicos do aplicativo de quadro de horários. Este artigo apresenta uma solução de nota fiscal usando o Microsoft Office Excel 2003 e criada com o Microsoft Visual C#, usando o Microsoft Visual Studio Tools for Office, versão 2005 Beta 1. A demonstração utiliza fontes de dados XML de quadro de horários, projeto e clientes.

Histórico

Para os fins desta demonstração, chamaremos minha empresa de Adventure Works, Ltd. A Adventure Works Ltd. é uma empresa de serviços profissionais que cobra seus clientes por tempo e material. Os consultores registram seu tempo por hora em um aplicativo de quadro de horários que oferece suporte à exportação de dados no formato XML. A Adventure Works sempre usa o Excel para criar notas fiscais. O gerente de projeto do cliente deve revisar as entradas do quadro de horários e determinar se são devidas ou se estão fora dos requisitos do contrato. Às vezes, os itens da nota fiscal devem ser editados, removidos ou novos itens devem ser adicionados manualmente antes de enviar a nota fiscal para o cliente.

Regras comerciais

Ao analisar possíveis soluções, a equipe da Adventure Works compilou a seguinte lista de requisitos comerciais para o aplicativo de nota fiscal.

  • Endereços e informações de contato dos clientes devem ser importados de aplicativos comerciais existentes.

  • Apenas os projetos ativos devem ser importados para o cliente que receberá a nota fiscal. Esses projetos devem ser importados do aplicativo comercial existente.

  • As entradas de horário dos consultores devem ser importadas do sistema de quadro de horários e, em seguida, revisadas e editadas, incluindo adições ou exclusões feitas pelo gerente de projeto do cliente.

  • O gerente de projeto deve poder calcular descontos na nota fiscal.

  • Apesar de não haver imposto sobre serviços em nosso estado, às vezes precisamos calcular o imposto sobre determinados materiais. Como isso é raro, a Adventure Works não tem componentes de terceiros para gerenciar o cálculo de impostos. Para essas exceções, o imposto é calculado usando a fórmula na planilha.

  • Se um cliente tem um crédito ou saldo existente, devemos adicioná-lo à nota fiscal e somá-lo ao total.

  • O gerente de projeto solicita os seguintes campos ao revisar o trabalho realizado:

    • Data

    • Horas

    • Descrição

  • A nota fiscal que é enviada para o cliente deve ter os seguintes campos em cada item de linha, na seguinte ordem:

    • Horas

    • Data

    • Nome do recurso

    • Taxa por hora

    • Total do item de linha

  • As notas fiscais são impressas e enviadas para o cliente. O cliente nunca recebe a cópia eletrônica da nota fiscal.

Cenário

Atualmente, para emitir notas fiscais para clientes, um gerente de projeto da Adventure Works usa o aplicativo de quadro de horários baseado na Web para exibir um quadro de horários para cada consultor. Em seguida, ele recorta cada campo disponível do quadro de horários e cola em uma pasta de trabalho de nota fiscal do Excel. Geralmente, a nota fiscal do mês anterior é usada como um modelo para a taxa por hora e para as informações do cliente, mas, freqüentemente, isso gera um problema quando os dados no aplicativo comercial são mudados. Para atenuar esses erros, o gerente de projeto deve verificar sempre no aplicativo comercial as informações de taxa por hora e endereço. A nota fiscal do Microsoft Excel, como mostrada na Figura 1, é impressa e enviada ao cliente.

Cc580620.odc_vstoexcelinvoice_fig1(pt-br,MSDN.10).gif

Figura 1. Nota fiscal do Excel

Solução

Eu criei uma solução para Excel 2003 usando código gerenciado baseado no .NET com o Visual Studio Tools for Office. Essa solução usa fontes de dados XML disponíveis a partir de aplicativos comerciais existentes e elimina as etapas de recortar e colar. A pasta de trabalho tem duas planilhas; a planilha de nota fiscal é o produto final, que é impresso e fornecido para o cliente, e a planilha de dados (Data) é a área de trabalho do usuário. A planilha de dados permite que o gerente do projeto faça as edições necessárias e escolha as entradas que serão aplicadas à nota fiscal. Quando o gerente de projeto abre a pasta de trabalho da nota fiscal no Excel, um painel de tarefas (painel de ações) chamado Document Actions (Ações do Documento) é exibido, permitindo escolher o cliente e o projeto, como mostrado na Figura 2.

Cc580620.odc_vstoexcelinvoice_fig2(pt-br,MSDN.10).gif

Figura 2. Painel de ações de seleção de projeto do cliente

O usuário pode escolher um cliente na lista suspensa do painel de ações. Clicar em Update Client (Atualizar Cliente) preenche as informações de nome, endereço e contato do cliente na planilha de nota fiscal. A alteração do cliente selecionado atualiza a lista de projetos disponíveis na lista suspensa a seguir. Clicar em Get Hours (Obter Horas) recupera todas as entradas do quadro de horários a serem cobradas para esse projeto e leva o usuário para a planilha Data, como mostrado na Figura 3.

Cc580620.odc_vstoexcelinvoice_fig3_thumb(pt-br,MSDN.10).gif

Figura 3. Planilha Data (clique na figura para ver uma imagem ampliada)

A planilha Data (Dados) permite que o usuário edite qualquer entrada, incluindo a adição ou remoção de entradas. Quando o usuário ativa a planilha Data, o painel de tarefas é atualizado para não permitir que o usuário altere o cliente selecionado. Contudo, é permitido obter as horas de projetos adicionais desse cliente. Clicar em Get Hours (Obter Horas) carrega as horas na lista. Clicar em Add To Invoice (Adicionar à Nota Fiscal) na planilha de dados adiciona as entradas à planilha de nota fiscal e a define como a planilha ativa.

Quando a planilha de nota fiscal é ativada, observe que o painel de ações é atualizado com toda a funcionalidade disponível na planilha de nota fiscal. O usuário pode clicar em Clear Invoice (Limpar Nota Fiscal) para limpar o conteúdo de todas as células de itens de linha e do cliente na planilha de nota fiscal.

Requisitos de instalação

Para usar a solução de nota fiscal, você precisa ter os seguintes componentes de software instalados:

  • Microsoft Visual Studio 2005 Beta 1

  • Microsoft Visual Studio Tools for the Microsoft Office System, versão 2005 Beta 1
    Observação: O Visual Studio Tools for Office, versão 2005 Beta 1 está incluído no Visual Studio 2005 Beta 1.

  • Microsoft Office Word 2003 ou Microsoft Office Professional Edition 2003

A ordem de instalação dos produtos é importante. Para executar esta solução, é necessário instalar o Visual Studio 2005 Beta 1 antes de instalar o Office ou o Excel. Com a instalação do Visual Studio, o Microsoft .NET Framework fica disponível e o instalador do Office pode adicionar os PIAs (Primary Interop Assemblies, Módulos de interoperabilidade primários) necessários ao GAC (Global Assembly Cache, Cache de conjunto de módulos global).

  1. Instale o Microsoft Visual Studio 2005 Beta 1.

  2. Execute uma instalação Completa do Microsoft Office 2003 Professional.
    Observação: Somente uma instalação completa inclui os PIAs.

  3. Baixe o pacote associado a este artigo, que contém o código-fonte, a pasta de trabalho do Excel e os arquivos de dados XML.

  4. Extraia esses arquivos em um diretório em seu computador local.

  5. Abra o projeto no Visual Studio .NET 2005 Beta 1 clicando duas vezes no arquivo .sln.

  6. Compile o exemplo clicando com o botão direito do mouse na solução no Solution Explorer e clicando em Build Solution (Criar Solução).

  7. Pressione F5 para executar o exemplo.

Considerações sobre a arquitetura na criação da solução

Usar o Excel sempre foi natural para nós ao compor notas fiscais, embora recortar e colar não fosse uma solução de longo prazo viável. A Adventure Works padronizou o .NET Framework usando a linguagem de programação Visual C# e, ao pensar sobre como automatizar o processo de notas fiscais, considerei várias opções de implementação que pudessem usar nossas habilidades com o Microsoft .NET Framework.

Solução gerenciada .NET

Criar a solução em código gerenciado oferece várias vantagens. O tempo de execução da linguagem comum valida o código conforme ele é compilado. A validação impede que o processo execute operações ilegais, como acessar uma memória que não pertença a ele. Saturações do buffer não autorizadas e outras proezas de segurança comuns podem causar esse tipo de operação ilegal. O heap gerenciado está automaticamente sujeito à coleta de lixo. A coleta de lixo destrói objetos quando eles não são mais necessários ou acessíveis, reduzindo assim o volume de código de suporte necessário para gravar e otimizar de maneira transparente a utilização da memória para nosso processo. Além disso, temos acesso à .NET Framework Class Library, que fornece objetos como o ADO.NET.

ADO.NET

ADO.NET é a camada flexível de acesso a dados no Microsoft .NET Framework que fornece acesso consistente a fontes de dados como o Microsoft SQL Server, bem como a fontes de dados expostas através de OLE DB e XML em uma arquitetura desconectada. Em nome da simplicidade, o exemplo incluído com este artigo usa arquivos XML locais em vez do que poderia ser XML retornado de chamadas de serviços da Web. Ao usar o ADO.NET, você pode tornar a substituição do provedor de dados completamente transparente para o restante do aplicativo.

ASP.NET

Considerando que o aplicativo de quadro de horários já é uma solução ASP.NET baseada na Web, primeiro achei que seria uma extensão lógica adicionar um componente de nota fiscal. O aplicativo poderia ler os dados do banco de dados e produzir uma nota fiscal em HTML. Quando comecei a pensar sobre a implementação da solução da Web, rapidamente lembrei da infinidade de exceções que podem ocorrer ao criar uma nota fiscal. Por exemplo, ocasionalmente precisamos cobrar, além de tempo, o material, ou aplicar um desconto, um saldo ou mesmo créditos. Isso era fácil com a pasta de trabalho do Excel, mas provavelmente seria muito mais trabalhoso de implementar em um aplicativo da Web.

Windows Forms

Como alternativa, considerei criar uma solução no Microsoft Windows Forms. Eu pensei em usar um controle de grade para a área da nota fiscal, permitindo que os usuários importassem as entradas de tempo e que editassem os itens na grade. Isso seria possível na solução ASP.NET, mas os controles do Windows Forms poderiam ter me dado um pouco mais de flexibilidade.

Voltando um passo, me dei conta de que estava para criar uma planilha elegante, mas ela não nos daria a flexibilidade que já tínhamos com o Excel.

Visual Studio Tools for Office

A opção de usar as Edições do Microsoft Office 2003 e particularmente o Excel estava clara. Nossos usuários se sentem mais à vontade usando aplicativos que já conhecem e em que confiam e, além disso, usar o Office nos rende uma economia de um bocado de código.

Tradicionalmente, os suplementos COM e Visual Basic for Applications (VBA) têm sido a principal maneira de estender o Office. Eu acho que o VBA tem seu lugar com utilitários menores e tarefas repetitivas comuns, mas estávamos procurando criar uma solução com código .NET gerenciado, por todas as vantagens já mencionadas.

O Visual Studio Tools for Office nos permite criar soluções escalonáveis usando o Microsoft Office 2003 como uma plataforma de aplicativos. Usando o Visual Studio Tools for Office, você pode criar uma solução do Microsoft Word ou do Excel escrita em C# ou Visual Basic .NET, tirando proveito do .NET Framework completo. Com o Visual Studio Tools for Office 2003, o Office teve ciência, pela primeira vez, do tempo de execução do .NET e nos forneceu grande parte da infra-estrutura necessária para começar a criar soluções do Office confiáveis com o Microsoft .NET.

Desenvolvendo o aplicativo de nota fiscal do Excel

O Visual Studio Tools for Office fornece ótimos invólucros gerenciados para alguns dos modelos de objetos do Office, mas devemos criar a maior parte da automação do Office em objetos COM herdados. Você pode obter acesso aos objetos COM herdados através da interoperabilidade do .NET usando os PIAs.

Optamos por desenvolver esta solução em C#, mas o Visual Studio Tools for Office também oferece suporte ao Visual Basic .NET. As duas linguagens são linguagens de programação de primeira classe baseadas no Microsoft .NET Framework e são igualmente potentes. Muitos dizem que a diferença é simplesmente perfumaria, e que a escolha depende de preferências pessoais. O que está quase correto.

A primeira diferença significativa é que o Visual Basic .NET oferece suporte a parâmetros opcionais e o C# não. O C# depende de uma abordagem de sobrecargas de método orientada a objeto, que não tem suporte no Visual Basic 6.0 e no COM.
Observação: O Visual Basic .NET também oferece suporte à sobrecarga de método.

Você encontrará várias assinaturas de método no modelo de objeto herdado do Office que depende de parâmetros opcionais. Isso pode precisar de alguns truques no C#, como mostrarei. Compare o seguinte método SaveAsDocument no Word:

' Visual Basic
Friend Sub SaveAsDocument()
    ' This overwrites any previously existing 
    ' documents at this location.
    ThisDocument.SaveAs("c:\test\MyNewDocument.doc")
End Sub

// C#
private void SaveAsDocument() 
{ 
    // This overwrites any previously existing 
    // documents at this location. 
    object missingValue = Type.Missing; 
    object fileName = "c:\\test\\MyNewDocument.doc"; 
    ThisDocument.SaveAs(ref fileName, ref missingValue,
        ref missingValue, ref missingValue, ref missingValue,
        ref missingValue, ref missingValue, ref missingValue,
        ref missingValue, ref missingValue, ref missingValue,
        ref missingValue, ref missingValue, ref missingValue,
        ref missingValue, ref missingValue); 
}
	

Você pode ver no exemplo de código anterior que os desenvolvedores de C# devem fornecer valores para todos os parâmetros opcionais, e se você não quiser passar um parâmetro, deverá fornecer uma referência a uma instância de objeto especial de Type.Missing.

A segunda principal diferença entre o C# e o Visual Basic .NET está no trabalho com métodos do acessador. É necessário prefaciar as propriedades herdadas nos modelos de objeto do Office que são acessíveis como XXXX com o Visual Basic .NET com get_XXXX ou set_XXXX ao usar C#.

Apesar dessas pequenas diferenças, tenho uma preferência pela linguagem de programação C# e nós colocaremos algumas linhas extras aqui e ali para poder usá-lo.

Criando o projeto

O assistente New Project (Novo Projeto) no Visual Studio 2005 Beta 1 tem agora um tipo de projeto do Office na linguagem de sua escolha, o que é ligeiramente diferente da versão do Visual Studio 2003.

Para criar um projeto de pasta de trabalho do Excel:

  1. No menu File (Arquivo), aponte para New (Novo) e clique em Project (Projeto).

  2. A caixa de diálogo New Project (Novo Projeto) é exibida.

  3. No painel Project Types (Tipos de Projeto), expanda a linguagem de sua escolha (neste caso, Visual C#) e clique em Office.

  4. No painel Templates (Modelos), selecione Excel Application (Aplicativo do Excel).

  5. Dê um nome ao projeto e o armazene em um diretório local.

  6. Clique em Create a new document (Criar um novo documento) e dê um nome apropriado a ele.


    Observação: Para esta solução, escolhi Use an Existing Document (Usar um Documento Existente) e especifiquei nossa pasta de trabalho de nota fiscal do Excel.
  7. Clique em Finish (Concluir).

Experiência de design

Quando o assistente de projeto é concluído, o primeiro novo recurso do Visual Studio Tools for Office que você observa é mostrado na Figura 4. A nova pasta de trabalho do Microsoft Excel é totalmente hospedada no Visual Studio .NET como uma superfície de design. O Visual Studio mescla menus e interfaces com o aplicativo do Excel.

Cc580620.odc_vstoexcelinvoice_fig4(pt-br,MSDN.10).gif

Figura 4. O Microsoft Excel hospedado no Visual Studio .NET

Se você olhar para o Solution Explorer na Figura 5, observará três classes. É criada uma classe code-behind para cada planilha e uma única classe para a pasta de trabalho.

Cc580620.odc_vstoexcelinvoice_fig5(pt-br,MSDN.10).gif

Figura 5. Solution Explorer

Por padrão, o Excel sempre cria três planilhas para uma nova pasta de trabalho. Para excluir uma planilha da pasta de trabalho, você pode clicar com o botão direito do mouse na guia do modo de exibição Designer e clicar em Excluir. Quando você faz isso, o Visual Studio Tools for Office exclui o arquivo de classe na solução do projeto. A maioria das soluções com as quais trabalhei precisaram de menos de três planilhas, e o código extra me perturba, então é possível alterar o padrão do Excel para a próxima pasta de trabalho que você criar.

  1. No menu Tools (Ferramentas), clique em Options (Opções).
    A caixa de diálogo Options é exibida.
    Dica: Se estiver fazendo isso no ambiente do Visual Studio .NET, no menu Tools (Ferramentas) clique em Microsoft Office Excel Tools (Ferramentas do Microsoft Office Excel) e em Options (Opções). Isso demonstra como o Visual Studio mesclou os menus.

  2. Na guia General (Geral), altere o valor de Sheets (Planilhas) na nova pasta de trabalho para o número desejado.
    Observação: Essa configuração tem efeito na próxima pasta de trabalho criada; ela não exclui nenhuma planilha existente.

Code-behind

Clicar no menu View (Exibir) e escolher Code (Código) ou pressionar F7 exibe a classe code-behind para a planilha ativa. Se você iniciou com uma nova pasta de trabalho em vez de criar a solução a partir de um documento existente, suas classes provavelmente se chamarão Plan1, Plan2, etc. Esses nomes não significam muito para mim, e gostaria de chamar minhas planilhas de acordo com a função que desempenham ou com os dados que contêm.

Existem algumas etapas para renomear uma planilha e realmente não importa a ordem em que são executadas. Eu comecei renomeando a classe. Para isso, clique com o botão direito do mouse no arquivo de classe no Solution Explorer e clique em Rename (Renomear).

Para renomear a classe de uma planilha:

  1. No Solution Explorer, clique com o botão direito do mouse no nome do arquivo de classe.
    O menu de contexto é exibido.

  2. Clique em Rename (Renomear) e digite o novo nome da classe.
    Dica: Verifique se você incluiu a extensão do nome do arquivo ao renomear o arquivo.

Quando você faz isso, o Visual Studio Tools for Office executa várias etapas nos bastidores. Ele renomeia o arquivo no sistema de arquivos, atualiza o arquivo do projeto, atualiza a declaração de nome da classe e atualiza todas as referências ao nome da classe em cada arquivo de classe parcial, sobre o que falaremos rapidamente.

Renomear atualiza todo o código da classe, mas o nome da planilha do Excel permanece o mesmo. O Visual Studio Tools for Office controla essa discrepância exibindo o nome da planilha do Excel entre parênteses ao lado do nome do arquivo de classe. Isso fica visível no Solution Explorer, como mostrado na Figura 6.

Cc580620.odc_vstoexcelinvoice_fig6(pt-br,MSDN.10).gif

Figura 6. O nome da planilha é diferente do nome da classe

Para renomear a planilha:

  1. Do modo de exibição de código, alterne para o modo de exibição do designer. Faça isso pressionando SHIFT + F7 ou clicando em Designer no menu View (Exibir).

    A planilha é exibida no Excel.

  2. Clique com o botão direito do mouse na guia da planilha e clique em Renomear, como mostrado na Figura 7.

    O nome da planilha é realçado.

    Cc580620.odc_vstoexcelinvoice_fig7(pt-br,MSDN.10).gif

    Figura 7. Renomeando a planilha

  3. Digite o novo nome da planilha e pressione ENTER.

Se você voltar para o modo de exibição de código, verá que não haverá muito código para começar, mas poderá observar um novo modificador na declaração de classe:

 public partial class Invoice : Microsoft.Office.Tools.Excel.Worksheet 
	

Para ocultar uma boa parte do código de implementação gerado automaticamente, o Visual Studio Tools for Office está usando classes parciais, que são um novo recurso do Microsoft .NET Framework 2.0. Clicar em Show All (Mostrar Tudo) no Solution Explorer, como mostrado na Figura 8, mostra todos os arquivos usados no projeto.

Cc580620.odc_vstoexcelinvoice_fig8(pt-br,MSDN.10).gif

Figura 8. Botão Show All

Se você examinar o arquivo Invoice.designer.cs, observará outra parte da classe parcial Invoice. As classes parciais oferecem suporte à definição de um tipo em vários arquivos. Às vezes, essa pode não ser uma boa metodologia de design, mas pode ajudar no desenvolvimento em equipe, em que diversas pessoas estão trabalhando em vários aspectos autônomos da classe. Ela também pode ser extremamente útil para o código gerado automaticamente, em que o gerador não precisa substituir o código do usuário, porque ele usa seu próprio arquivo designado.

Globals

Um arquivo físico .cs ou .vb pode conter mais de uma classe e, se você examinar o arquivo Invoice.designer.cs, perto da parte inferior, observará o seguinte código:

public partial class Globals {
    
    private static Invoice _Invoice;
    
    public static Invoice Invoice {
        get {
            return _Invoice;
        }
        set {
            if ((_Invoice == null)) {
                _Invoice = value;
            }
            else {
                throw new System.Data.ReadOnlyException();
            }
        }
    }
} 
	

No arquivo da classe parcial do designer existe um método chamado CreateForClient, que é chamado pela moldura subjacente. O método atribui o valor de sua propriedade Invoice à instância da classe Invoice em execução. Existe realmente uma classe parcial chamada Globals em cada umas das classes de pastas de trabalho e planilhas do *.designer.cs. Quando o módulo (assembly) é compilado, todos esses arquivos de classe parcial são combinados para formar uma única classe, como você pode ver na Figura 9. Isso torna fácil para você acessar propriedades públicas ou internas, e métodos de outras planilhas com código, assim:

Globals.Data.Activate();
	

Cc580620.odc_vstoexcelinvoice_fig9(pt-br,MSDN.10).gif

Figura 9. Classe Globals

Controles de exibição

Como afirmado anteriormente, os controles de exibição estendem os objetos existentes do Word e do Excel; contudo, eles incluem recursos de ligação de dados e eventos. O controle de exibição NamedRange é uma extensão do objeto Range do Excel.

Há várias maneiras de adicionar um NamedRange ao documento. Uma maneira é arrastar o controle da seção Excel Controls (Controles do Excel) na Caixa de ferramentas e soltá-lo sobre o documento. Outra maneira é clicar no menu Insert (Inserir), escolher Name (Nome) e clicar em Define (Definir). De qualquer maneira, é criado um controle de exibição que representa aquele intervalo. É possível examinar as propriedades do intervalo no momento do design com a grade de propriedades no Visual Studio .NET, como mostrado na Figura 10.

Cc580620.odc_vstoexcelinvoice_fig10(pt-br,MSDN.10).gif

Figura 10. Propriedades NamedRange

Para capturar um evento de alteração com um objeto Range nativo do Excel em vez de um Controle de exibição, é necessário manipular o evento de alteração da planilha e determinar se o que mudou foi o intervalo no qual você está interessado.

Private EventDel_CellsChange As Excel.DocEvents_ChangeEventHandler

Private Sub CellsChange(ByVal Target As Excel.Range)
      ' This is called when a cell or cells on a worksheet are changed.
      If Target.ID = "MyInterestingRange" Then
        ' Do something interesting.
      ElseIf Target.ID = "SomethingElseInteresting" Then
        ' Do something else interesting.
      End If
End Sub
	

O controle de exibição NamedRange é um controle baseado em .NET completo, com seus próprios eventos. Por exemplo, para manipular o evento Change em C#, você poderia usar o seguinte código:

// Assign the delegate.
this.myRange.Change += new 
     Microsoft.Office.Interop.Excel.DocEvents_ChangeEventHandler(
     this.myRange_Change); 

void myRange_Change(Microsoft.Office.Interop.Excel.Range Target)
{
     // Do something interesting with this range here.
}	
	

Se você escolher, poderá gerar este código automaticamente, clicando duas vezes no intervalo, a partir do designer.

Tabela 1. Controles de exibição do Excel

Controle

Descrição

NamedRange

Representa um objeto Excel.Range avançado que tem seus próprios eventos e oferece suporte à ligação de dados simples.
Importante: Para ler e gravar o valor deste objeto, use a propriedade Value2.

XMLMappedRange

Um objeto Excel.Range que é criado quando um XmlNode não repetitivo é mapeado para uma célula no Excel.

ListObject

O ListObject é um intervalo que estende várias colunas e linhas, e oferece suporte à classificação em qualquer coluna. ListObject é o único controle de exibição que oferece suporte à ligação de dados complexa, o que significa que ele pode ser ligado a mais de um valor.

Chart

Um objeto Chart de Excel.Application.

Painel de ações

Os documentos inteligentes são um novo recurso apresentado com o Word 2003 e o Excel 2003. Eles oferecem aos usuários funcionalidade e ajuda contextual, usando o painel de ações do documento. Os documentos inteligentes são baseados no documento que está sendo marcado com um esquema XML definido pelo usuário. Até o Visual Studio Tools for Office, versão 2003, a interface ISmartDocument facilitava a programabilidade do painel de tarefas. Toda a funcionalidade de um documento inteligente é determinada pela seleção do XmlNode atual do usuário.

O painel de tarefas de ações é um controle do Windows Forms que é uma implementação gerenciada do painel de tarefas Ações do Documento no Word 2003 e no Excel 2003. Você não fica impedido de implementar funcionalidades semelhantes no painel de ações, mas não é necessário anexar nenhum esquema XML ao documento. Sendo um controle do Windows Forms, o painel de ações funciona como um recipiente de todos os outros controles do Windows Forms, incluindo controles do usuário criados por você. Nesta solução, eu criei um controle do usuário chamado ClientProjectsUserControl e o adicionei ao painel de ações:

// Load the ClientUserControl into the task pane.
ClientProjectsUserControl clientPane = 
     new ClientProjectsUserControl();

this.ActionsPane.Controls.Add(clientPane);
	

Adicionar um controle mostra automaticamente o painel de tarefas, como na Figura 2, mas você pode mostrá-lo ou ocultá-lo explicitamente com o seguinte código:

this.ActionsPane.Show();
. . .this.ActionsPane.Hide();
	

Para remover um controle do painel de ações, chame o método Remove:

// Remove the ClientProjectsUserControl from the actions pane.
this.ActionsPane.Controls.Remove(clientPane);
	

Ligação de dados

A ligação de dados simples existe quando uma única propriedade de controle está ligada a um único valor de fonte de dados. Um exemplo de ligação de dados simples é a propriedade Text do controle Textbox quando ligado a um único valor de dados em um conjunto de dados. Se você atualizar o conjunto de dados, o texto no controle Textbox é atualizado e vice-versa. A ligação de dados complexa ocorre quando seu controle está ligado a mais de um elemento de dados. Esse é o caso em uma lista de controle ListBox, em que DisplayMember e ValueMember estão ligados a colunas diferentes na fonte de dados.

Esta solução usa ligação de dados complexa com um ListObject na planilha Data para exibir entradas de tempo para um determinado projeto, como mostrado na Figura 3. A fonte de dados é um objeto DataSet do ADO.NET. O conjunto de dados é um cache de dados na memória recuperado de uma fonte de dados que inclui as tabelas que contêm, ordenam e limitam os dados, bem como as relações entre as tabelas. Para este exemplo, a fonte de dados do quadro de horários não processado é um arquivo XML localizado no aplicativo.
Dica: Enquanto este exemplo usa arquivos XML locais, você poderá retornar os mesmos dados de uma chamada de serviço da Web e ainda carregá-los em um conjunto de dados de maneira semelhante.

<Timesheets>
    <Timesheet>
        <Tasks>
            <Task projectId="101">
                <Date>5/3/2004</Date>
                <Hours>5</Hours>
                <Description>Reconfigured mail server.</Description>
                <Resource>Craig Playstead</Resource>
                <Rate>80</Rate>
            </Task>
        </Tasks>
    </Timesheet>
</Timesheets>	
	

O código a seguir cria um conjunto de dados e o preenche a partir de um arquivo XML no disco rígido:

// Load timesheet xml into the dataset.
DataSet timesheetDataSet = new DataSet();
timesheetDataSet.ReadXml(filePath);
	

O conjunto de dados é carregado a partir do arquivo XML, incluindo todas as tabelas e relações derivadas implicitamente do esquema do documento XML. Esta fonte de dados contém todas as entradas do quadro de horários de um período especificado. Como visto na Figura 2, o usuário pode escolher um determinado cliente e projeto para os quais obter os dados.

Quando o usuário clica em Get Hours (Obter Horas), eu pego o projeto atual da caixa de listagem e uso o objeto Globals para acessar a instância atual da classe Data e atribuir a propriedade ProjectId, como mostrado a seguir.

private void getHours_Click(object sender, EventArgs e)
{
    Globals.Data.ProjectId =
        int.Parse(projectComboBox.SelectedValue.ToString());
    
    Globals.Data.Activate();
}
	

Se eu ligar ListObject ao conjunto de dados, ele retornará todas as entradas de tempo. Em vez disso, o que preciso fazer é filtrar essa lista somente para os dados que se apliquem ao projeto ativo. Isso é possível usando outro objeto do ADO.NET chamado DataView. DataView é um modo de exibição personalizado de um DataTable que podemos usar para filtragem. Para criar o modo de exibição desejado em meu ListObject, crio um DataView e filtro a lista com base no projeto atual, e a ligo ao ListObject:

// Create the DataView to be used for filtering by projectId.
projectView = new DataView(timesheetDataSet.Tables["Task"]);

// Only show time for the selected project.
projectView.RowFilter =
        string.Format("projectId='{0}'", projectId);

// Data Bind to the ListObject. Notice the 2nd parameter is ""!
timesheetList.SetDataBinding(projectView, "", "Date", "Hours",
        "Description", "Resource", "projectId");
	

Ao criar um DataView filtrado, podemos filtrar apenas as linhas relevantes, que são exibidas no ListObject. Além disso, o método SetDataBinding de ListObject nos permite especificar as colunas que desejamos exibir. Ao chamar SetDataBinding com um DataView como fonte de dados, certifique-se de ter definido o segundo parâmetro como uma seqüência vazia ou a ligação de dados acionará uma exceção.

Outra limitação de ListObjects é que não é possível estendê-lo para células mescladas. Essa limitação não é do Visual Studio Tools for Office, mas do Excel. Por esse motivo, estamos usando um NamedRange na planilha Invoice (Nota fiscal) e preenchendo-a por iteração através de cada DataRowView no DataView quando o usuário clica em Add To Invoice (Adicionar à Nota Fiscal) na planilha Data.

private void addToInvoice_Click(object sender, EventArgs e)
{
     addInvoiceItems();
     Globals.Invoice.Activate();
}
	

Como a solução oferece suporte ao acréscimo de dados ao intervalo, a primeira coisa que preciso procurar no método addInvoiceItems é uma linha em branco no intervalo invoiceItems:

// Starting row on the Invoice sheet.
int row = 0;
int lastRow = Globals.Invoice.invoiceItems.Rows.Count +
    Globals.Invoice.invoiceItems.Row;

// Determine the first blank row to start appending to.
for (row = Globals.Invoice.invoiceItems.Row; row < lastRow; row++)
{
    // Check to see if a value already exists in the first cell.
    Excel.Range start = (Excel.Range)Globals.Invoice.Cells[row,
        Globals.Invoice.invoiceItems.Column];

    // Exit at the first blank row.
    if (start.Value2 == null)
    {
        break;
    }
}
	

Outro ponto que merece cuidado é que não desejo causar um estouro no intervalo designado de itens da nota fiscal na planilha de nota fiscal. A planilha comporta apenas um determinado número de linhas. Pode ser uma boa idéia incluir no futuro um recurso de expansão, mas até o momento isso ainda não foi necessário. Da maneira como o código foi escrito, se for necessário expandir o número de itens, eu apenas aumentarei a planilha e atualizarei o intervalo. Para impedir o estouro e dar suporte a alterações futuras na planilha, adicionei código que garanta que a inserção de linhas não exceda o número de linhas no intervalo.

foreach (DataRowView lineItem in projectView)
{
    // Ensure we don't overrun the Range.
    if (row >= lastRow)
    {
        MessageBox.Show("The invoice items you are attempting to" +
            " add will overrun the size of the invoice.\nPlease " +
            "clear the current invoice items before running this" +
            " operation again.", "Invoice", MessageBoxButtons.OK,
            MessageBoxIcon.Warning);
        
        addToInvoice.Enabled = false;
        break;
    }

    columnOffset = Globals.Invoice.invoiceItems.Column;

    Excel.Range hours =
        (Excel.Range)Globals.Invoice.Cells[row, columnOffset++];
    Excel.Range date =
        (Excel.Range)Globals.Invoice.Cells[row, columnOffset++];
    Excel.Range resource =
        (Excel.Range)Globals.Invoice.Cells[row, columnOffset];
    Excel.Range rate =
        (Excel.Range)Globals.Invoice.Cells[row, columnOffset+7];

    hours.Value2 = lineItem["Hours"];
    date.Value2 = lineItem["Date"];
    resource.Value2 = lineItem["Resource"];
    rate.Value2 = lineItem["Rate"];

    // Increment to the next row.
    row++;
}
	

Incorporando controles do Windows Forms

O recurso final que descrevemos é a capacidade de incorporar controles do Windows Forms na planilha do Excel. Geralmente, você coloca controles na superfície do documento quando deseja o controle presente todo o tempo, e coloca controles no painel de ações quando se baseiam no contexto do documento. Para incorporar um controle na planilha do Excel, é possível arrastá-lo e soltá-lo da Caixa de ferramentas. A Figura 3 mostra um controle de botão na planilha Data, rotulado Add to Invoice (Adicionar à Nota Fiscal) e chamado addToInvoice.

Adicionar um controle do Windows Forms à planilha em comparação com um controle do Microsoft ActiveX nos apresenta as mesmas vantagens abordadas anteriormente com os controles de exibição. Para responder ao clique do botão do usuário, podemos escrever o seguinte código:

// Assign the delegate.
this.addToInvoice.Click += new 
     System.EventHandler(this.addToInvoice_Click);

// Add the items to the Invoice sheet and switch to it.
private void addToInvoice_Click(object sender, EventArgs e)
{
     addInvoiceItems();
     Globals.Invoice.Activate();
}


	

Ao adicionar um controle do Windows Forms à planilha, ocorre uma pequena mágica nos bastidores. Os dados incorporados no documento são, na verdade, um controle ActiveX chamado WinForms.Control.Host, que hospeda o controle gerenciado. Os motivos para isso estão fora do escopo do presente artigo, mas o primeiro é a segurança, e o segundo é o registro COM. Para que o aplicativo do Excel chame um controle gerenciado baseado em .NET, você deverá registrar um invólucro que pode ser chamado por COM para cada tipo de controle. Isso requer entradas do Registro perniciosas e não é orientado a .NET, de forma que o WinForms.Control.Host funciona como um proxy para o Excel.

Implantando o aplicativo de nota fiscal do Excel

Após a versão Beta 1, você poderá implantar as soluções do Visual Studio Tools for Office usando o Publish Wizard (Assistente para Publicação), que copia o documento, os módulos (assemblies) e os manifestos no local da publicação. O trabalho nesse assistente não foi concluído na versão Beta 1, então você poderá implantar as soluções do Visual Studio Tools for Office apenas manualmente, copiando o projeto correspondente para outro computador com o Office Professional 2003 e o Visual Studio 2005 Enterprise Edition Beta 1 instalados. Observe que os componentes de tempo de execução do Visual Studio Tools for Office são instalados atualmente somente com o Visual Studio 2005 Enterprise Edition Beta 1 e ainda não estão disponíveis para redistribuição.

Segurança de código

O código de exemplo ao qual este artigo faz referência se destina a fins de instrução e não deve ser usado em soluções implantadas sem modificações. Particularmente, é necessário considerar a segurança de código.

Para ilustrar a simplicidade desta solução de exemplo, uma lista de possíveis ameaças foi identificada usando as ferramentas e o processo de modelagem de ameaças descritos na seção Threat Modeling (em inglês) do Microsoft Security Developer Center.

Segue um exemplo de uma ameaça identificada que pode ser levada em consideração antes de expandir ou implantar esta solução.

Tabela 2. Exemplo de ameaças

Efeito da ameaça

Ponto de entrada

Atenuação conhecida

Os arquivos de dados XML foram comprometidos e contêm dados inválidos.

DataSet.ReadXml

Marque os arquivos de dados XML como somente leitura.

Para obter mais informações sobre segurança de código, visite o Microsoft Security Developer Center (em inglês).

Recursos adicionais

Visual Studio Tools for Office

Segurança de código

Sobre o autor

J. Jason De Lorme é consultor da Simplesheet, Inc., uma empresa de arquitetura e desenvolvimento de software especializada em soluções criadas com o Microsoft .NET Framework e com as Edições do Microsoft Office 2003. Sendo um adepto de muito tempo, ele gosta de trabalhar com novos produtos, especialmente quando o .NET Framework está envolvido. Quando não está em reuniões com clientes ou escrevendo código, Jason gosta de praticar montanhismo com uma de suas bicicletas.

Mostrar:
© 2015 Microsoft