Использование именованных и необязательных аргументов в программировании приложений Office

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

Внимание

VSTO (набор средств Visual Studio для Office) зависит от платформа .NET Framework. Надстройки COM также можно записывать с помощью платформа .NET Framework. Надстройки Office нельзя создавать с помощью .NET Core и .NET 5+, последних версий .NET. Это связано с тем, что .NET Core/.NET 5+ не может работать вместе с платформа .NET Framework в том же процессе и может привести к сбоям загрузки надстроек. Вы можете продолжать использовать платформа .NET Framework для записи надстроек VSTO и COM для Office. Корпорация Майкрософт не будет обновлять VSTO или платформу надстройки COM для использования .NET Core или .NET 5+. Вы можете воспользоваться преимуществами .NET Core и .NET 5+, включая ASP.NET Core, чтобы создать серверную часть надстроек Office Web.

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

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

Примечание.

Отображаемые на компьютере имена или расположения некоторых элементов пользовательского интерфейса Visual Studio могут отличаться от указанных в следующих инструкциях. Это зависит от имеющегося выпуска Visual Studio и используемых параметров. Дополнительные сведения см. в разделе Персонализация среды IDE.

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

Запустите среду Visual Studio. В меню Файл последовательно выберите команды Создатьи Проект. В области "Категории шаблонов" разверните C#, а затем выберите Windows. В верхней части области Шаблоны в поле Требуемая версия .NET Framework должно отображаться значение .NET Framework 4. В области "Шаблоны" выберите консольное приложение. Введите имя проекта в поле Имя. Нажмите ОК. В обозревателе решений появится новый проект.

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

В Обозреватель решений щелкните правой кнопкой мыши имя проекта и нажмите кнопку "Добавить ссылку". Откроется диалоговое окно Добавление ссылки. На странице .NET выберите Microsoft.Office.Interop.Word в списке Имя компонента. Нажмите ОК.

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

В Обозреватель решений щелкните правой кнопкой мыши файл Program.cs и выберите команду View Code. В начало файла кода добавьте следующие директивы using:

using Word = Microsoft.Office.Interop.Word;

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

В класс 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();
}

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

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

Выполнение приложения

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

DisplayInWord();

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

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

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

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

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

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

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

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

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

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

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

Пример

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

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