Procedimiento Tener acceso a objetos de interoperabilidad de Office mediante las características de Visual C# (Guía de programación de C#)How to access Office interop objects (C# Programming Guide)

C# tiene nuevas características que simplifican el acceso a objetos de la API de Office.C# has features that simplify access to Office API objects. Las nuevas características incluyen argumentos con nombre y opcionales, un nuevo tipo llamado dynamic y la capacidad de pasar argumentos a parámetros de referencia en los métodos COM como si fueran 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.

En este tema se utilizarán las nuevas características para escribir código que crea y muestra una hoja de cálculo de Microsoft Office Excel.In this topic you will use the new features to write code that creates and displays a Microsoft Office Excel worksheet. A continuación, se escribirá código para agregar un documento de Office Word que contiene un icono que está vinculado a la hoja de cálculo de Excel.You will then write code to add an Office Word document that contains an icon that is linked to the Excel worksheet.

Para completar este tutorial, es necesario tener Microsoft Office Excel 2007 y Microsoft Office Word 2007 —o una versión posterior— instalados en el equipo.To complete this walkthrough, you must have Microsoft Office Excel 2007 and Microsoft Office Word 2007, or later versions, installed on your computer.

Nota

Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obtener más información, vea Personalizar el IDE.For more information, see Personalizing the IDE.

Para crear una aplicación de consola nuevaTo create a new console application

  1. Inicie Visual Studio.Start Visual Studio.

  2. En el menú Archivo , elija Nuevoy haga clic en Proyecto.On the File menu, point to New, and then click Project. Aparecerá el cuadro de diálogo Nuevo proyecto .The New Project dialog box appears.

  3. En el panel Plantillas instaladas, expanda Visual C# y haga clic en Windows.In the Installed Templates pane, expand Visual C#, and then click Windows.

  4. En la parte superior del cuadro de diálogo Nuevo proyecto, compruebe si .NET Framework 4 (o una versión posterior) está seleccionado como una plataforma 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. En el panel Plantillas, haga clic en Aplicación de consola.In the Templates pane, click Console Application.

  6. Escriba un nombre para el proyecto en el campo Nombre.Type a name for your project in the Name field.

  7. Haga clic en Aceptar.Click OK.

    El proyecto nuevo aparece en el Explorador de soluciones.The new project appears in Solution Explorer.

Para agregar referenciasTo add references

  1. En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y luego haga clic en Agregar referencia.In Solution Explorer, right-click your project's name and then click Add Reference. Aparecerá el cuadro de diálogo Agregar referencia.The Add Reference dialog box appears.

  2. En la página de Ensamblados, seleccione Microsoft.Office.Interop.Word en la lista Nombre de componente y, después, mantenga presionada la tecla CTRL y seleccione 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. Si no ve los ensamblados, asegúrese de que están instalados y que se muestran.If you do not see the assemblies, you may need to ensure they are installed and displayed. Vea Cómo: Instalación de ensamblados de interoperabilidad primarios de Office.See How to: Install Office Primary Interop Assemblies.

  3. Haga clic en Aceptar.Click OK.

Para agregar las directivas using necesariasTo add necessary using directives

  1. En el Explorador de soluciones, haga clic con el botón derecho en el archivo Program.cs y, después, haga clic en Ver código.In Solution Explorer, right-click the Program.cs file and then click View Code.

  2. Agregue las directivas using siguientes a la parte superior del archivo 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 crear una lista de las cuentas bancariasTo create a list of bank accounts

  1. Pegue la definición de clase siguiente en Program.cs, bajo la clase 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. Agregue el código siguiente al método Main para crear una lista bankAccounts lista que contenga dos cuentas.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 un método que exporta información de cuentas a ExcelTo declare a method that exports account information to Excel

  1. Agregue el método siguiente a la clase Program para configurar una hoja de cálculo de Excel.Add the following method to the Program class to set up an Excel worksheet.

    El método Add tiene un parámetro opcional para especificar una plantilla determinada.Method Add has an optional parameter for specifying a particular template. Los parámetros opcionales introducidos en C# 4 permiten omitir el argumento para ese parámetro si se desea utilizar el valor predeterminado del 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. Dado que en el código siguiente no se envía ningún argumento, Add usa la plantilla predeterminada y crea un libro nuevo.Because no argument is sent in the following code, Add uses the default template and creates a new workbook. La instrucción equivalente en versiones anteriores de C# requiere un argumento de marcador de posición: 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. Agregue el siguiente código al final de DisplayInExcel.Add the following code at the end of DisplayInExcel. El código inserta valores en las dos primeras columnas de la primera fila de la hoja de cálculo.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. Agregue el siguiente código al final de DisplayInExcel.Add the following code at the end of DisplayInExcel. El bucle foreach coloca la información de la lista de cuentas en las dos primeras columnas de filas sucesivas de la hoja de cálculo.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. Agregue el código siguiente al final de DisplayInExcel para ajustar los anchos de columna a fin de adaptarlos al contenido.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();
    

    Las versiones anteriores de C# requieren una conversión explícita para estas operaciones, ya que ExcelApp.Columns[1] devuelve Object y AutoFit es un método Range de 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. Las siguientes líneas muestran la conversión.The following lines show the casting.

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

    C# 4, y versiones posteriores, convierte automáticamente el valor Object devuelto en dynamic si se hace referencia al ensamblado mediante la opción del compilador -link o, de forma equivalente, si la propiedad Incrustar tipos de interoperabilidad de Excel se establece en 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. El valor predeterminado de esta propiedad es true.True is the default value for this property.

Para ejecutar el proyectoTo run the project

  1. Agregue la línea siguiente al final de Main.Add the following line at the end of Main.

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

    Aparece una hoja de cálculo de Excel que contiene los datos de las dos cuentas.An Excel worksheet appears that contains the data from the two accounts.

Para agregar un documento de WordTo add a Word document

  1. Para ilustrar las formas adicionales en que C# 4, y versiones posteriores, mejoran la programación de Office, el código siguiente abre una aplicación de Word y crea un icono que se vincula a la hoja de cálculo de 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.

    Pegue el método CreateIconInWordDoc, proporcionado más adelante en este paso, en la clase Program.Paste method CreateIconInWordDoc, provided later in this step, into the Program class. CreateIconInWordDoc usa argumentos con nombre y opcionales para reducir la complejidad de las llamadas de método a Add y PasteSpecial.CreateIconInWordDoc uses named and optional arguments to reduce the complexity of the method calls to Add and PasteSpecial. Estas llamadas incorporan otras dos nuevas características introducidas en C# 4 que simplifican las llamadas a métodos COM que tienen parámetros de referencia.These calls incorporate two other new features introduced in C# 4 that simplify calls to COM methods that have reference parameters. En primer lugar, puede enviar argumentos a los parámetros de referencia como si fueran parámetros de valor.First, you can send arguments to the reference parameters as if they were value parameters. Es decir, puede enviar valores directamente, sin necesidad de crear una variable para cada parámetro de referencia.That is, you can send values directly, without creating a variable for each reference parameter. El compilador genera variables temporales para contener los valores de argumento y las descarta cuando se regresa de la llamada.The compiler generates temporary variables to hold the argument values, and discards the variables when you return from the call. En segundo lugar, se puede omitir la palabra clave ref en la lista de argumentos.Second, you can omit the ref keyword in the argument list.

    El método Add tiene cuatro parámetros de referencia, todos ellos opcionales.The Add method has four reference parameters, all of which are optional. En C# 4.0 y versiones posteriores, puede omitir los argumentos de cualquiera o de todos los parámetros si quiere usar sus valores predeterminados.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. En C# 3.0 y versiones anteriores, se debe proporcionar un argumento para cada parámetro; el argumento debe ser una variable, ya que los parámetros son parámetros de referencia.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.

    El método PasteSpecial inserta el contenido del Portapapeles.The PasteSpecial method inserts the contents of the Clipboard. El método tiene siete parámetros de referencia, todos ellos opcionales.The method has seven reference parameters, all of which are optional. El siguiente código especifica los argumentos para dos de ellos: Link, para crear un vínculo con el origen del contenido del Portapapeles, y DisplayAsIcon, para mostrar el vínculo como un icono.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. En C# 4.0 y versiones posteriores, puede usar argumentos con nombre para esos dos y omitir los demás.In C# 4.0 and later versions, you can use named arguments for those two and omit the others. Aunque se trata de parámetros de referencia, no es necesario utilizar la palabra clave ref ni crear variables para enviarlas 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. Puede enviar los valores directamente.You can send the values directly. En C# 3.0 y versiones anteriores, debe proporcionar un argumento de variable para cada parámetro de referencia.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);
    }
    

    En C# 3.0 y versiones anteriores del lenguaje, es necesario el código siguiente, que es más complejo.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. Agregue la siguiente instrucción al 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. Agregue la siguiente instrucción al final de DisplayInExcel.Add the following statement at the end of DisplayInExcel. El método Copy agrega la hoja de cálculo en el Portapapeles.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. Presione CTRL+F5.Press CTRL+F5.

    Un documento de Word aparecerá con un icono.A Word document appears that contains an icon. Haga doble clic en el icono para abrir la hoja de cálculo en primer plano.Double-click the icon to bring the worksheet to the foreground.

Para establecer la propiedad Incrustar tipos de interoperabilidadTo set the Embed Interop Types property

  1. Es posible realizar mejoras adicionales si se llama a un tipo COM que no requiere un ensamblado de interoperabilidad primario (PIA) en tiempo de ejecución.Additional enhancements are possible when you call a COM type that does not require a primary interop assembly (PIA) at run time. Si se elimina la dependencia de PIA, la versión gana en independencia y se facilita la implementación.Removing the dependency on PIAs results in version independence and easier deployment. Para obtener más información sobre las ventajas de la programación sin PIA, consulte Tutorial: Insertar los tipos de los ensamblados administrados.For more information about the advantages of programming without PIAs, see Walkthrough: Embedding Types from Managed Assemblies.

    Además, programar resulta más fácil porque los tipos requeridos y devueltos por los métodos COM se pueden representar con el tipo dynamic en 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. Las variables de tipo dynamic no se evalúan hasta el tiempo de ejecución, lo que elimina la necesidad de la conversión explícita.Variables that have type dynamic are not evaluated until run time, which eliminates the need for explicit casting. Para obtener más información, vea Uso del tipo dynamic.For more information, see Using Type dynamic.

    En C# 4, el comportamiento predeterminado es insertar información de tipos en lugar de utilizar los PIA.In C# 4, embedding type information instead of using PIAs is default behavior. Debido a ese comportamiento predeterminado, algunos de los ejemplos anteriores se simplifican dado que no es necesaria la conversión explícita.Because of that default, several of the previous examples are simplified because explicit casting is not required. Por ejemplo, la declaración de worksheet en DisplayInExcel se escribe como Excel._Worksheet workSheet = excelApp.ActiveSheet en lugar 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. Las llamadas a AutoFit en el mismo método también requerirían conversión explícita sin el valor predeterminado, porque ExcelApp.Columns[1] devuelve un Object y AutoFit es un método de 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. En el código siguiente se muestra la conversión.The following code shows the casting.

    ((Excel.Range)workSheet.Columns[1]).AutoFit();
    ((Excel.Range)workSheet.Columns[2]).AutoFit();
    
  2. Para cambiar el valor predeterminado y usar los PIA en lugar de insertar información de tipos, expanda el nodo Referencias del Explorador de soluciones y, después, seleccione Microsoft.Office.Interop.Excel o 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. Si no ve la ventana Propiedades, presione F4.If you cannot see the Properties window, press F4.

  4. Busque Incrustar tipos de interoperabilidad en la lista de propiedades y cambie su valor a False.Find Embed Interop Types in the list of properties, and change its value to False. Del mismo modo, se puede compilar mediante el uso de la opción del compilador -reference en lugar de -link en un símbolo del sistema.Equivalently, you can compile by using the -reference compiler option instead of -link at a command prompt.

Para agregar formato adicional a la tablaTo add additional formatting to the table

  1. Reemplace las dos llamadas a AutoFit en DisplayInExcel con la siguiente instrucción.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);
    

    El método AutoFormat tiene siete parámetros de valor, todos ellos opcionales.The AutoFormat method has seven value parameters, all of which are optional. Los argumentos con nombre y los argumentos opcionales permiten proporcionar argumentos para ninguno, algunos o todos ellos.Named and optional arguments enable you to provide arguments for none, some, or all of them. En la instrucción anterior, se proporciona un argumento para uno solo de los parámetros, Format.In the previous statement, an argument is supplied for only one of the parameters, Format. Puesto que Format es el primer parámetro de la lista de parámetros, no es necesario proporcionar el nombre de parámetro.Because Format is the first parameter in the parameter list, you do not have to provide the parameter name. Sin embargo, la instrucción sería más fácil de entender si se incluyese el nombre del parámetro, como se muestra en el código siguiente.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. Presione CTRL+F5 para ver el resultado.Press CTRL+F5 to see the result. Otros formatos se indican en la enumeración XlRangeAutoFormat.Other formats are listed in the XlRangeAutoFormat enumeration.

  3. Compare la instrucción del paso 1 con el siguiente código, que muestra los argumentos necesarios en C# 3.0 y versiones 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);
    

EjemploExample

En el código siguiente se muestra el ejemplo 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; }
    }
}

Vea tambiénSee also