Пошаговое руководство. Программирование Office в C#

Статья
03/09/2023

C# предлагает функции, которые улучшают программирование Microsoft Office. В число полезных функций C# входят именованные и необязательные аргументы и возвращаемые значения типа dynamic. В программировании COM можно опустить ключевое слово ref и получить доступ к индексированным свойствам.

Оба языка поддерживают внедрение сведений о типах, что позволяет развертывать сборки, взаимодействующие с компонентами COM, без предварительного развертывания на компьютере основных сборок взаимодействия (PIA). Дополнительные сведения см. в разделе Пошаговое руководство. Внедрение данных о типах из управляемых сборок.

В данном пошаговом руководстве эти возможности показаны в контексте программирования для Microsoft Office, но многие из них могут оказаться полезными и в других ситуациях. В этом пошаговом руководстве вы создадите книгу Excel с помощью надстройки Excel, а затем документ Word со ссылкой на эту книгу. Наконец, вы узнаете, как включать и отключать зависимость PIA.

Важно!

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.

Необходимые компоненты

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

Примечание.

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

Настройка приложения надстройки Excel

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

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

В Обозреватель решений щелкните правой кнопкой мыши имя проекта и нажмите кнопку "Добавить ссылку". Откроется диалоговое окно Добавление ссылки.
На вкладке Сборки в списке Имя компонента выберите Microsoft.Office.Interop.Excel, версия <version>.0.0.0 (расшифровку номеров версий продуктов Office см. в разделе Версии Майкрософт), а затем, удерживая нажатой клавишу CTRL, выберите Microsoft.Office.Interop.Word, version <version>.0.0.0. Если сборки не отображаются, их может потребоваться установить (см . инструкции по установке основных сборок взаимодействия Office).
Нажмите ОК.

Добавление необходимых инструкций Import или директив using

В Обозреватель решений щелкните правой кнопкой мыши файл ThisAddIn.cs и выберите команду View Code. Добавьте следующие using директивы (C#) в начало файла кода, если они еще не присутствуют.

using System.Collections.Generic;
using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;

Создание списка банковских счетов

В Обозреватель решений щелкните правой кнопкой мыши имя проекта, выберите "Добавить" и выберите "Класс". Назовите класс Account.cs. Выберите Добавить. Замените определение класса Account следующим кодом. В определениях классов используются автоматически реализуемые свойства.

class Account
{
    public int ID { get; set; }
    public double Balance { get; set; }
}

Чтобы создать bankAccounts список, содержащий две учетные записи, добавьте следующий код в ThisAddIn_Startup метод в ThisAddIn.cs. В объявлениях списков используются инициализаторы коллекций.

var bankAccounts = new List<Account>
{
    new Account
    {
        ID = 345,
        Balance = 541.27
    },
    new Account
    {
        ID = 123,
        Balance = -127.44
    }
};

Экспорт данных в Excel

В том же самом файле добавьте в класс ThisAddIn следующий метод. Этот метод служит для настройки книги Excel и экспорта данных в нее.

void DisplayInExcel(IEnumerable<Account> accounts,
           Action<Account, Excel.Range> DisplayFunc)
{
    var excelApp = this.Application;
    // Add a new Excel workbook.
    excelApp.Workbooks.Add();
    excelApp.Visible = true;
    excelApp.Range["A1"].Value = "ID";
    excelApp.Range["B1"].Value = "Balance";
    excelApp.Range["A2"].Select();

    foreach (var ac in accounts)
    {
        DisplayFunc(ac, excelApp.ActiveCell);
        excelApp.ActiveCell.Offset[1, 0].Select();
    }
    // Copy the results to the Clipboard.
    excelApp.Range["A1:B3"].Copy();
}

У метода Add есть необязательный параметр для указания конкретного шаблона. Необязательные параметры позволяют опустить аргумент для этого параметра, если вы хотите использовать значение по умолчанию параметра. Так как предыдущий пример не имеет аргументов, Add использует шаблон по умолчанию и создает новую книгу. В эквивалентном операторе в более ранних версиях C# необходимо было использовать аргумент-местозаполнитель excelApp.Workbooks.Add(Type.Missing). Дополнительные сведения см. в разделе Именованные и необязательные аргументы.
Свойства Range и Offset объекта Range используют возможность индексированных свойств. Она позволяет использовать свойства типов COM с помощью стандартного синтаксиса C#. Кроме того, индексированные свойства позволяют использовать свойство Value объекта Range, устраняя необходимость в использовании свойства Value2. Свойство Value является индексированным, но индекс — необязательным. Совместная работа необязательных аргументов и индексированных свойств показана в следующем примере.

// Visual C# 2010 provides indexed properties for COM programming.
excelApp.Range["A1"].Value = "ID";
excelApp.ActiveCell.Offset[1, 0].Select();

Не удается создать индексированные свойства собственных. Эта возможность поддерживает только использование имеющихся индексированных свойств.

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

excelApp.Columns[1].AutoFit();
excelApp.Columns[2].AutoFit();

Эти дополнения демонстрируют еще одну возможность C#: значения Object, возвращаемые главными приложениями COM, например приложениями Office, и обрабатываются так, как если бы они имели тип dynamic. COM-объекты обрабатываются автоматически dynamic , если типы взаимодействия внедрения имеют значение по умолчанию или True, аналогично, при ссылке на сборку с параметром компилятора EmbedInteropTypes . Дополнительные сведения о внедрении типов взаимодействия см. в процедурах "Поиск ссылки на PIA" и "Восстановление зависимости PIA" далее в этой статье. Дополнительные сведения о dynamic см. в разделе dynamic или Использование типа dynamic.

Вызов DisplayInExcel

Добавьте следующий код в конец метода ThisAddIn_StartUp. Вызов метода DisplayInExcel содержит два аргумента. Первым аргументом является имя списка обработанных учетных записей. Второй аргумент — это многостроочное лямбда-выражение, определяющее способ обработки данных. Значения ID и balance для каждого из счетов отображаются в соседних ячейках, а если баланс имеет отрицательное значение, строка отображается красным. Дополнительные сведения см. в разделе Лямбда-выражения.

DisplayInExcel(bankAccounts, (account, cell) =>
// This multiline lambda expression sets custom processing rules
// for the bankAccounts.
{
    cell.Value = account.ID;
    cell.Offset[0, 1].Value = account.Balance;
    if (account.Balance < 0)
    {
        cell.Interior.Color = 255;
        cell.Offset[0, 1].Interior.Color = 255;
    }
});

Чтобы запустить программу, нажмите клавишу F5. Появится книга Excel, содержащая данные о счетах.

Добавление документа Word

Добавьте в конец метода ThisAddIn_StartUp следующий код, чтобы создать документ Word, содержащий ссылку на книгу Excel.

var wordApp = new Word.Application();
wordApp.Visible = true;
wordApp.Documents.Add();
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);

Этот код демонстрирует несколько функций в C#: возможность пропускать ref ключевое слово в программировании COM, именованные аргументы и необязательные аргументы. Метод PasteSpecial имеет семь параметров, все из которых являются необязательными ссылочными параметрами. Именованные и необязательные аргументы позволяют определять параметры, к которым требуется обращаться по имени, и передавать аргументы только для этих параметров. В этом примере аргументы указывают на создание ссылки на книгу в буфере обмена (параметр Link) и отображение ссылки в документе Word в виде значка (параметра DisplayAsIcon). C# также позволяет опустить ref ключевое слово для этих аргументов.

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

Нажмите клавишу F5 для запуска приложения. Будет запущено приложение Excel, в котором будет открыта таблица, содержащая сведения о двух счетах из списка bankAccounts. Затем будет открыт документ Word, содержащий ссылку на таблицу Excel.

Очистка завершенного проекта

В Visual Studio выберите "Очистить решение " в меню "Сборка ". В противном случае надстройка выполняется при каждом открытии Excel на компьютере.

Поиск ссылки на PIA

Снова запустите приложение, но не нажимайте кнопку "Очистить решение".
Выберите кнопку Пуск. Найдите версию> Microsoft Visual Studio <и откройте командную строку разработчика.
В окне командной строки разработчика для Visual Studio введите команду ildasm, а затем нажмите клавишу ВВОД. Появится окно программы IL DASM.
В меню Файл в окне IL DASM выберите пункт Файл>Открыть. Дважды щелкните версию> Visual Studio <и дважды щелкните "Проекты". Откройте папку проекта и найдите в папке bin/Debug файл имя_проекта.dll. Дважды щелкните файл имя_проекта.dll. В новом окне будут показаны атрибуты проекта, а также ссылки на другие модули и сборки. Сборка включает пространства Microsoft.Office.Interop.Excel имен и Microsoft.Office.Interop.Word. По умолчанию в Visual Studio компилятор импортирует в сборку необходимые типы из сборки PIA, на которую указывает ссылка. Дополнительные сведения см. в разделе Практическое руководство. Просмотр содержимого сборок.
Дважды щелкните значок МАНИФЕСТ. Откроется окно со списком сборок, содержащих элементы, на которые имеются ссылки в проекте. Microsoft.Office.Interop.Excel и Microsoft.Office.Interop.Word нет в списке. Так как вы импортировали типы проектов в сборку, вам не требуется устанавливать ссылки на PIA. Импорт типов в сборку упрощает развертывание. Пин-коды не должны присутствовать на компьютере пользователя. Приложению не требуется развертывание определенной версии PIA. Приложения могут работать с несколькими версиями Office, если необходимые API существуют во всех версиях. Поскольку развертывать сборки PIA больше не требуется, можно создавать приложения для применения в сложных сценариях, чтобы эти приложения работали с несколькими версиями Office, включая и более ранние версии. Код не может использовать интерфейсы API, которые недоступны в версии Office, с которыми вы работаете. Не всегда ясно, был ли определенный API доступен в более ранней версии. Не рекомендуется работать с более ранними версиями Office.
Закройте окно манифеста и окно сборки.

Восстановление зависимости PIA

В Обозреватель решений нажмите кнопку "Показать все файлы". Разверните папку Ссылки и выберите Microsoft.Office.Interop.Excel. Нажмите клавишу F4, чтобы открыть окно "Свойства".
В окне Свойства измените значение свойства Внедрить типы взаимодействия с True на False.
Повторите шаги 1 и 2 этой процедуры для сборки Microsoft.Office.Interop.Word.
В C# раскомментируйте два вызова метода Autofit в конце метода DisplayInExcel.
Нажмите клавишу F5, чтобы проверить, что проект по-прежнему выполняется правильно.
Повторите шаги 1–3 из предыдущей процедуры, чтобы открыть окно сборки. Обратите внимание, что сборки Microsoft.Office.Interop.Word и Microsoft.Office.Interop.Excel больше не входят в список внедренных сборок.
Дважды щелкните значок МАНИФЕСТ и просмотрите список сборок, на которые имеются ссылки. В списке будут указаны сборки Microsoft.Office.Interop.Word и Microsoft.Office.Interop.Excel. Так как приложение ссылается на личные данные Excel и Word, а свойство "Типы взаимодействия внедрения" имеет значение False, обе сборки должны существовать на компьютере конечного пользователя.
В Visual Studio выберите "Очистить решение " в меню "Сборка ", чтобы очистить завершенный проект.