Como: acessar objetos de interoperabilidade do Office usando funcionalidades do Visual C# (Guia de Programação em C#)How to: Access Office Interop Objects by Using Visual C# Features (C# Programming Guide)

O Visual C# tem funcionalidades que simplificam o acesso a objetos de API do Office.Visual C# has features that simplify access to Office API objects. 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.The new features include named and optional arguments, a new type called dynamic, and the ability to pass arguments to reference parameters in COM methods as if they were value parameters.

Neste tópico, você usará os novos recursos para escrever código que cria e exibe uma planilha do Microsoft Office Excel.In this topic you will use the new features to write code that creates and displays a Microsoft Office Excel worksheet. Em seguida, você irá escrever código para adicionar um documento do Office Word que contenha um ícone que esteja vinculado à planilha do Excel.You will then write code to add an Office Word document that contains an icon that is linked to the Excel worksheet.

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.To complete this walkthrough, you must have Microsoft Office Excel 2007 and Microsoft Office Word 2007, or later versions, installed on your computer.

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.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obter mais informações, consulte Personalizando o IDE.For more information, see Personalizing the IDE.

Para criar um novo aplicativo de consoleTo create a new console application

  1. Inicie o Visual Studio.Start Visual Studio.

  2. No menu Arquivo, aponte para Novo e clique em Projeto.On the File menu, point to New, and then click Project. A caixa de diálogo Novo Projeto é exibida.The New Project dialog box appears.

  3. No painel Modelos Instalados, expanda Visual C# e, em seguida, selecione Windows.In the Installed Templates pane, expand Visual C#, and then click Windows.

  4. Observe a parte superior da caixa de diálogo Novo Projeto para verificar se .NET Framework 4 (ou versão posterior) está selecionado como uma estrutura de destino.Look at the top of the New Project dialog box to make sure that .NET Framework 4 (or later version) is selected as a target framework.

  5. No painel Modelos, clique em Aplicativo de Console.In the Templates pane, click Console Application.

  6. Digite um nome para o projeto no campo Nome.Type a name for your project in the Name field.

  7. Clique em OK.Click OK.

    O novo projeto aparece no Gerenciador de Soluções.The new project appears in Solution Explorer.

Para adicionar referênciasTo add references

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e, em seguida, clique em Adicionar Referência.In Solution Explorer, right-click your project's name and then click Add Reference. A caixa de diálogo Adicionar Referência é exibida.The Add Reference dialog box appears.

  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.On the Assemblies page, select Microsoft.Office.Interop.Word in the Component Name list, and then hold down the CTRL key and select Microsoft.Office.Interop.Excel. Se você não vir os assemblies, talvez seja necessário verificar se eles estão instalados e exibidos (confira Como Instalar assemblies de interoperabilidade primários do Office)If you do not see the assemblies, you may need to ensure they are installed and displayed (see How to: Install Office Primary Interop Assemblies)

  3. Clique em OK.Click OK.

Para adicionar as diretivas using necessáriasTo add necessary using directives

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Program.cs e, em seguida, clique em Exibir Código.In Solution Explorer, right-click the Program.cs file and then click View Code.

  2. Adicione as seguintes diretivas using na parte superior do arquivo de código.Add the following using directives to the top of the code file.

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

Para criar uma lista de contas bancáriasTo create a list of bank accounts

  1. Cole a seguinte definição de classe em Program.cs, na classe Program.Paste the following class definition into Program.cs, under the Program class.

    public class Account
    {
        public int ID { get; set; }
        public double Balance { get; set; }
    }
    
  2. Adicione o seguinte código ao método Main para criar uma lista bankAccounts que contenha duas contas.Add the following code to the Main method to create a bankAccounts list that contains two accounts.

    // 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 ExcelTo declare a method that exports account information to Excel

  1. Adicione o método a seguir à classe Program para configurar uma planilha do Excel.Add the following method to the Program class to set up an Excel worksheet.

    O método Add tem um parâmetro opcional para especificar um modelo específico.Method Add has an optional parameter for specifying a particular template. Os parâmetros opcionais, novos no C# 4, permitem omitir o argumento para esse parâmetro se você quiser usar o valor padrão do parâmetro.Optional parameters, new in C# 4, enable you to omit the argument for that parameter if you want to use the parameter's default value. Como nenhum argumento é enviado no código a seguir, Add usa o modelo padrão e cria uma nova pasta de trabalho.Because no argument is sent in the following code, Add uses the default template and creates a new workbook. A instrução equivalente em versões anteriores do C# requer um argumento de espaço reservado: ExcelApp.Workbooks.Add(Type.Missing).The equivalent statement in earlier versions of C# requires a placeholder argument: 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;
    }
    
  2. Adicione o código a seguir no final de DisplayInExcel.Add the following code at the end of DisplayInExcel. O código insere valores nas duas primeiras colunas da primeira linha da planilha.The code inserts values into the first two columns of the first row of the worksheet.

    // Establish column headings in cells A1 and B1.
    workSheet.Cells[1, "A"] = "ID Number";
    workSheet.Cells[1, "B"] = "Current Balance";
    
  3. Adicione o código a seguir no final de DisplayInExcel.Add the following code at the end of DisplayInExcel. O loop foreach coloca as informações da lista de contas nas duas primeiras colunas de sucessivas linhas da planilha.The foreach loop puts the information from the list of accounts into the first two columns of successive rows of the worksheet.

    
    var row = 1;
    foreach (var acct in accounts)
    {
        row++;
        workSheet.Cells[row, "A"] = acct.ID;
        workSheet.Cells[row, "B"] = acct.Balance;
    }
    
  4. Adicione o seguinte código no final de DisplayInExcel para ajustar as larguras das colunas para adequar o conteúdo.Add the following code at the end of DisplayInExcel to adjust the column widths to fit the content.

    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.Earlier versions of C# require explicit casting for these operations because ExcelApp.Columns[1] returns an Object, and AutoFit is an Excel Range method. As linhas a seguir mostram a conversão.The following lines show the casting.

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

    O C# 4, e versões posteriores, converterão o Object retornado em dynamic automaticamente se o assembly for referenciado pela opção do compilador /link ou, de forma equivalente, se a propriedade Embed Interop Types do Excel estiver definida como true.C# 4, and later versions, converts the returned Object to dynamic automatically if the assembly is referenced by the /link compiler option or, equivalently, if the Excel Embed Interop Types property is set to true. True é o valor padrão para essa propriedade.True is the default value for this property.

Para executar o projetoTo run the project

  1. Adicione a seguinte linha no final de Main.Add the following line at the end of Main.

    // Display the list in an Excel spreadsheet.
    DisplayInExcel(bankAccounts);
    
  2. Pressione CTRL+F5.Press CTRL+F5.

    Uma planilha do Excel é exibida contendo os dados das duas contas.An Excel worksheet appears that contains the data from the two accounts.

Para adicionar um documento do WordTo add a Word document

  1. Para ilustrar maneiras adicionais pelas quais o C# 4 e versões posteriores aprimoram a programação do Office, o código a seguir abre um aplicativo Word e cria um ícone vinculado à planilha do Excel.To illustrate additional ways in which C# 4, and later versions, enhances Office programming, the following code opens a Word application and creates an icon that links to the Excel worksheet.

    Cole o método CreateIconInWordDoc, fornecido posteriormente nesta etapa, na classe Program.Paste method CreateIconInWordDoc, provided later in this step, into the Program class. O CreateIconInWordDoc usa argumentos nomeados e opcionais para reduzir a complexidade das chamadas de método a Add e PasteSpecial.CreateIconInWordDoc uses named and optional arguments to reduce the complexity of the method calls to Add and PasteSpecial. Essas chamadas incorporam dois novos recursos apresentados no C# 4 que simplificam as chamadas aos métodos COM que possuem parâmetros de referência.These calls incorporate two other new features introduced in C# 4 that simplify calls to COM methods that have reference parameters. Primeiro, você pode enviar argumentos para os parâmetros de referência como se fossem parâmetros de valor.First, you can send arguments to the reference parameters as if they were value parameters. Ou seja, você pode enviar valores diretamente, sem criar uma variável para cada parâmetro de referência.That is, you can send values directly, without creating a variable for each reference parameter. O compilador gera variáveis temporárias para conter os valores de argumento e descarta as variáveis quando você retornar da chamada.The compiler generates temporary variables to hold the argument values, and discards the variables when you return from the call. Em segundo lugar, você pode omitir a palavra-chave ref na lista de argumentos.Second, you can omit the ref keyword in the argument list.

    O método Add tem quatro parâmetros de referência que são opcionais.The Add method has four reference parameters, all of which are optional. No C# 4.0 e versões posteriores, você poderá omitir argumentos para alguns ou todos os parâmetros se desejar usar os valores padrão.In C# 4.0 and later versions, you can omit arguments for any or all of the parameters if you want to use their default values. No C# 3.0 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.In C# 3.0 and earlier versions, an argument must be provided for each parameter, and the argument must be a variable because the parameters are reference parameters.

    O método PasteSpecial insere o conteúdo da área de transferência.The PasteSpecial method inserts the contents of the Clipboard. O método tem sete parâmetros de referência que são opcionais.The method has seven reference parameters, all of which are optional. 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.The following code specifies arguments for two of them: Link, to create a link to the source of the Clipboard contents, and DisplayAsIcon, to display the link as an icon. No C# 4.0 e versões posteriores, você pode usar argumentos nomeados para esses dois e omitir os outros.In C# 4.0 and later versions, you can use named arguments for those two and omit the others. 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.Although these are reference parameters, you do not have to use the ref keyword, or to create variables to send in as arguments. Você pode enviar os valores diretamente.You can send the values directly. No C# 3.0 e versões anteriores, você deve fornecer um argumento variável para cada parâmetro de referência.In C# 3.0 and earlier versions, you must supply a variable argument for each reference parameter.

    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);
    }
    

    No C# 3.0 e versões anteriores da linguagem, o código a seguir mais complexo é necessário.In C# 3.0 and earlier versions of the language, the following more complex code is required.

    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);
    }
    
  2. Adicione a instrução a seguir no final de Main.Add the following statement at the end of Main.

    // Create a Word document that contains an icon that links to
    // the spreadsheet.
    CreateIconInWordDoc();
    
  3. Adicione a instrução a seguir no final de DisplayInExcel.Add the following statement at the end of DisplayInExcel. O método Copy adiciona a planilha na área de transferência.The Copy method adds the worksheet to the Clipboard.

    // 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();
    
  4. Pressione CTRL+F5.Press CTRL+F5.

    Um documento do Word é exibido contendo um ícone.A Word document appears that contains an icon. Clique duas vezes no ícone para colocar a planilha no primeiro plano.Double-click the icon to bring the worksheet to the foreground.

Para definir a propriedade Inserir Tipos InteropTo set the Embed Interop Types property

  1. 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.Additional enhancements are possible when you call a COM type that does not require a primary interop assembly (PIA) at run time. A remoção da dependência nos PIAs resulta na independência de versão e em uma implantação mais fácil.Removing the dependency on PIAs results in version independence and easier deployment. Para saber mais sobre as vantagens de programação sem PIAs, confira Instruções passo a passo: inserir tipos de assemblies gerenciados.For more information about the advantages of programming without PIAs, see Walkthrough: Embedding Types from Managed Assemblies.

    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.In addition, programming is easier because the types that are required and returned by COM methods can be represented by using the type dynamic instead of 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.Variables that have type dynamic are not evaluated until run time, which eliminates the need for explicit casting. Para obter mais informações, veja Usando o tipo dynamic.For more information, see Using Type dynamic.

    No C# 4, a inserção de informações de tipo, em vez do uso de PIAs, é o comportamento padrão.In C# 4, embedding type information instead of using PIAs is default behavior. Devido a esse padrão, vários dos exemplos anteriores são simplificados pois a conversão explícita não é necessária.Because of that default, several of the previous examples are simplified because explicit casting is not required. 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.For example, the declaration of worksheet in DisplayInExcel is written as Excel._Worksheet workSheet = excelApp.ActiveSheet rather than 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.The calls to AutoFit in the same method also would require explicit casting without the default, because ExcelApp.Columns[1] returns an Object, and AutoFit is an Excel method. O código a seguir mostra a conversão.The following code shows the casting.

    ((Excel.Range)workSheet.Columns[1]).AutoFit();
    ((Excel.Range)workSheet.Columns[2]).AutoFit();
    
  2. 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.To change the default and use PIAs instead of embedding type information, expand the References node in Solution Explorer and then select Microsoft.Office.Interop.Excel or Microsoft.Office.Interop.Word.

  3. Se você não conseguir ver a janela Propriedades, pressione F4.If you cannot see the Properties window, press F4.

  4. Localize Inserir Tipos Interop na lista de propriedades e altere seu valor para False.Find Embed Interop Types in the list of properties, and change its value to False. De maneira equivalente, você pode compilar usando a opção do compilador /reference em vez de /link em um prompt de comando.Equivalently, you can compile by using the /reference compiler option instead of /link at a command prompt.

Para adicionar formatação adicional à tabelaTo add additional formatting to the table

  1. Substitua as duas chamadas para AutoFit em DisplayInExcel pela instrução a seguir.Replace the two calls to AutoFit in DisplayInExcel with the following statement.

    // 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.The AutoFormat method has seven value parameters, all of which are optional. Argumentos nomeados e opcionais permitem que você forneça argumentos para nenhum, alguns ou todos eles.Named and optional arguments enable you to provide arguments for none, some, or all of them. Na instrução anterior, um argumento é fornecido para apenas um dos parâmetros, Format.In the previous statement, an argument is supplied for only one of the parameters, Format. Como Format é o primeiro parâmetro na lista de parâmetros, você não precisará fornecer o nome do parâmetro.Because Format is the first parameter in the parameter list, you do not have to provide the parameter name. 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.However, the statement might be easier to understand if the parameter name is included, as is shown in the following code.

    // Call to AutoFormat in Visual C# 2010.
    workSheet.Range["A1", "B3"].AutoFormat(Format:
        Excel.XlRangeAutoFormat.xlRangeAutoFormatClassic2);
    
  2. Pressione CTRL + F5 para ver o resultado.Press CTRL+F5 to see the result. Outros formatos estão listados na enumeração XlRangeAutoFormat.Other formats are listed in the XlRangeAutoFormat enumeration.

  3. Compare a instrução na etapa 1 com o código a seguir, que mostra os argumentos que são necessários no C# 3.0 ou versões anteriores.Compare the statement in step 1 with the following code, which shows the arguments that are required in C# 3.0 and earlier versions.

    // 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);
    

ExemploExample

O código a seguir mostra um exemplo completo.The following code shows the complete example.

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#. 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émSee also