Cómo: Usar argumentos opcionales y con nombre en la programación de Office (Guía de programación de C#)

Artículo
08/10/2011

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

En el ejemplo siguiente, el método ConvertToTable tiene dieciséis parámetros que representan diversas características de una tabla, como el número de columnas y filas, el formato, los bordes, las fuentes y los colores. Los dieciséis parámetros son opcionales, porque la mayoría de las veces no se desea especificar valores determinados para todos ellos. Sin embargo, sin los argumentos opcionales y con nombre, debe proporcionarse un valor o un valor de marcador de posición para cada parámetro. Con los argumentos opcionales y con nombre, solamente se deben especificar valores para los parámetros necesarios para el proyecto.

Para poder completar estos procedimientos, debe tener instalado Microsoft Office Word en el equipo.

Nota

Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio incluidos en las instrucciones siguientes. 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 Valores de configuración de Visual Studio.

Para crear una aplicación de consola

Inicie Visual Studio.
En el menú Archivo, elija Nuevo y haga clic en Proyecto.
En el recuadro Categorías de plantillas, expanda **Visual C#**y, a continuación, haga clic en Ventanas.
Compruebe la parte superior del recuadro Plantillas para asegurarse de que .NET Framework 4 aparece en el cuadro Versión de .NET Framework de destino.
En el panel Plantillas, haga clic en Aplicación de consola.
Escriba un nombre para el proyecto en el campo Nombre.
Haga clic en Aceptar.

El nuevo proyecto aparecerá en el Explorador de soluciones.

Para agregar una referencia

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

Para agregar las directivas using necesarias

En el Explorador de soluciones, haga clic con el botón secundario en el archivo Program.cs y, a continuación, haga clic en Ver código.
Agregue las siguientes directivas using al principio del archivo de código.
```
using Word = Microsoft.Office.Interop.Word;
```

Para mostrar texto en un documento de Word

En la clase Program de Program.cs, agregue el siguiente método para crear una aplicación 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 requiere ningún argumento 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 siguiente código al final del método para definir dónde se va a mostrar el 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. . .");

Para ejecutar la aplicación

Agregue la siguiente instrucción a Main.
```
DisplayInWord();
```
Presione CTRL+F5 para ejecutar el proyecto. Aparece un documento de Word que contiene el texto especificado.

Para cambiar el texto a modo de tabla

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

Parámetros de ConvertToTable

Los parámetros opcionales y con nombre permiten especificar valores únicamente para los parámetros que se desean cambiar. Agregue el código siguiente al final del método DisplayInWord para crear una tabla simple. El argumento especifica que las comas en 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: ",");
```
En las versiones anteriores de C#, la llamada a ConvertToTable requiere un argumento de referencia para cada parámetro, tal y como se muestra en el siguiente código.
```
// Call to ConvertToTable in Visual C# 2008 or earlier. This code
// is not part of the solution.
var missing = Type.Missing;
object separator = ",";
range.ConvertToTable(ref separator, ref missing, ref missing,
    ref missing, ref missing, ref missing, ref missing,
    ref missing, ref missing, ref missing, ref missing,
    ref missing, ref missing, ref missing, ref missing,
    ref missing);
```
Presione CTRL+F5 para ejecutar el proyecto.

Para experimentar con otros parámetros

Para cambiar la tabla de forma que tenga una columna y tres filas, reemplace la última línea de DisplayInWord con la instrucción siguiente y, a continuación, presione CTRL+F5.
```
range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);
```
Para especificar un formato predefinido para la tabla, reemplace la última línea de DisplayInWord con la instrucción siguiente y, a continuación, presione 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 System.Collections.Generic;
using System.Linq;
using System.Text;
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);
        }
    }
}

Vea también

Conceptos

Argumentos opcionales y con nombre (Guía de programación de C#)