Como acessar objetos de interoperabilidade do Office usando recursos do Visual C# (Guia de Programação em C#)
O Visual C# 2010 apresenta novos 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 tópico, você usará os novos recursos para escrever código que cria e exibe uma planilha do Microsoft Office Excel. Em seguida, você irá escrever 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.
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 criar um novo aplicativo de console
Inicie o Visual Studio.
No menu Arquivo, aponte para Novo e clique em Projeto. A caixa de diálogo Novo Projeto é exibida.
No painel Modelos Instalados, expanda Visual C# e selecione Windows.
Observe a parte superior da caixa de diálogo Novo Projeto para se certificar de que .NET Framework 4 (ou versão posterior) esteja selecionado como uma estrutura de destino.
No painel Modelos, clique em Aplicativo de Console.
Digite um nome para o projeto no campo Nome.
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 página Assemblies , selecione Microsoft.Office.Interop.Word na lista Nome do Componente e, mantendo pressionada a tecla CTRL, selecione Microsoft.Office.Interop.Excel. 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 as diretivas using necessárias
No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Program. cs e clique em 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
Adicione o método a seguir à classe Program para configurar uma planilha do Excel.
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 a seguir, 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 praticular 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();Versões anteriores do C# exigem conversão explícita desses operadores 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();Visual C# 2010, e versões posteriores, converterá o Object retornado em dynamic automaticamente se o assembly for referenciado pela opção do compilador /link ou, de forma equivalente, se a propriedade Inserir Tipos Interop do Excel estiver definida como 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
Para ilustrar maneiras adicionais na quais Visual C# 2010, e versões posteriores, aprimora a programação do Office, o código a seguir abre um aplicativo Word e cria um ícone vinculado à planilha do Excel.
Cole o método CreateIconInWordDoc, fornecido posteriormente nesta etapa, na classe Program. CreateIconInWordDoc usa argumentos nomeados e opcionais para reduzir a complexidade das chamadas do método para Add e PasteSpecial. Essas chamadas incorporam dois novos recursos apresentados em Visual C# 2010 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. No Visual C# 2010, ou versões posteriores, você poderá omitir argumentos para alguns ou todos os parâmetros se desejar usar os valores padrão. Em Visual C# 2008 e versões anteriores, um argumento deve ser fornecido para cada parâmetro e o argumento deve ser uma variável, pois os parâmetros são parâmetros de referência.
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. No Visual C# 2010, você pode usar argumentos nomeados para esses dois e omitir os outros. Embora esses 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. Em Visual C# 2008 e versões anteriores, você deve enviar um argumento variável para cada parâmetro de referência.
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# 2010 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); }Em Visual C# 2008 ou versões anteriores da linguagem, o código a seguir mais complexo é necessário.
static void CreateIconInWordDoc2008() { var wordApp = new Word.Application(); wordApp.Visible = true; // The Add method has four parameters, all of which are optional. // In Visual C# 2008 and earlier versions, an argument has to be sent // for every parameter. Because the parameters are reference // parameters of type object, you have to create an object variable // for the arguments that represents 'no value'. object useDefaultValue = Type.Missing; wordApp.Documents.Add(ref useDefaultValue, ref useDefaultValue, ref useDefaultValue, ref useDefaultValue); // PasteSpecial has seven reference parameters, all of which are // optional. In this example, only two of the parameters require // specified values, but in Visual C# 2008 an argument must be sent // for each parameter. Because the parameters are reference parameters, // you have to contruct variables for the arguments. object link = true; object displayAsIcon = true; wordApp.Selection.PasteSpecial( ref useDefaultValue, ref link, ref useDefaultValue, ref displayAsIcon, ref useDefaultValue, ref useDefaultValue, ref useDefaultValue); }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
Melhorias adicionais 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 de programação sem PIAs, consulte Instruções passo a passo: inserindo tipos de assemblies gerenciados (C# e Visual Basic).
Além disso, a programação é mais fácil porque os tipos necessários e retornados por métodos COM podem ser representados usando o tipo dynamic, em vez de Object. 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, consulte Usando o tipo dynamic (Guia de Programação em C#).
Em Visual C# 2010, 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 pois a conversão explícita não é necessária. 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 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 /reference em vez de /link 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 possui 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, um argumento é fornecido 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 o nome do parâmetro estiver incluído, 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. Outros formatos estão listados na enumeração XIRangeAutoFormat.
Compare a instrução na etapa 1 com o código a seguir, que mostra os argumentos que são necessários em Visual C# 2008 ou versões anteriores.
// The AutoFormat method has seven optional value parameters. The // following call specifies a value for the first parameter, and uses // the default values for the other six. // Call to AutoFormat in Visual C# 2008. This code is not part of the // current solution. excelApp.get_Range("A1", "B4").AutoFormat(Excel.XlRangeAutoFormat.xlRangeAutoFormatTable3, Type.Missing, Type.Missing, Type.Missing, Type.Missing, Type.Missing, Type.Missing);
Exemplo
O código a seguir mostra um exemplo completo.
using System;
using System.Collections.Generic;
using System.Linq;
using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;
namespace OfficeProgramminWalkthruComplete
{
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 praticular 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# 2010. 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# 2010 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
Tarefas
Como usar argumentos nomeados e opcionais na programação do Office (Guia de Programação em C#)
Referência
Conceitos
Argumentos nomeados e opcionais (Guia de Programação em C#)