Como acessar objetos de interoperabilidade do Office

  • Artigo

O C# tem recursos que simplificam o acesso a objetos de API do Office. Os novos recursos incluem argumentos nomeados e opcionais, um novo tipo chamado dynamic e a capacidade de passar argumentos para parâmetros de referência em métodos COM como se fossem parâmetros de valor.

Neste artigo, você usará os novos recursos para escrever código que cria e exibe uma planilha do Microsoft Office Excel. Escreva o código para adicionar um documento do Office Word que contenha um ícone que esteja vinculado à planilha do Excel.

Para concluir este passo a passo, você deve ter o Microsoft Office Excel 2007 e o Microsoft Office Word 2007 ou versões posteriores, instaladas no computador.

Observação

Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de 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 o IDE.

Importante

O Visual Studio Tools para Office (VSTO) depende do .NET Framework. Os suplementos COM também podem ser gravados com o .NET Framework. Os suplementos do Office não podem ser criados com o .NET Core e o .NET 5+, as versões mais recentes do .NET. Isso ocorre porque o .NET Core/.NET 5+ não pode trabalhar em conjunto com o .NET Framework no mesmo processo e pode levar a falhas de carga de suplemento. Você pode continuar a usar o .NET Framework para escrever suplementos VSTO e COM para o Office. A Microsoft não atualizará o VSTO ou a plataforma de suplemento COM para usar o .NET Core ou o .NET 5+. Você pode aproveitar o .NET Core e o .NET 5+, incluindo o ASP.NET Core, para criar o lado do servidor dos Suplementos Web do Office.

Para criar um novo aplicativo de console

  1. Inicie o Visual Studio.
  2. No menu Arquivo , aponte para Novoe selecione Projeto. A caixa de diálogo Novo Projeto aparecerá.
  3. No painel Modelos Instalados, expanda C# e selecione Windows.
  4. Observe a parte superior da caixa de diálogo Novo Projeto para selecionar .NET Framework 4 (ou versão posterior) como uma estrutura de destino.
  5. No painel Modelos, selecione Aplicativo de Console.
  6. Digite um nome para o projeto no campo Nome.
  7. Selecione OK.

O novo projeto aparece no Gerenciador de Soluções.

Para adicionar referências

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e, em seguida, selecione Adicionar Referência. A caixa de diálogo Adicionar Referência é exibida.
  2. Na página Assemblies, selecione Microsoft.Office.Interop.Word na lista Nome do Componente e, mantendo a tecla CTRL pressionada, selecione Microsoft.Office.Interop.Excel. Se você não vir os assemblies, talvez seja necessário instalá-los. Confira Como instalar assemblies de interoperabilidade primários do Office.
  3. Selecione OK.

Para adicionar as diretivas using necessárias

No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Program.cs e, em seguida, selecione Exibir Código. Adicione as seguintes diretivas using na parte superior do arquivo de código:

using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;

Para criar uma lista de contas bancárias

Cole a seguinte definição de classe em Program.cs, na classe Program.

public class Account
{
    public int ID { get; set; }
    public double Balance { get; set; }
}

Adicione o seguinte código ao método Main para criar uma lista bankAccounts que contenha duas contas.

// Create a list of accounts.
var bankAccounts = new List<Account> {
    new Account {
                  ID = 345678,
                  Balance = 541.27
                },
    new Account {
                  ID = 1230221,
                  Balance = -127.44
                }
};

Para declarar um método que exporta as informações de conta para o Excel

  1. Adicione o método a seguir à classe Program para configurar uma planilha do Excel. O método Add tem um parâmetro opcional para especificar um modelo específico. Os parâmetros opcionais permitem omitir o argumento para esse parâmetro, se você deseja usar o valor padrão do parâmetro. Como você não forneceu um argumento, Add usará o modelo padrão e criará 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).
static void DisplayInExcel(IEnumerable<Account> accounts)
{
    var excelApp = new Excel.Application();
    // Make the object visible.
    excelApp.Visible = true;

    // Create a new, empty workbook and add it to the collection returned
    // by property Workbooks. The new workbook becomes the active workbook.
    // Add has an optional parameter for specifying a particular template.
    // Because no argument is sent in this example, Add creates a new workbook.
    excelApp.Workbooks.Add();

    // This example uses a single workSheet. The explicit type casting is
    // removed in a later procedure.
    Excel._Worksheet workSheet = (Excel.Worksheet)excelApp.ActiveSheet;
}

Adicione o código a seguir no final de DisplayInExcel. O código insere valores nas duas primeiras colunas da primeira linha da planilha.

// Establish column headings in cells A1 and B1.
workSheet.Cells[1, "A"] = "ID Number";
workSheet.Cells[1, "B"] = "Current Balance";

Adicione o código a seguir no final de DisplayInExcel. O loop foreach coloca as informações da lista de contas nas duas primeiras colunas de sucessivas linhas da planilha.


var row = 1;
foreach (var acct in accounts)
{
    row++;
    workSheet.Cells[row, "A"] = acct.ID;
    workSheet.Cells[row, "B"] = acct.Balance;
}

Adicione o seguinte código no final de DisplayInExcel para ajustar as larguras das colunas para adequar o conteúdo.

workSheet.Columns[1].AutoFit();
workSheet.Columns[2].AutoFit();

As versões anteriores do C# exigem a conversão explícita para essas operações, porque ExcelApp.Columns[1] retorna um Object, e AutoFit é um método Range do Excel. As linhas a seguir mostram a conversão.

((Excel.Range)workSheet.Columns[1]).AutoFit();
((Excel.Range)workSheet.Columns[2]).AutoFit();

O C# converte o Object retornado em dynamic automaticamente, se o assembly for referenciado pela opção do compilador EmbedInteropTypes ou, de maneira equivalente, se a propriedade Inserir Tipos de Interoperabilidade do Excel for true. True é o valor padrão para essa propriedade.

Para executar o projeto

Adicione a seguinte linha no final de Main.

// Display the list in an Excel spreadsheet.
DisplayInExcel(bankAccounts);

Pressione CTRL+F5. Uma planilha do Excel é exibida contendo os dados das duas contas.

Para adicionar um documento do Word

O código a seguir abre um aplicativo do Word e cria um ícone que é vinculado à planilha do Excel. Cole o método CreateIconInWordDoc, fornecido posteriormente nesta etapa, na classe Program. O CreateIconInWordDoc usa argumentos nomeados e opcionais para reduzir a complexidade das chamadas de método a Add e PasteSpecial. Essas chamadas incorporam dois recursos que simplificam as chamadas para métodos COM que possuem parâmetros de referência. Primeiro, você pode enviar argumentos para os parâmetros de referência como se fossem parâmetros de valor. Ou seja, você pode enviar valores diretamente, sem criar uma variável para cada parâmetro de referência. O compilador gera variáveis temporárias para conter os valores de argumento e descarta as variáveis quando você retornar da chamada. Em segundo lugar, você pode omitir a palavra-chave ref na lista de argumentos.

O método Add tem quatro parâmetros de referência que são opcionais. Você poderá omitir argumentos para alguns ou todos os parâmetros se desejar usar os valores padrão.

O método PasteSpecial insere o conteúdo da área de transferência. O método tem sete parâmetros de referência que são opcionais. O código a seguir especifica argumentos para dois deles: Link, para criar um link para a origem do conteúdo da área de transferência, e DisplayAsIcon, para exibir o link como um ícone. Você pode usar argumentos nomeados para esses dois argumentos e omitir os outros. Embora esses argumentos sejam parâmetros de referência, você não precisa usar a palavra-chave ref ou criar variáveis para os enviar como argumentos. Você pode enviar os valores diretamente.

static void CreateIconInWordDoc()
{
    var wordApp = new Word.Application();
    wordApp.Visible = true;

    // The Add method has four reference parameters, all of which are
    // optional. Visual C# allows you to omit arguments for them if
    // the default values are what you want.
    wordApp.Documents.Add();

    // PasteSpecial has seven reference parameters, all of which are
    // optional. This example uses named arguments to specify values
    // for two of the parameters. Although these are reference
    // parameters, you do not need to use the ref keyword, or to create
    // variables to send in as arguments. You can send the values directly.
    wordApp.Selection.PasteSpecial( Link: true, DisplayAsIcon: true);
}

Adicione a instrução a seguir no final de Main.

// Create a Word document that contains an icon that links to
// the spreadsheet.
CreateIconInWordDoc();

Adicione a instrução a seguir no final de DisplayInExcel. O método Copy adiciona a planilha na área de transferência.

// Put the spreadsheet contents on the clipboard. The Copy method has one
// optional parameter for specifying a destination. Because no argument
// is sent, the destination is the Clipboard.
workSheet.Range["A1:B3"].Copy();

Pressione CTRL+F5. Um documento do Word é exibido contendo um ícone. Clique duas vezes no ícone para colocar a planilha no primeiro plano.

Para definir a propriedade Inserir Tipos Interop

Outras melhorias são possíveis quando você chama um tipo COM que não requer um assembly de interoperabilidade primário (PIA) no tempo de execução. A remoção da dependência nos PIAs resulta na independência de versão e em uma implantação mais fácil. Para obter mais informações sobre as vantagens da programação sem PIAs, consulte Passo a passo: inserindo tipos de assemblies gerenciados.

Além disso, a programação é mais fácil porque o tipo dynamic representa os tipos necessários e retornados declarados em métodos COM. Variáveis com o tipo dynamic não são avaliadas até o tempo de execução, o que elimina a necessidade de conversão explícita. Para obter mais informações, veja Usando o tipo dynamic.

A inserção de informações de tipo, em vez do uso de PIAs, é o comportamento padrão. Devido a esse padrão, vários dos exemplos anteriores são simplificados. Você não precisa de nenhuma conversão explícita. Por exemplo, a declaração de worksheet em DisplayInExcel é escrita como Excel._Worksheet workSheet = excelApp.ActiveSheet, em vez de Excel._Worksheet workSheet = (Excel.Worksheet)excelApp.ActiveSheet. As chamadas para AutoFit no mesmo método também exigem conversão explícita sem o padrão, pois ExcelApp.Columns[1] retorna um Object, e AutoFit é um método do Excel. O código a seguir mostra a conversão.

((Excel.Range)workSheet.Columns[1]).AutoFit();
((Excel.Range)workSheet.Columns[2]).AutoFit();

Para alterar o padrão e usar PIAs em vez de inserir informações de tipo, expanda o nó Referências no Gerenciador de Soluções e, em seguida, selecione Microsoft.Office.Interop.Excel ou Microsoft.Office.Interop.Word. Se você não conseguir ver a janela Propriedades, pressione F4. Localize Inserir Tipos Interop na lista de propriedades e altere seu valor para False. De maneira equivalente, você pode compilar usando a opção do compilador Referências, em vez de EmbedInteropTypes em um prompt de comando.

Para adicionar formatação adicional à tabela

Substitua as duas chamadas para AutoFit em DisplayInExcel pela instrução a seguir.

// Call to AutoFormat in Visual C# 2010.
workSheet.Range["A1", "B3"].AutoFormat(
    Excel.XlRangeAutoFormat.xlRangeAutoFormatClassic2);

O método AutoFormat tem sete parâmetros de valor, que são opcionais. Argumentos nomeados e opcionais permitem que você forneça argumentos para nenhum, alguns ou todos eles. Na instrução anterior, você fornece um argumento para apenas um dos parâmetros, Format. Como Format é o primeiro parâmetro na lista de parâmetros, você não precisará fornecer o nome do parâmetro. No entanto, poderá ser mais fácil entender a instrução se você incluir o nome do parâmetro, conforme mostrado no código a seguir.

// Call to AutoFormat in Visual C# 2010.
workSheet.Range["A1", "B3"].AutoFormat(Format:
    Excel.XlRangeAutoFormat.xlRangeAutoFormatClassic2);

Pressione CTRL + F5 para ver o resultado. Você pode encontrar outros formatos na lista na enumeração XlRangeAutoFormat.

Exemplo

O código a seguir mostra um exemplo completo.

using System.Collections.Generic;
using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;

namespace OfficeProgrammingWalkthruComplete
{
    class Walkthrough
    {
        static void Main(string[] args)
        {
            // Create a list of accounts.
            var bankAccounts = new List<Account>
            {
                new Account {
                              ID = 345678,
                              Balance = 541.27
                            },
                new Account {
                              ID = 1230221,
                              Balance = -127.44
                            }
            };

            // Display the list in an Excel spreadsheet.
            DisplayInExcel(bankAccounts);

            // Create a Word document that contains an icon that links to
            // the spreadsheet.
            CreateIconInWordDoc();
        }

        static void DisplayInExcel(IEnumerable<Account> accounts)
        {
            var excelApp = new Excel.Application();
            // Make the object visible.
            excelApp.Visible = true;

            // Create a new, empty workbook and add it to the collection returned
            // by property Workbooks. The new workbook becomes the active workbook.
            // Add has an optional parameter for specifying a particular template.
            // Because no argument is sent in this example, Add creates a new workbook.
            excelApp.Workbooks.Add();

            // This example uses a single workSheet.
            Excel._Worksheet workSheet = excelApp.ActiveSheet;

            // Earlier versions of C# require explicit casting.
            //Excel._Worksheet workSheet = (Excel.Worksheet)excelApp.ActiveSheet;

            // Establish column headings in cells A1 and B1.
            workSheet.Cells[1, "A"] = "ID Number";
            workSheet.Cells[1, "B"] = "Current Balance";

            var row = 1;
            foreach (var acct in accounts)
            {
                row++;
                workSheet.Cells[row, "A"] = acct.ID;
                workSheet.Cells[row, "B"] = acct.Balance;
            }

            workSheet.Columns[1].AutoFit();
            workSheet.Columns[2].AutoFit();

            // Call to AutoFormat in Visual C#. This statement replaces the
            // two calls to AutoFit.
            workSheet.Range["A1", "B3"].AutoFormat(
                Excel.XlRangeAutoFormat.xlRangeAutoFormatClassic2);

            // Put the spreadsheet contents on the clipboard. The Copy method has one
            // optional parameter for specifying a destination. Because no argument
            // is sent, the destination is the Clipboard.
            workSheet.Range["A1:B3"].Copy();
        }

        static void CreateIconInWordDoc()
        {
            var wordApp = new Word.Application();
            wordApp.Visible = true;

            // The Add method has four reference parameters, all of which are
            // optional. Visual C# allows you to omit arguments for them if
            // the default values are what you want.
            wordApp.Documents.Add();

            // PasteSpecial has seven reference parameters, all of which are
            // optional. This example uses named arguments to specify values
            // for two of the parameters. Although these are reference
            // parameters, you do not need to use the ref keyword, or to create
            // variables to send in as arguments. You can send the values directly.
            wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
        }
    }

    public class Account
    {
        public int ID { get; set; }
        public double Balance { get; set; }
    }
}

Confira também