Tutorial: Programación de Office en C#

Artículo
03/09/2023

C# ofrece características que mejoran la programación de Microsoft Office. Las características útiles de C# incluyen argumentos opcionales y con nombre, y devuelven valores de tipo dynamic. En la programación COM, puede omitir la palabra clave ref y obtener acceso a las propiedades indexadas.

En ambos lenguajes se puede insertar información de tipo, lo que permite la implementación de ensamblados que interactúan con componentes COM sin necesidad de implementar ensamblados de interoperabilidad primarios (PIA) en el equipo del usuario. Para obtener más información, vea Tutorial: Insertar los tipos de los ensamblados administrados.

En este tutorial se muestran estas características en el contexto de la programación de Office, pero muchas de ellas también son útiles en la programación general. En el tutorial, usa una aplicación complemento de Excel para crear un libro de Excel. Después, crea un documento de Word que contiene un vínculo al libro. Por último, ve cómo habilitar y deshabilitar la dependencia de un PIA.

Importante

VSTO (Visual Studio Tools para Office) se basa en .NET Framework. Los complementos COM también se pueden escribir con .NET Framework. No se pueden crear complementos de Office con .NET Core y .NET 5 o versiones posteriores, las últimas versiones de .NET. Esto se debe a que .NET Core/.NET 5 o versiones posteriores no pueden funcionar junto con .NET Framework en el mismo proceso, y se pueden provocar errores de carga de complementos. Puede seguir usando .NET Framework a fin de escribir complementos VSTO y COM para Office. Microsoft no actualizará VSTO ni la plataforma de complementos COM para usar .NET Core, o .NET 5 o versiones posteriores. Puede aprovechar .NET Core y .NET 5 o versiones posteriores, incluido ASP.NET Core, para crear el lado servidor de complementos web de Office.

Requisitos previos

Debe tener Microsoft Office Excel y Microsoft Office Word instalados en su equipo para completar este tutorial.

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. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para obtener más información, vea Personalizar el IDE.

Configuración de una aplicación complemento de Excel

Inicie Visual Studio.
En el menú Archivo , seleccione Nuevoy haga clic en Proyecto.
En el panel Plantillas instaladas, expanda C#, Office y, después, seleccione el año de versión del producto de Office.
En el panel Plantillas, seleccione Excel <versión > Complemento.
En la parte superior del panel Plantillas, asegúrese de que .NET Framework 4 o una versión posterior aparece en el cuadro Plataforma de destino.
Si quiere, escriba un nombre para el proyecto en el cuadro Nombre.
Seleccione Aceptar.
El proyecto nuevo aparece en el Explorador de soluciones.

Agregar referencias

En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y luego seleccione Agregar referencia. Aparecerá el cuadro de diálogo Agregar referencia.
En la pestaña Ensamblados, seleccione Microsoft.Office.Interop.Excel, versión <version>.0.0.0 (para obtener una clave de los números de versión de productos de Office, vea Versiones de Microsoft), en la lista Nombre de componente y, después, mantenga presionada la tecla CTRL y seleccione Microsoft.Office.Interop.Word, version <version>.0.0.0. Si no ve los ensamblados, es posible que tenga que instalarlos (vea Procedimientos para instalar ensamblados de interoperabilidad primarios de Office).
Seleccione Aceptar.

Incorporación de las instrucciones Imports necesarias o las directivas using

En el Explorador de soluciones, haga clic con el botón derecho en el archivo ThisAddIn.cs y luego seleccione Ver código. Agregue las directivas using (C#) siguientes en la parte superior del archivo de código si no están ya presentes.

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

Creación de una lista de cuentas bancarias

En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto, seleccione Agregar y luego Clase. Asigne un nombre a la clase Account.cs. Seleccione Agregar. Reemplace la definición de la clase Account por el código siguiente. Las definiciones de clase usan propiedades implementadas automáticamente.

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

Para crear una lista bankAccounts que contenga dos cuentas, agregue el código siguiente al método ThisAddIn_Startup en ThisAddIn.cs. Las declaraciones de lista usan inicializadores de colección.

var bankAccounts = new List<Account>
{
    new Account
    {
        ID = 345,
        Balance = 541.27
    },
    new Account
    {
        ID = 123,
        Balance = -127.44
    }
};

Exportación de datos a Excel

En el mismo archivo, agregue el siguiente método a la clase ThisAddIn. El método configura un libro de Excel, a donde exporta los datos.

void DisplayInExcel(IEnumerable<Account> accounts,
           Action<Account, Excel.Range> DisplayFunc)
{
    var excelApp = this.Application;
    // Add a new Excel workbook.
    excelApp.Workbooks.Add();
    excelApp.Visible = true;
    excelApp.Range["A1"].Value = "ID";
    excelApp.Range["B1"].Value = "Balance";
    excelApp.Range["A2"].Select();

    foreach (var ac in accounts)
    {
        DisplayFunc(ac, excelApp.ActiveCell);
        excelApp.ActiveCell.Offset[1, 0].Select();
    }
    // Copy the results to the Clipboard.
    excelApp.Range["A1:B3"].Copy();
}

El método Add tiene un parámetro opcional para especificar una plantilla determinada. Los parámetros opcionales permiten omitir el argumento de ese parámetro si se desea utilizar el valor predeterminado del parámetro. Como el ejemplo anterior no tiene argumentos, Add usa la plantilla predeterminada y crea un libro. La instrucción equivalente en versiones anteriores de C# requiere un argumento de marcador de posición: excelApp.Workbooks.Add(Type.Missing). Para obtener más información, vea Argumentos opcionales y con nombre.
Las propiedades Range y Offset del objeto Range usan la característica de propiedades indizadas. Esta característica permite utilizar estas propiedades de los tipos COM mediante la siguiente sintaxis típica de C#. Las propiedades indizadas también permiten utilizar la propiedad Value del objeto Range, eliminando la necesidad de utilizar la propiedad Value2. La propiedad Value está indizada, pero el índice es opcional. Los argumentos opcionales y las propiedades indizadas funcionan conjuntamente en el ejemplo siguiente.

// Visual C# 2010 provides indexed properties for COM programming.
excelApp.Range["A1"].Value = "ID";
excelApp.ActiveCell.Offset[1, 0].Select();

No se pueden crear propiedades indexadas propias. La característica solo admite el uso de las propiedades indizadas existentes.

Agregue el código siguiente al final de DisplayInExcel para ajustar los anchos de columna a fin de adaptarlos al contenido.

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

Estas adiciones muestran otra característica de C#: el tratamiento de valores Object devueltos por hosts COM, como Office, como si tuvieran un tipo dynamic. Los objetos COM se tratan como dynamic de forma automática cuando Incrustar tipos de interoperabilidad tiene su valor predeterminado, True, o equivalentemente, al hacer referencia al ensamblado con la opción del compilador EmbedInteropTypes. Para obtener más información sobre cómo insertar tipos de interoperabilidad, consulte los procedimientos "Búsqueda de la referencia a un PIA" y "Restauración de la dependencia de un PIA" más adelante en este artículo. Para obtener más información sobre dynamic, vea dynamic o Uso de tipo dinámico.

Invocación de DisplayInExcel

Agregue el código siguiente al final del método ThisAddIn_StartUp. La llamada a DisplayInExcel contiene dos argumentos. El primer argumento es el nombre de la lista de cuentas procesadas. El segundo argumento es una expresión lambda de varias líneas que define cómo procesar los datos. Los valores ID y balance de cada cuenta se muestran en las celdas adyacentes y la fila se muestra en rojo si el saldo es inferior a cero. Para obtener más información, vea Expresiones lambda.

DisplayInExcel(bankAccounts, (account, cell) =>
// This multiline lambda expression sets custom processing rules
// for the bankAccounts.
{
    cell.Value = account.ID;
    cell.Offset[0, 1].Value = account.Balance;
    if (account.Balance < 0)
    {
        cell.Interior.Color = 255;
        cell.Offset[0, 1].Interior.Color = 255;
    }
});

Presione F5 para ejecutar el programa. Aparece una hoja de cálculo de Excel que contiene los datos de las cuentas.

Incorporación de un documento de Word

Agregue el código siguiente al final del método ThisAddIn_StartUp para crear un documento de Word que contenga un vínculo al libro de Excel.

var wordApp = new Word.Application();
wordApp.Visible = true;
wordApp.Documents.Add();
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);

En este código se muestran varias de las características de C#: la capacidad de omitir la palabra clave ref en programación COM, argumentos con nombre y argumentos opcionales. El método PasteSpecial tiene siete parámetros y todos ellos son parámetros de referencia opcionales. Los argumentos opcionales y con nombre permiten designar los parámetros a los que se quiere tener acceso por nombre, y enviar argumentos únicamente a esos parámetros. En este ejemplo, los argumentos indican la creación de un vínculo al libro en el Portapapeles (parámetro Link) y que el vínculo en el documento de Word se muestra como un icono (parámetro DisplayAsIcon). C# también le permite omitir la palabra clave ref para estos argumentos.

Ejecución de la aplicación

Presione F5 para ejecutar la aplicación. Excel se abre y muestra una tabla que contiene la información de las dos cuentas de bankAccounts. Entonces aparece un documento de Word que contiene un vínculo a la tabla de Excel.

Limpieza del proyecto completado

En Visual Studio, seleccione Limpiar solución en el menú Compilación. De lo contrario, el complemento se ejecutará cada vez que abra Excel en el equipo.

Búsqueda de la referencia de PIA

Vuelva a ejecutar la aplicación, pero no seleccione Limpiar solución.
Seleccione Iniciar. Busque Microsoft Visual Studio <versión> y abra un símbolo del sistema del desarrollador.
Escriba ildasm en la ventana Símbolo del sistema para desarrolladores de Visual Studio y, luego, presione ENTRAR. Aparecerá la ventana IL DASM.
En el menú Archivo de la ventana de IL DASM, seleccione Archivo>Abrir. Haga doble clic en Visual Studio <versión> y, después, haga doble clic en Proyectos. Abra la carpeta de su proyecto y, en la carpeta bin/Debug, busque su_proyecto.dll. Haga doble clic en su_proyecto.dll. Una nueva ventana muestra los atributos del proyecto, además de las referencias a otros módulos y ensamblados. El ensamblado incluye los espacios de nombres Microsoft.Office.Interop.Excel y Microsoft.Office.Interop.Word. De manera predeterminada en Visual Studio, el compilador importa los tipos necesarios desde un PIA con referencia a su ensamblado. Para obtener más información, vea Cómo: Consulta del contenido de un ensamblado.
Haga doble clic en el icono MANIFIESTO. Aparecerá una ventana con una lista de ensamblados que contienen los elementos a los que hace referencia el proyecto. Microsoft.Office.Interop.Excel y Microsoft.Office.Interop.Word no están en la lista. Dado que importó los tipos que necesita el proyecto en el ensamblado, no es necesario instalar referencias a un PIA. La importación de los tipos en el ensamblado facilita la implementación. Los PIA no tienen que estar presentes en el equipo del usuario. Una aplicación no requiere la implementación de una versión específica de un PIA. Las aplicaciones pueden funcionar con varias versiones de Office, siempre que existan las API necesarias en todas las versiones. Dado que la implementación de los PIA ya no es necesaria, puede crear una aplicación en escenarios avanzados que funcione con varias versiones de Office, incluidas versiones anteriores. El código no puede usar ninguna API que no esté disponible en la versión de Office con la que trabaja. No siempre está claro si una API determinada estaba disponible en una versión anterior. No se recomienda trabajar con versiones anteriores de Office.
Cierre la ventana del manifiesto y la del ensamblado.

Restauración de la dependencia de PIA

En el Explorador de soluciones, seleccione el botón Mostrar todos los archivos. Expanda la carpeta Referencias y seleccione Microsoft.Office.Interop.Excel. Pulse F4 para abrir la ventana Propiedades.
En la ventana Propiedades, cambie la propiedad Incrustar tipos de interoperabilidad de True a False.
Repita los pasos 1 y 2 de este procedimiento para Microsoft.Office.Interop.Word.
En C#, marque como comentario las dos llamadas a Autofit al final del método DisplayInExcel.
Presione F5 para comprobar que el proyecto sigue ejecutándose correctamente.
Repita los pasos 1 a 3 del procedimiento anterior para abrir la ventana de ensamblado. Observe que Microsoft.Office.Interop.Word y Microsoft.Office.Interop.Excel ya no están en la lista de ensamblados insertados.
Haga doble clic en el icono MANIFIESTO y desplácese por la lista de ensamblados de referencia. Tanto Microsoft.Office.Interop.Word como Microsoft.Office.Interop.Excel están en la lista. Dado que la aplicación hace referencia a los PIA de Excel y Word y la propiedad Incrustar tipos de interoperabilidad se establece en False, ambos ensamblados deben existir en el equipo del usuario final.
En Visual Studio, seleccione Limpiar solución en el menú Compilación para limpiar el proyecto completado.