Passo a passo: Programação do Office (C# e Visual Basic)

Artigo
06/10/2015

Visual Studio 2010 apresenta novos recursos no C# e no Visual Basic que melhoram a programação do Microsoft Office. Cada linguagem adicionou recursos que já existiam na outra linguagem.

Os novos recursos em C# incluem argumentos nomeados e opcionais, retornam valores que possuem o tipo dynamic e, em programação COM, a capacidade de omitir a palavra-chave ref e acessar propriedades indexadas. Os novos recursos do Visual Basic incluem propriedades implementadas automaticamente, instruções em expressões lambda e inicializadores de coleção.

Ambas as linguagens permitem incorporar as informações de tipo, que permitem a implantação de assemblies que interagem com componentes COM sem implantar assemblies de interoperabilidade primários (PIAs) no computador do usuário. Para obter mais informações, consulte Instruções passo a passo: inserindo tipos de assemblies gerenciados (C# e Visual Basic).

Este passo a passo demonstra os novos recursos no contexto de programação do Office, mas muitos deles também são úteis na programação em geral. No passo a passo, você primeiro usará um aplicativo Suplemento do Excel para criar uma planilha do Excel. Em seguida, você criará um documento do Word que contém um link para a pasta de trabalho. Por fim, você verá como a dependência de PIA pode ser ativada e desativada.

Pré-requisitos

Você deve ter o Microsoft Office Excel 2013 (ou versão 2007 ou posterior) e o Microsoft Office Word 2013 (ou versão 2007 ou posterior) instalado no computador para concluir este passo a passo.

Se você estiver usando um sistema operacional anterior ao Windows Vista, certifique-se de que .NET Framework 2,0 esteja instalado.

Dica

Seu computador pode mostrar nomes ou locais diferentes para alguns dos elementos da interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Personalizando configurações de desenvolvimento no Visual Studio.

Para configurar um aplicativo Suplemento do Excel

Inicie o Visual Studio.
No menu Arquivo, aponte para Novo e clique em Projeto.
No painel Modelos Instalados, expanda Visual Basic ou Visual C#, expanda Office e, em seguida, clique em 2013 (ou 2010 ou 2007).
No painel Modelos, clique em Suplemento do Excel 2013 (ou Suplemento do Excel 2010 ou Suplemento do Excel 2007).
Observe a parte superior do painel Modelos para se certificar de que .NET Framework 4, ou uma versão posterior, é exibido na caixa Estrutura de Destino.
Digite um nome para o seu projeto na caixa Nome, se desejar.
Clique em OK.
Esse novo nome aparece no Gerenciador de Soluções.

Para adicionar referências

No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e clique em Adicionar Referência. A caixa de diálogo Adicionar Referência é exibida.
Na guia Assemblies, selecione Microsoft.Office.Interop.Excel, versão 15.0.0.0 (ou versão 14.0.0.0 para Excel 2010 ou versão 12.0.0.0 para Excel 2007), na lista Nome do Componente e, em seguida, mantenha pressionada a tecla CTRL e selecione Microsoft.Office.Interop.Word, versão 15.0.0.0 (ou versão 14.0.0.0 para Word 2010 ou 12.0.0.0 para Word 2007). Se você não vir os assemblies, talvez seja necessário verificar se eles estão instalados e exibidos (consulte Como instalar assemblies de interoperabilidade primários do Office).
Clique em OK.

Para adicionar instruções Imports necessárias ou diretivas de uso

No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo ThisAddIn.vb ou ThisAddIn.cs e clique em Exibir Código.
Adicione as seguintes instruções Imports (Visual Basic) ou diretivas using (C#) à parte superior do arquivo de código, se elas ainda não estiverem presentes.
```
Imports Microsoft.Office.Interop
```
```
using System.Collections.Generic;
using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;
```

Para criar uma lista de contas bancárias

No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto, clique em Adicionar e clique em Classe. Nomeie a classe Account.vb se você estiver usando Visual Basic ou Account.cs, se você estiver usando C#. Clique em Adicionar.
Substitua a definição da classe Account pelo código a seguir. As definições de classe usam propriedades implementadas automaticamente, novas no Visual Basic no Visual Studio 2010. Para obter mais informações, consulte Propriedades autoimplementadas (Visual Basic).
```
Public Class Account
    Property ID As Integer = -1
    Property Balance As Double 
End Class
```
```
class Account
{
    public int ID { get; set; }
    public double Balance { get; set; }
}
```

Para criar uma lista bankAccounts que contém duas contas, adicione o seguinte código ao método ThisAddIn_Startup em ThisAddIn.vb ou ThisAddIn.cs. As declarações da lista usam inicializadores de coleção, novos no Visual Basic no Visual Studio 2010. Para obter mais informações, consulte Inicializadores de coleção (Visual Basic).

Dim bankAccounts As New List(Of Account) From {
    New Account With {
                          .ID = 345,
                          .Balance = 541.27
                     },
    New Account With {
                          .ID = 123,
                          .Balance = -127.44
                     }
    }

var bankAccounts = new List<Account> 
{
    new Account 
    {
        ID = 345,
        Balance = 541.27
    },
    new Account 
    {
        ID = 123,
        Balance = -127.44
    }
};

Para exportar dados para o Excel

No mesmo arquivo, adicione o método a seguir para a classe ThisAddIn. O método configura uma planilha do Excel e exporta dados para ela.
```
Sub DisplayInExcel(ByVal accounts As IEnumerable(Of Account),
               ByVal DisplayAction As Action(Of Account, Excel.Range))

    With Me.Application
        ' Add a new Excel workbook.
        .Workbooks.Add()
        .Visible = True
        .Range("A1").Value = "ID"
        .Range("B1").Value = "Balance"
        .Range("A2").Select()

        For Each ac In accounts
            DisplayAction(ac, .ActiveCell)
            .ActiveCell.Offset(1, 0).Select()
        Next 

        ' Copy the results to the Clipboard.
        .Range("A1:B3").Copy()
    End With 
End Sub
```
```
void DisplayInExcel(IEnumerable<Account> accounts,
           Action<Account, Excel.Range> DisplayFunc)
{
    var excelApp = this.Application;
    // Add a new Excel workbook.
    excelApp.Workbooks.Add();
    excelApp.Visible = true;
    excelApp.Range["A1"].Value = "ID";
    excelApp.Range["B1"].Value = "Balance";
    excelApp.Range["A2"].Select();

    foreach (var ac in accounts)
    {
        DisplayFunc(ac, excelApp.ActiveCell);
        excelApp.ActiveCell.Offset[1, 0].Select();
    }
    // Copy the results to the Clipboard.
    excelApp.Range["A1:B3"].Copy();
}
```
Dois novos recursos do C# são usados neste método. Esses dois recursos já existem no Visual Basic.
- O método Add possui um parâmetro opcional para especificar um determinado modelo. Parâmetros opcionais, novos no Visual C# 2010, permitem omitir o argumento para esse parâmetro, se você deseja usar o valor padrão do parâmetro. Como nenhum argumento é enviado no código anterior, Add usa o modelo padrão e cria uma nova pasta de trabalho. A instrução equivalente em versões anteriores do C# requer um argumento de espaço reservado: excelApp.Workbooks.Add(Type.Missing).
  
  Para obter mais informações, consulte Argumentos nomeados e opcionais (Guia de Programação em C#).
- As propriedades Range e Offset do objeto Range usam o recurso propriedades indexadas. Este recurso permite consumir essas propriedades de tipos COM usando a sintaxe típica do C# a seguir. Propriedades indexadas também permitem que você use a propriedade Value do objeto Range, eliminando a necessidade de usar a propriedade Value2. A propriedade Value é indexada, mas o índice é opcional. Argumentos opcionais e propriedades indexadas trabalham juntos no exemplo a seguir.
```
// Visual C# 2010 provides indexed properties for COM programming.
excelApp.Range["A1"].Value = "ID";
excelApp.ActiveCell.Offset[1, 0].Select();
```
  Em versões anteriores da linguagem, a sintaxe especial a seguir é obrigatória.
```
// In Visual C# 2008, you cannot access the Range, Offset, and Value 
// properties directly.
excelApp.get_Range("A1").Value2 = "ID";
excelApp.ActiveCell.get_Offset(1, 0).Select();
```
  Não é possível criar propriedades indexadas de sua preferência. O recurso dá suporte apenas ao consumo de propriedades indexadas existentes.
  
  Para obter mais informações, consulte Como usar propriedades indexadas na programação para interoperabilidade COM (Guia de Programação em C#).
Adicione o seguinte código no final de DisplayInExcel para ajustar as larguras das colunas para adequar o conteúdo.
```
' Add the following two lines at the end of the With statement.
.Columns(1).AutoFit()
.Columns(2).AutoFit()
```
```
excelApp.Columns[1].AutoFit();
excelApp.Columns[2].AutoFit();
```
Essas adições demonstram outro recurso novo em C# 2010: tratar valores Object retornados de hosts COM como o Office, como se eles tivessem o tipo dinâmico. Isso acontece automaticamente quando Inserir Tipos Interop está definido como o valor padrão, True, ou, de forma equivalente, quando o assembly é referenciado pela opção de compilador /link. O tipo dynamic permite a vinculação posterior, já disponível no Visual Basic, e evita a conversão explícita necessária no Visual C# 2008 e em versões anteriores da linguagem.

Por exemplo, excelApp.Columns[1] retorna um Object e AutoFit é um método Range do Excel. Sem dynamic, você deve converter o objeto retornado em excelApp.Columns[1] como uma instância de Range antes de chamar o método AutoFit.
```
// Casting is required in Visual C# 2008.
((Excel.Range)excelApp.Columns[1]).AutoFit();

// Casting is not required in Visual C# 2010.
excelApp.Columns[1].AutoFit();
```
Para obter mais informações sobre como inserir tipos de interoperabilidade, consulte os procedimentos "Para localizar a referência de PIA" e "Para restaurar a dependência de PIA" posteriormente neste tópico. Para obter mais informações sobre dynamic, consulte dynamic (Referência de C#) ou Usando o tipo dynamic (Guia de Programação em C#).

Para invocar DisplayInExcel

Adicione o código a seguir no final do método ThisAddIn_StartUp. A chamada para DisplayInExcel contém dois argumentos. O primeiro argumento é o nome da lista de contas a ser processada. O segundo argumento é uma expressão lambda com várias linhas que define como os dados deverão ser processados. Os valores ID e balance de cada conta serão exibidos em células adjacentes e a linha será exibida em vermelho se o equilíbrio for menor do que zero. Expressões lambda com várias linhas são um novo recurso do Visual Basic 2010. Para obter mais informações, consulte Expressões lambda (Visual Basic).

DisplayInExcel(bankAccounts,
       Sub(account, cell)
           ' This multiline lambda expression sets custom 
           ' processing rules for the bankAccounts.
           cell.Value = account.ID
           cell.Offset(0, 1).Value = account.Balance

           If account.Balance < 0 Then
               cell.Interior.Color = RGB(255, 0, 0)
               cell.Offset(0, 1).Interior.Color = RGB(255, 0, 0)
           End If 
       End Sub)

DisplayInExcel(bankAccounts, (account, cell) =>
// This multiline lambda expression sets custom processing rules   
// for the bankAccounts.
{
    cell.Value = account.ID;
    cell.Offset[0, 1].Value = account.Balance;
    if (account.Balance < 0)
    {
        cell.Interior.Color = 255;
        cell.Offset[0, 1].Interior.Color = 255;
    }
});

Para executar o programa, pressione F5. Uma planilha do Excel é exibida contendo os dados das contas.

Para adicionar um documento do Word

Adicione o código a seguir ao final do método ThisAddIn_StartUp para criar um documento do Word que contém um link para a pasta de trabalho do Excel.
```
Dim wordApp As New Word.Application
wordApp.Visible = True
wordApp.Documents.Add()
wordApp.Selection.PasteSpecial(Link:=True, DisplayAsIcon:=True)
```
```
var wordApp = new Word.Application();
wordApp.Visible = true;
wordApp.Documents.Add();
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
```
Esse código demonstra vários dos novos recursos no C#: a capacidade para omitir a palavra-chave ref em programação COM, argumentos nomeados e argumentos opcionais. Esses recursos já existem no Visual Basic. O método PasteSpecial tem sete parâmetros, que são definidos como parâmetros de referência opcionais. Antes do Visual C# 2010, era necessário definir as variáveis de objeto a serem usadas como argumentos para os sete parâmetros, mesmo quando você não tinha nenhum valor significativo para enviar. Argumentos opcionais e nomeados permitem designar os parâmetros que você deseja acessar pelo nome e enviar argumentos apenas para esses parâmetros. Neste exemplo, os argumentos são enviados para indicar que deve ser criado um link para a pasta de trabalho na área de transferência (parâmetro Link), e que o link será exibido no documento do Word como um ícone (parâmetro DisplayAsIcon). O Visual c# 2010 permite também que você omita a palavra-chave ref nesses argumentos. Compare o segmento de código a seguir do Visual C# 2008 com a única linha necessária no Visual C# 2010:
```
// Call to PasteSpecial in Visual C# 2008. 
object iconIndex = Type.Missing;
object link = true;
object placement = Type.Missing;
object displayAsIcon = true;
object dataType = Type.Missing;
object iconFileName = Type.Missing;
object iconLabel = Type.Missing;
wordApp.Selection.PasteSpecial(ref iconIndex,
                               ref link,
                               ref placement,
                               ref displayAsIcon,
                               ref dataType,
                               ref iconFileName,
                               ref iconLabel);

// Call to PasteSpecial in Visual C# 2010.
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
```

Para executar o aplicativo

Pressione F5 para executar o aplicativo. O Excel é iniciado e exibe uma tabela que contém as informações das duas contas em bankAccounts. Em seguida, um documento do Word é exibido contendo um link para a tabela do Excel.

Para limpar o projeto concluído

No Visual Studio, clique em Limpar Solução no menu Compilar. Caso contrário, o suplemento será executado toda vez que você abrir o Excel no seu computador.

Para localizar a referência de PIA

Execute o aplicativo novamente, mas não clique em Limpar Solução.
No menu Iniciar, clique em Todos os Programas. Em seguida, clique em Microsoft Visual Studio 2013, em Ferramentas do Visual Studio e em Prompt de Comando do Visual Studio (2013).
Digite ildasm na janela Prompt de Comando do Visual Studio (2013) e pressione ENTER. A janela IL DASM é exibida.
No menu Arquivo na janela IL DASM, clique em abrir. Clique duas vezes em Visual Studio 2013e clique duas vezes em Projetos. Abra a pasta do seu projeto e procure na pasta bin/Debug por nome do projeto.dll. Clique duas vezes em nome do projeto.dll. Uma nova janela exibe os atributos do projeto, além das referências a outros módulos e assemblies. Observe que os namespaces Microsoft.Office.Interop.Excel e Microsoft.Office.Interop.Word estão incluídos no assembly. Por padrão, no Visual Studio 2013, o compilador importa os tipos que você precisa de um PIA referenciado para o seu assembly.

Para obter mais informações, consulte Como exibir o conteúdo de um assembly.
Clique duas vezes no ícone MANIFEST. Uma janela será exibida contendo uma lista de assemblies que contêm itens referenciados pelo projeto. Microsoft.Office.Interop.Excel e Microsoft.Office.Interop.Word não estão incluídos na lista. Como os tipos do seu projeto precisam ter sido importados para o assembly, referências a um PIA não são necessárias. Isso facilita a implantação. Os PIAs não precisam estar presentes no computador do usuário e como um aplicativo não requer a implantação de uma versão específica de um PIA, os aplicativos podem ser projetados para trabalhar com várias versões do Office, desde que as APIs necessárias existam em todas as versões.

Como a implantação de PIAs não é mais necessária, você pode criar um aplicativo em cenários avançados que funcione com várias versões do Office, incluindo versões anteriores. No entanto, isso funcionará apenas se seu código não usar quaisquer APIs que não estejam disponíveis na versão do Office na qual você está trabalhando. Não é sempre claro se uma determinada API estava disponível em uma versão anterior e, por essa razão, não é recomendado trabalhar com versões anteriores do Office.

Dica

O Office não publicou PIAs antes do Office 2003.Portanto, a única maneira de gerar um assembly de interoperabilidade para o Office 2002 ou versões anteriores é importando referência COM.
Feche a janela do manifesto e a janela do assembly.

Para restaurar a dependência de PIA

Em Gerenciador de Soluções, clique no botão Mostrar Todos os Arquivos. Expanda a pasta Referências e selecione Microsoft.Office.Interop.Excel. Pressione F4 para exibir a janela Propriedades.
Na janela Propriedades, altere a propriedade Inserir Tipos Interop de True para False.
Repita as etapas 1 e 2 deste procedimento para Microsoft.Office.Interop.Word.
Em C#, comente as duas chamadas para Autofit no final do método DisplayInExcel.
Pressione F5 para verificar se o projeto ainda é executado corretamente.
Repita as etapas de 1 a 3 do procedimento anterior para abrir a janela do assembly. Observe que Microsoft.Office.Interop.Word e Microsoft.Office.Interop.Excel não estão mais na lista de assemblies inseridos.
Clique duas vezes no ícone MANIFEST e percorra a lista de assemblies referenciados. Ambos Microsoft.Office.Interop.Word e Microsoft.Office.Interop.Excel estão na lista. Como o aplicativo faz referência aos PIAs do Excel e do Word e a propriedade Inserir Tipos Interop está definida como False, ambos os assemblies devem existir no computador do usuário final.
No Visual Studio, clique em Limpar solução no menu Compilar para limpar o projeto concluído.

Consulte também

Compartilhar via