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ê usa os novos recursos para escrever código que cria e exibe uma planilha do Microsoft Office Excel. Você escreve código para adicionar um documento do Office Word que contém um ícone que está 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, instalados no seu computador.

Nota

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ê tem e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Personalizando o IDE.

Importante

O VSTO (Visual Studio Tools for Office) depende do .NET Framework. Os suplementos COM também podem ser escritos 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 carregamento de suplementos. 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 Novo e selecione Projeto. Aparece a caixa de diálogo Novo Projeto.
  3. No painel Modelos Instalados, expanda C# e selecione Windows.
  4. Observe a parte superior da caixa de diálogo Novo Projeto para selecionar o .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 seu 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 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, mantenha pressionada a tecla CTRL e selecione Microsoft.Office.Interop.Excel. Se você não vir os assemblies, talvez seja necessário instalá-los. Consulte Como instalar assemblies de interoperabilidade primários do Office.
  3. Selecione OK.

Para adicionar o necessário usando diretivas

No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Program.cs e selecione Exibir Código. Adicione as seguintes using diretivas à 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, sob a Program classe.

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

Adicione o seguinte código ao Main método para criar uma bankAccounts lista que contém 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 informações de conta para o Excel

  1. Adicione o seguinte método à Program classe 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 que você omita o argumento para esse parâmetro se quiser usar o valor padrão do parâmetro. Como você não forneceu um argumento, 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).
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 seguinte código no final do 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 seguinte código no final do DisplayInExcel. O foreach loop coloca as informações da lista de contas nas duas primeiras colunas de linhas sucessivas 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 do para ajustar as larguras das DisplayInExcel colunas para se ajustarem ao conteúdo.

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

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

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

C# converte o retornado Object em dynamic automaticamente se o assembly for referenciado pela opção de compilador EmbedInteropTypes ou, equivalentemente, se a propriedade Excel Embed Interop Types 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. É apresentada uma folha de cálculo do Excel que contém 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 vincula à planilha do Excel. Cole o método CreateIconInWordDoc, fornecido posteriormente nesta etapa, na Program classe. CreateIconInWordDoc usa argumentos nomeados e opcionais para reduzir a complexidade das chamadas de método para Add e PasteSpecial. Essas chamadas incorporam dois outros recursos que simplificam as chamadas para métodos COM que têm 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 manter os valores de argumento e descarta as variáveis quando você retorna da chamada. Em segundo lugar, você pode omitir a ref palavra-chave na lista de argumentos.

O Add método tem quatro parâmetros de referência, todos opcionais. Você pode omitir argumentos para qualquer um ou todos os parâmetros se quiser usar seus valores padrão.

O PasteSpecial método insere o conteúdo da área de transferência. O método tem sete parâmetros de referência, todos 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, não é necessário usar a palavra-chave ref ou criar variáveis para 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 seguinte instrução no final de Main.

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

Adicione a seguinte instrução no final de DisplayInExcel. O Copy método adiciona a planilha à á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. É apresentado um documento do Word que contém um ícone. Clique duas vezes no ícone para trazer a planilha para o primeiro plano.

Para definir a propriedade Embed Interop Types

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

Além disso, a programação é mais fácil porque o dynamic tipo representa os tipos necessários e retornados declarados em métodos COM. As variáveis que têm tipo dynamic não são avaliadas até o tempo de execução, o que elimina a necessidade de transmissão explícita. Para obter mais informações, consulte Usando o tipo dinâmico.

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

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

Para alterar o padrão e usar PIAs em vez de incorporar informações de tipo, expanda o nó Referências no Gerenciador de Soluções e selecione Microsoft.Office.Interop.Excel ou Microsoft.Office.Interop.Word. Se não conseguir ver a janela Propriedades , prima F4. Encontre Incorporar tipos de interoperabilidade na lista de propriedades e altere seu valor para False. Equivalentemente, você pode compilar usando a opção de compilador References em vez de EmbedInteropTypes em um prompt de comando.

Para adicionar formatação adicional à tabela

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

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

O AutoFormat método tem sete parâmetros de valor, todos os quais são opcionais. Os 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, não é necessário fornecer o nome do parâmetro. No entanto, a instrução pode ser mais fácil de entender 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 XlRangeAutoFormat enumeração.

Exemplo

O código a seguir mostra o 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; }
    }
}

Consulte também