Uso de argumentos opcionales y con nombre 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 enormemente 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 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 utilizar .NET Core y .NET 5 o versiones posteriores, incluido 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 las 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 interesa 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 los argumentos opcionales y con nombre, puede especificar valores solo para los parámetros necesarios para el proyecto.

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

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.

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. Seleccione 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 luego 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 de componente. Seleccione Aceptar.

Agregar las directivas using necesarias

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

using Word = Microsoft.Office.Interop.Word;

Mostrar texto en un documento de Word

En la clase Program en 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 los valores predeterminados. Por lo tanto, no se necesitan argumentos en la instrucción de llamada.

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    wordApp.Visible = true;
    // 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();
}

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

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

Ejecución de la aplicación

Agregue la instrucción siguiente a Principal:

DisplayInWord();

Presione CTRL+F5 para ejecutar el proyecto. Aparecerá un documento de Word con el texto especificado.

Cambiar el texto a una tabla

Use el método ConvertToTable para incluir el texto en una tabla. El método tiene 16 parámetros opcionales. IntelliSense coloca los parámetros opcionales entre corchetes, tal como se muestra en la ilustración siguiente.

Los argumentos opcionales y con nombre permiten especificar valores solo para los parámetros que quiere 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 de modo que tenga una columna y tres filas, reemplace la última línea de DisplayInWord por la instrucción siguiente y, a continuación, escriba CTRL+F5.

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

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

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

Ejemplo

En el código siguiente se 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();
            wordApp.Visible = true;
            // 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);
        }
    }
}