Практическое руководство. Использование именованных и необязательных аргументов в программировании приложений Office (Руководство по программированию на C#)

Появившиеся в Visual C# 2010 именованные и необязательные аргументы повышают удобство, гибкость и удобочитаемость программирования на C#. Кроме этого, данные функции значительно упрощают доступ к COM-интерфейсам, таким как интерфейсы API автоматизации Microsoft Office.

В следующем примере у метода ConvertToTable имеется шестнадцать параметров, представляющих характеристики таблицы, например число столбцов и строк, форматирование, границы и цвета. Все шестнадцать параметров являются необязательными, поскольку в большинстве случаев не требуется задавать конкретные значения для всех этих параметров. Однако без именованных и необязательных параметров приходилось указывать значение или значение-заполнитель для каждого из параметров. Именованные и необязательные параметры позволяют задавать значения только для тех параметров, которые требуются в конкретном проекте.

Для выполнения этих процедур на компьютере должен быть установлен Microsoft Office Word.

Создание нового консольного приложения

1. Запустите Visual Studio.

2. В меню Файл последовательно выберите пункты Создать и Проект.

3. В области Категории шаблонов откройте Visual C#, а затем щелкните Windows.

4. В верхней части области Шаблоны значение .NET Framework 4 должно отображаться в поле Требуемая версия .NET Framework.

5. В области Шаблоны щелкните Консольное приложение.

6. Введите имя проекта в поле Имя.

7. Нажмите кнопку ОК.

   В обозревателе решений появится новый проект.

Добавление ссылки

1. В обозревателе решений щелкните имя проекта правой кнопкой мыши и выберите Добавить ссылку. Откроется диалоговое окно Добавление ссылки.

2. На странице .NET выберите в списке Имя компонента элемент Microsoft.Office.Interop.Word.

3. Нажмите кнопку ОК.

Добавление необходимых директив Using

1. В обозревателе решений щелкните правой кнопкой мыши файл Program.cs и выберите пункт Просмотр кода.

2. Добавьте следующие директивы using в начало файла кода.

   using Word = Microsoft.Office.Interop.Word;
   

Отображение текста в документе Word

1. В класс Program в файле Program.cs добавьте следующий метод для создания приложения Word и документа Word. У метода Add имеется четыре необязательных параметра. В этом примере используются значения по умолчанию. Поэтому в инструкции вызова указывать аргументы не требуется.

   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();
   }
   

2. Добавьте в конец метода следующий код, чтобы определить место отображения текста в документе и текст для отображения.

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

Запуск приложения

1. Добавьте в метод Main следующую инструкцию.

   DisplayInWord();
   

2. Нажмите сочетание клавиш CTRL+F5, чтобы запустить проект. Появится документ Word, содержащий указанный текст.

Замена текста на таблицу

1. Метод ConvertToTable служит для преобразования текста в таблицу. У метода имеется шестнадцать необязательных параметров. IntelliSense заключает необязательные параметры в квадратные скобки, как показано на следующем рисунке.

   Параметры ConvertToTable

   

   Именованные и необязательные аргументы позволяют задавать значения только для тех параметров, которые требуется изменить. Добавьте в конец метода DisplayInWord следующий код, чтобы создать простую таблицу. Аргумент указывает, что запятые в текстовой строке в range разделяют ячейки таблицы.

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

   В предыдущих версиях C# для вызова ConvertToTable каждому параметру требовался ссылочный аргумент, как показано в следующем коде.

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

2. Нажмите сочетание клавиш CTRL+F5, чтобы запустить проект.

Экспериментирование с другими параметрами

1. Для изменения таблицы, чтобы она содержала один столбец и три строки, замените последнюю строку метода DisplayInWord следующей инструкцией и нажмите сочетание клавиш CTRL+F5.

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

2. Чтобы использовать заранее определенный формат таблицы, замените последнюю строку метода DisplayInWord следующей инструкцией и нажмите сочетание клавиш CTRL+F5. В качестве формата можно использовать любую из констант WdTableFormat.

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

Пример

Следующий код включает полный пример.

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);
        }
    }
}

См. также

Основные понятия

Именованные и необязательные аргументы (Руководство по программированию на C#)