Cómo usar argumentos con nombre y opcionales en la programación de Office

Los argumentos con nombre y los argumentos opcionales mejoran la comodidad, la flexibilidad y la legibilidad en la programación de C#. Además, estas características facilitan considerablemente el acceso a interfaces COM, como las API de automatización de Microsoft Office.

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+, las versiones más recientes de .NET. Esto se debe a que .NET Core/.NET 5+ no puede trabajar junto con .NET Framework en el mismo proceso y puede provocar errores de carga de complementos. Puede seguir usando .NET Framework para escribir complementos VSTO y COM para Office. Microsoft no actualizará VSTO ni la plataforma de complemento COM para usar .NET Core o .NET 5 o versiones posteriores. Puede aprovechar .NET Core y .NET 5+, incluida ASP.NET Core, para crear el lado servidor de complementos web de Office.

En el ejemplo siguiente, el método ConvertToTable tiene 16 parámetros que representan características de una tabla, como el número de columnas y filas, el formato, los bordes, las fuentes y los colores. Los 16 parámetros son opcionales, ya que la mayoría de las veces no desea especificar valores concretos para todos ellos. Sin embargo, sin argumentos con nombre ni opcionales, debe proporcionar un valor o un valor de marcador de posición. Con argumentos con nombre y opcionales, solo se especifican valores para los parámetros necesarios para el proyecto.

Debe tener Microsoft Office Word instalado en el equipo para completar estos procedimientos.

Nota:

El equipo puede mostrar nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las instrucciones siguientes. La edición de Visual Studio que tiene y la configuración que usa determinan estos elementos. Para obtener más información, consulte Personalizando el IDE.

Creación de una nueva aplicación de consola

Inicie Visual Studio. En el menú Archivo , seleccione Nuevoy haga clic en Proyecto. En el panel Categorías de plantillas , expanda C#y, a continuación, seleccione Windows. En la parte superior del panel Plantillas, asegúrese de que .NET Framework 4 aparece en el cuadro Plataforma de destino. En el panel Plantillas , seleccione Aplicación de consola. Escriba un nombre para el proyecto en el campo Nombre . Selecciona Aceptar. El proyecto nuevo aparece en el Explorador de soluciones.

Agregar una referencia

En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y seleccione Agregar referencia. Aparecerá el cuadro de diálogo Agregar referencia. En la página .NET , seleccione Microsoft.Office.Interop.Word en la lista Nombre del componente . Selecciona Aceptar.

Agregar las directivas using necesarias

En el Explorador de soluciones, haga clic con el botón derecho en el archivo Program.cs y seleccione Ver código. Agregue las siguientes using directivas a la parte superior del archivo de código:

using Word = Microsoft.Office.Interop.Word;

Mostrar texto en un documento de Word

En la Program clase de Program.cs, agregue el método siguiente para crear una aplicación de Word y un documento de Word. El método Add tiene cuatro parámetros opcionales. En este ejemplo se usan sus valores predeterminados. Por lo tanto, no se necesitan argumentos en la instrucción de llamada.

Nota:

Para evitar problemas de subprocesos y tiempos COM que pueden provocar excepciones como "El filtro de mensajes indica que la aplicación está ocupada" (HRESULT 0x8001010A), la aplicación word se mantiene invisible durante las operaciones y solo se hace visible una vez completadas todas las operaciones.

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    // Keep Word invisible during operations to avoid COM threading issues
    wordApp.Visible = false;
    // docs is a collection of all the Document objects currently
    // open in Word.
    Word.Documents docs = wordApp.Documents;

    // Add a document to the collection and name it doc.
    Word.Document doc = docs.Add();
    
    // Make Word visible after operations are complete
    wordApp.Visible = true;
}

Agregue el código siguiente al final del método para definir dónde mostrar texto en el documento y qué texto se va a mostrar:

// Define a range, a contiguous area in the document, by specifying
// a starting and ending character position. Currently, the document
// is empty.
Word.Range range = doc.Range(0, 0);

// Use the InsertAfter method to insert a string at the end of the
// current range.
range.InsertAfter("Testing, testing, testing. . .");

Ejecutar la aplicación

Agregue la siguiente declaración a Main:

DisplayInWord();

Presione CTRL+F5 para ejecutar el proyecto. Aparece un documento de Word que contiene el texto especificado.

Cambiar el texto a una tabla

Use el ConvertToTable método para incluir el texto en una tabla. El método tiene 16 parámetros opcionales. IntelliSense incluye parámetros opcionales entre corchetes, como se muestra en la ilustración siguiente. Los valores predeterminados de Type.Missing son el nombre simple de System.Type.Missing.

Los argumentos con nombre y opcionales permiten especificar valores solo para los parámetros que desea cambiar. Agregue el código siguiente al final del método DisplayInWord para crear una tabla. El argumento especifica que las comas de la cadena de texto de range separan las celdas de la tabla.

// Convert to a simple table. The table will have a single row with
// three columns.
range.ConvertToTable(Separator: ",");

Presione CTRL+F5 para ejecutar el proyecto.

Experimentar con otros parámetros

Cambie la tabla para que tenga una columna y tres filas, reemplace la última línea de DisplayInWord por la instrucción siguiente y escriba CTRL+F5.

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

Especifique un formato predefinido para la tabla, reemplace la última línea de DisplayInWord por la siguiente instrucción y escriba CTRL+F5. El formato puede ser cualquiera de las constantes WdTableFormat .

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
    Format: Word.WdTableFormat.wdTableFormatElegant);

Ejemplo

El código siguiente incluye el ejemplo completo:

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

namespace OfficeHowTo
{
    class WordProgram
    {
        static void Main(string[] args)
        {
            DisplayInWord();
        }

        static void DisplayInWord()
        {
            var wordApp = new Word.Application();
            // Keep Word invisible during operations to avoid COM threading issues
            wordApp.Visible = false;
            // docs is a collection of all the Document objects currently
            // open in Word.
            Word.Documents docs = wordApp.Documents;

            // Add a document to the collection and name it doc.
            Word.Document doc = docs.Add();

            // Define a range, a contiguous area in the document, by specifying
            // a starting and ending character position. Currently, the document
            // is empty.
            Word.Range range = doc.Range(0, 0);

            // Use the InsertAfter method to insert a string at the end of the
            // current range.
            range.InsertAfter("Testing, testing, testing. . .");

            // You can comment out any or all of the following statements to
            // see the effect of each one in the Word document.

            // Next, use the ConvertToTable method to put the text into a table.
            // The method has 16 optional parameters. You only have to specify
            // values for those you want to change.

            // Convert to a simple table. The table will have a single row with
            // three columns.
            range.ConvertToTable(Separator: ",");

            // Change to a single column with three rows..
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

            // Format the table.
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
                Format: Word.WdTableFormat.wdTableFormatElegant);

            // Make Word visible after all operations are complete
            wordApp.Visible = true;
        }
    }
}