Руководство. Обмен кодом между надстройкой VSTO и надстройкой Office с помощью общей библиотеки кода

Надстройки набора средств Visual Studio для Office (VSTO) отлично подходят для расширения возможностей Office с предоставлением решений для вашей компании и других пользователей. Они используются уже давно, и существуют тысячи решений, созданных с помощью VSTO. Однако они работают только в Office для Windows. Надстройки VSTO нельзя запускать на Mac, в Интернете или на мобильных платформах.

Важно!

Надстройки COM и VSTO не поддерживаются в новой предварительной версии Outlook для Windows . Эти надстройки по-прежнему поддерживаются в классическом классическом клиенте Outlook для Windows. Дополнительные сведения см. в статье Разработка надстроек Outlook для новых приложений Outlook в Windows.

Надстройки Office используют HTML, JavaScript и другие веб-технологии для создания решений Office для всех платформ. Перенос существующей надстройки VSTO в надстройку Office — это отличный способ обеспечить доступность решения на всех платформах.

Вам может потребоваться сохранить как надстройку VSTO, так и новую надстройку Office с одинаковыми функциями. Это позволяет продолжать обслуживание клиентов, использующих надстройку VSTO в Office для Windows. Кроме того, это позволяет предоставлять те же функции в надстройке Office для клиентов на любых платформах. Вы также можете убедиться, что надстройка Office совместима с существующей надстройкой VSTO.

Однако лучше не перезаписывать весь код из надстройки VSTO для надстройки Office. В этом руководстве показано, как избежать переписывания кода с использованием общей библиотеки кода для обеих надстроек.

Общая библиотека кода

В этом руководстве описано, как определить общий код и совместное использование кода между надстройкой VSTO и современной надстройкой Office. В нем используется очень простой пример надстройки VSTO, чтобы вы могли сосредоточиться на навыках и методах, необходимых для работы с собственными надстройками VSTO.

На следующей схеме показано, как общая библиотека кода используется для миграции. Распространенный код перерабатывается в новую общую библиотеку кода. Код может оставаться на исходном языке, например C# или VB. Это означает, что вы можете продолжить использование кода в существующей надстройке VSTO, создав ссылку на проект. При создании надстройки Office она также будет использовать общую библиотеку кода, вызывая ее с помощью REST API.

Навыки и методы, рассматриваемые в этом руководстве:

• Создание общей библиотеки классов путем преобразования кода в библиотеку классов .NET.
• Создание оболочки API REST с использованием ASP.NET Core для общей библиотеки классов.
• Вызов REST API из надстройки Office для доступа к общему коду.

Предварительные требования

Чтобы настроить среду разработки:

1. Установите Visual Studio 2019.
2. Установите следующие рабочие нагрузки.
   • ASP.NET и веб-разработка.
   • Кроссплатформенная разработка .NET Core
   • Разработка для SharePoint или Office.
   • Следующие отдельные компоненты.
     • Инструменты Visual Studio для Office (VSTO)
     • Среда выполнения .NET Core 3.0

Кроме того, необходимо следующее:

• Учетная запись Microsoft 365. Вы можете получить подписку разработчика Microsoft 365 E5, включающую приложения Office, в рамках программы microsoft 365 для разработчиков. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.
• Клиент Microsoft Azure. Пробную подписку можно получить на сайте Microsoft Azure.

Надстройка VSTO для анализа ячеек

В этом руководстве используется решение PnP общей библиотеки надстройки VSTO для надстройки Office. Папка /start содержит решение надстройки VSTO, которое будет перенесено. Целью является перенос надстройки VSTO в современную надстройку Office с помощью общего кода, когда это возможно.

Примечание.

В этом примере используется C#, но методы, описанные в этом руководстве, можно применить к надстройке VSTO, написанной на любом языке .NET.

1. Скачайте решение PnP общей библиотеки надстройки VSTO для надстройки Office в рабочую папку на своем компьютере.
2. Запустите Visual Studio 2019 и откройте решение /start/Cell-Analyzer.sln.
3. В меню Отладка выберите команду Начать отладку.

Надстройка является настраиваемой областью задач для Excel. Вы можете выделить любую ячейку с текстом и нажать кнопку Показать Юникод. В разделе Результат надстройка отобразит список всех символов в тексте вместе с соответствующим номером Юникода.

Анализ типов кода в надстройке VSTO

Первым применяемым методом является анализ надстройки, с которой можно поделиться частями кода. Обычно проект разделяется на три типа кода.

Код пользовательского интерфейса

Код пользовательского интерфейса взаимодействует с пользователем. В VSTO код пользовательского интерфейса работает через Windows Forms. Надстройки Office используют HTML, CSS и JavaScript для пользовательского интерфейса. Из-за этих различий невозможно предоставить общий доступ к коду пользовательского интерфейса с надстройкой Office. Пользовательский интерфейс требуется воссоздать в JavaScript.

Код документов

В VSTO код взаимодействует с документом через объекты .NET, такие как Microsoft.Office.Interop.Excel.Range. Однако надстройки Office используют библиотеку Office.js. Хотя они похожи, они не совсем одинаковы. Таким образом, вы не можете предоставить общий доступ к коду взаимодействия с документами с надстройкой Office.

Код логики

Бизнес-логика, алгоритмы, вспомогательные функции и аналогичный код часто являются основой надстройки VSTO. Этот код работает независимо от пользовательского интерфейса и кода документов с целью выполнения анализа, подключения к серверным службам, выполнения вычислений и т. д. Этим кодом можно поделиться, чтобы не переписывать его в JavaScript.

Рассмотрим надстройку VSTO. В коде ниже каждый раздел определен как код ДОКУМЕНТА, ПОЛЬЗОВАТЕЛЬСКОГО ИНТЕРФЕЙСА или АЛГОРИТМА.

// *** UI CODE ***
private void btnUnicode_Click(object sender, EventArgs e)
{
    // *** DOCUMENT CODE ***
    Microsoft.Office.Interop.Excel.Range rangeCell;
    rangeCell = Globals.ThisAddIn.Application.ActiveCell;

    string cellValue = "";

    if (null != rangeCell.Value)
    {
        cellValue = rangeCell.Value.ToString();
    }

    // *** ALGORITHM CODE ***
    //convert string to Unicode listing
    string result = "";
    foreach (char c in cellValue)
    {
        int unicode = c;

        result += $"{c}: {unicode}\r\n";
    }

    // *** UI CODE ***
    //Output the result
    txtResult.Text = result;
}

Используя этот подход, вы увидите, что надстройка Office может предоставить общий доступ к одному разделу кода. Следующий код необходимо рефакторинговать в отдельную библиотеку классов.

// *** ALGORITHM CODE ***
//convert string to Unicode listing
string result = "";
foreach (char c in cellValue)
{
    int unicode = c;

    result += $"{c}: {unicode}\r\n";
}

Создание общей библиотеки классов

Надстройки VSTO создаются в Visual Studio в виде проектов .NET, поэтому мы будем по возможности использовать .NET, чтобы не усложнять процесс. Наш следующий метод заключается в создании библиотеки классов и преобразовании общего кода в библиотеку классов.

1. Если вы этого еще не сделали, запустите Visual Studio 2019 и откройте решение /start/Cell-Analyzer.sln.

2. Щелкните правой кнопкой мыши (или выберите и удерживайте) решение в обозревателе решений и выберите команду Добавить > новый проект.

3. В диалоговом окне Добавить новый проект выберите Библиотека классов (.NET Framework) и нажмите кнопку Далее.

   Примечание.

   Не используйте библиотеку классов .NET Core, так как она не будет работать с проектом VSTO.

4. В диалоговом окне Настроить новый проект настройте следующие поля.

   • Укажите в поле Имя проекта значение CellAnalyzerSharedLibrary.
   • Оставьте значение по умолчанию для параметра Расположение .
   • Присвойте параметру Платформа значение 4.7.2.

5. Нажмите кнопку Создать.

6. После создания проекта измените имя файла Class1.cs на CellOperations.cs. Появится запрос на переименование класса. Измените имя класса, чтобы оно соответствовало имени файла.

7. Добавьте следующий код в класс CellOperations, чтобы создать метод GetUnicodeFromText.

   public class CellOperations
   {
       static public string GetUnicodeFromText(string value)
       {
           string result = "";
           foreach (char c in value)
           {
               int unicode = c;
   
               result += $"{c}: {unicode}\r\n";
           }
           return result;
       }
   }
   

Использование общей библиотеки классов в надстройке VSTO

Чтобы использовать библиотеку классов, требуется обновить надстройку VSTO. Важно, что надстройка VSTO и надстройка Office используют одну общую библиотеку классов, благодаря чему будущие исправления ошибок и функции создаются в одном расположении.

1. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) проект Анализатора ячеек и выберите Добавить ссылку.

2. Выберите CellAnalyzerSharedLibrary и нажмите кнопку ОК.

3. В обозревателе решений разверните проект Анализатора ячеек , щелкните правой кнопкой мыши (или выберите и удерживайте) файл CellAnalyzerPane.cs и выберите пункт Просмотр кода.

4. В методе btnUnicode_Click удалите следующие строки кода.

   //Convert to Unicode listing
   string result = "";
   foreach (char c in cellValue)
   {
     int unicode = c;
     result += $"{c}: {unicode}\r\n";
   }
   

5. Обновите строку кода под комментарием //Output the result следующим образом:

   //Output the result
   txtResult.Text = CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(cellValue);
   

6. В меню Отладка выберите команду Начать отладку. Настраиваемая область задач должна работать правильно. Введите текст в ячейке и проверьте, можно ли преобразовать его в список Юникод в надстройке.

Создание оболочки API REST

Надстройка VSTO может использовать общую библиотеку классов напрямую, так как они обе являются проектами .NET. Однако надстройка Office не сможет использовать .NET, так как она использует JavaScript. Далее вы создадите оболочку REST API. Это позволяет надстройке Office вызывать REST API, который затем передает вызов в общую библиотеку классов.

1. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) проект Анализатора ячеек и выберите команду Добавить > новый проект.

2. В диалоговом окне Добавить новый проект выберите Веб-приложение ASP.NET Core и нажмите кнопку Далее.

3. В диалоговом окне Настроить новый проект настройте следующие поля.

   • Укажите в поле Имя проекта значение CellAnalyzerRESTAPI.
   • В поле Расположение оставьте значение по умолчанию.

4. Нажмите кнопку Создать.

5. В диалоговом окне Создание веб-приложения ASP.NET Core выберите ASP.NET Core 3.1 для версии и выберите API в списке проектов.

6. Оставьте для всех остальных полей значения по умолчанию и нажмите кнопку Создать.

7. После создания проекта разверните проект CellAnalyzerRESTAPI в обозревателе решений.

8. Щелкните правой кнопкой мыши (или выберите и удерживайте) Зависимости и выберите Добавить ссылку.

9. Выберите CellAnalyzerSharedLibrary и нажмите кнопку ОК.

10. Щелкните правой кнопкой мыши (или выберите и удерживайте ) папку Контроллеры и выберите Команду Добавить > контроллер.

11. В диалоговом окне Добавление нового шаблонного элемента выберите Контроллер API — пустой, а затем нажмите кнопку Добавить.

12. В диалоговом окне Добавление пустого контроллера API присвойте контроллеру имя AnalyzeUnicodeController и нажмите кнопку Добавить.

13. Откройте файл AnalyzeUnicodeController.cs и добавьте следующий код в качестве метода для класса AnalyzeUnicodeController.

    [HttpGet]
    public ActionResult<string> AnalyzeUnicode(string value)
    {
      if (value == null)
      {
        return BadRequest();
      }
      return CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(value);
    }
    

14. Щелкните правой кнопкой мыши (или выберите и удерживайте) проект CellAnalyzerRESTAPI и выберите пункт Задать в качестве запускаемого проекта.

15. В меню Отладка выберите команду Начать отладку.

16. Запустится браузер. Чтобы проверить, работает ли API REST, введите следующий URL-адрес: https://localhost:<ssl port number>/api/analyzeunicode?value=test. Вы можете повторно использовать номер порта из URL-адреса в браузере, который запущен приложением Visual Studio. Должна возвратиться строка со значениями Юникода для каждого символа.

Создание надстройки Office

Когда вы создаете надстройку Office, она вызывает REST API. Но сначала требуется получить номер порта сервера API REST и сохранить его для последующего использования.

Сохранение номера порта SSL

1. Если вы этого еще не сделали, запустите Visual Studio 2019 и откройте решение /start/Cell-Analyzer.sln.
2. В проекте CellAnalyzerRESTAPI разверните пункт Свойства и откройте файл launchSettings.json.
3. Найдите строку кода со значением sslPort, скопируйте номер порта и сохраните его в другом месте.

Добавление проекта надстройки Office

Для удобства храните весь код в одном решении. Добавьте проект надстройки Office в существующее решение Visual Studio. Однако если вы знакомы с генератором Yeoman для надстроек Office и Visual Studio Code, вы также можете выполнить команду yo office для сборки проекта. Действия очень похожи.

1. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) решение Анализатора ячеек и выберите добавить > новый проект.
2. В диалоговом окне Добавить новый проект выберите Веб-надстройка Excel и нажмите кнопку Далее.
3. В диалоговом окне Настроить новый проект настройте следующие поля.
   • Укажите в поле Имя проекта значение CellAnalyzerOfficeAddin.
   • Оставьте значение по умолчанию для параметра Расположение .
   • Присвойте параметру Платформа значение 4.7.2 или укажите более позднюю версию.
4. Нажмите кнопку Создать.
5. В диалоговом окне Выбор типа надстройки выберите Добавить новые функции в Excel и нажмите Готово.

Будут созданы два проекта:

• CellAnalyzerOfficeAddin. Этот проект настраивает XML-файлы манифеста, описывающего надстройку, чтобы приложение Office могло правильно ее загрузить. Он содержит идентификатор, имя, описание и другие сведения о надстройке.
• CellAnalyzerOfficeAddinWeb. Этот проект содержит веб-ресурсы для надстройки, например HTML, CSS и скрипты. Он также настраивает экземпляр IIS Express для размещения надстройки в виде веб-приложения.

Добавление пользовательского интерфейса и функций в надстройку Office

1. В обозревателе решений разверните проект CellAnalyzerOfficeAddinWeb.

2. Откройте файл Home.html и замените содержимое <body> указанным ниже HTML-кодом.

   <button id="btnShowUnicode" onclick="showUnicode()">Show Unicode</button>
   <p>Result:</p>
   <div id="txtResult"></div>
   

3. Откройте файл Home.js и замените все содержимое указанным ниже кодом.

   (function () {
     "use strict";
     // The initialize function must be run each time a new page is loaded.
     Office.initialize = function (reason) {
       $(document).ready(function () {
       });
     };
   })();
   
   function showUnicode() {
     Excel.run(function (context) {
       const range = context.workbook.getSelectedRange();
       range.load("values");
       return context.sync(range).then(function (range) {
         const url = "https://localhost:<ssl port number>/api/analyzeunicode?value=" + range.values[0][0];
         $.ajax({
           type: "GET",
           url: url,
           success: function (data) {
             let htmlData = data.replace(/\r\n/g, '<br>');
             $("#txtResult").html(htmlData);
           },
           error: function (data) {
               $("#txtResult").html("error occurred in ajax call.");
           }
         });
       });
     });
   }
   

4. В приведенном выше коде введите номер sslPort, сохраненный ранее из файла launchSettings.json.

В предыдущем коде возвращаемая строка будет обрабатываться для замены веб-каналов строки возврата каретки тегами <br> HTML. Иногда могут возникать ситуации, когда возвращаемое значение, подходящее для .NET в надстройке VSTO, требуется изменить в надстройке Office для правильной работы. В этом случае REST API и библиотека общих классов занимаются только возвратом строки. За правильное форматирование возвращаемых значений для представления отвечает функция showUnicode().

Разрешение CORS из надстройки Office

Библиотеке Office.js требуется CORS для исходящих вызовов, например для создаваемых из вызова ajax к серверу API REST. Выполните следующие действия, чтобы разрешить вызовы REST API из надстройки Office.

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

2. В меню Вид выберите Пункт Свойства Окно, если окно еще не отображается.

3. В окне свойств скопируйте значение свойства URL-адрес SSL и сохраните его в другом месте. Это URL-адрес, который требуется разрешить в CORS.

4. В проекте CellAnalyzerRESTAPI откройте файл Startup.cs.

5. Добавьте следующий код в начале метода ConfigureServices. Не забудьте подставить URL-адрес SSL, скопированный ранее для вызова builder.WithOrigins.

   services.AddCors(options =>
   {
     options.AddPolicy(MyAllowSpecificOrigins,
     builder =>
     {
       builder.WithOrigins("<your URL SSL>")
       .AllowAnyMethod()
       .AllowAnyHeader();
     });
   });
   

   Примечание.

   Оставьте / в конце URL-адреса, если вы используете его в методе builder.WithOrigins. Он должен выглядеть примерно так: https://localhost:44000. В противном случае вы получите ошибку CORS во время выполнения.

6. Добавьте в класс Startup следующее поле.

   readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";
   

7. Добавьте следующий код в метод configure непосредственно перед строкой кода для app.UseEndpoints.

   app.UseCors(MyAllowSpecificOrigins);
   

По завершении ваш класс Startup должен выглядеть примерно как в следующем коде (ваш URL-адрес localhost может отличаться).

public class Startup
{
  public Startup(IConfiguration configuration)
    {
      Configuration = configuration;
    }

    readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

    public IConfiguration Configuration { get; }

    // NOTE: The following code configures CORS for the localhost:44397 port.
    // This is for development purposes. In production code, you should update this to 
    // use the appropriate allowed domains.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCors(options =>
        {
            options.AddPolicy(MyAllowSpecificOrigins,
            builder =>
            {
                builder.WithOrigins("https://localhost:44397")
                .AllowAnyMethod()
                .AllowAnyHeader();
            });
        });
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseCors(MyAllowSpecificOrigins);

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Запуск надстройки

1. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) верхний узел Решение "Анализатор ячеек" и выберите Задать запускаемые проекты.

2. В диалоговом окне Страницы свойств решения "Cell-Analyzer" выберите Несколько запускаемых проектов.

3. Присвойте свойству Действие значение Запуск для каждого из следующих проектов.

   • CellAnalyzerRESTAPI
   • CellAnalyzerOfficeAddin
   • CellAnalyzerOfficeAddinWeb

4. Нажмите кнопку OK.

5. В меню Отладка выберите команду Начать отладку.

Запустится приложение Excel, которое загрузит неопубликованную надстройку Office. Вы можете проверить, правильно ли работает служба REST API localhost, введя в ячейку текстовое значение и нажав кнопку Показать Юникод в надстройке Office. Она вызовет API REST и отобразит значения Юникода для текстовых символов.

Публикация в службе приложений Azure

В конечном итоге рекомендуется опубликовать проект API REST в облаке. В следующих действиях показано, как опубликовать проект CellAnalyzerRESTAPI в службе приложений Microsoft Azure. Сведения о способе получения учетной записи Azure см. в разделе Предварительные требования.

1. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) проект CellAnalyzerRESTAPI и выберите Опубликовать.
2. В диалоговом окне Выберите целевой объект публикации нажмите кнопку Создать и выберите вариант Создать профиль.
3. В диалоговом окне Служба приложений выберите правильную учетную запись, если она еще не выбрана.
4. Полям в диалоговом окне Служба приложений будут присвоены значения по умолчанию для вашей учетной записи. Как правило, значения по умолчанию работают нормально, но их можно изменить, если вы предпочитаете другие параметры.
5. В диалоговом окне Служба приложений нажмите Создать.
6. На странице Опубликовать отобразится новый профиль. Нажмите кнопку Опубликовать, чтобы создать и развернуть код в службе приложений.

Теперь можно протестировать службу. Откройте браузер и введите URL-адрес, непосредственно ведущий в новую службу. Например, используйте https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=test, где myappservice — это уникальное имя, созданное для новой Службы приложений.

Использование Службы приложений Azure из надстройки Office

Завершающим этапом является обновление кода в надстройке Office, позволяющее использовать Службу приложений Azure вместо localhost.

1. В обозревателе решений разверните проект CellAnalyzerOfficeAddinWeb и откройте файл Home.js.

2. Измените константу url, чтобы использовать URL-адрес для службы приложения Azure, как показано в следующей строке кода. Замените <myappservice> на уникальное имя, созданное вами для новой службы приложений.

   const url = "https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=" + range.values[0][0];
   

3. В обозревателе решений щелкните правой кнопкой мыши (или выберите и удерживайте) верхний узел Решение "Анализатор ячеек" и выберите Задать запускаемые проекты.

4. В диалоговом окне Страницы свойств решения "Cell-Analyzer" выберите Несколько запускаемых проектов.

5. Разрешите действие Запуск для каждого из следующих проектов.

   • CellAnalyzerOfficeAddinWeb
   • CellAnalyzerOfficeAddin

6. Нажмите кнопку OK.

7. В меню Отладка выберите команду Начать отладку.

Запустится приложение Excel, которое загрузит неопубликованную надстройку Office. Чтобы проверить правильность работы службы приложений, введите текстовое значение в ячейку и нажмите Показать Юникод в надстройке Office. Она должна вызвать службу и отобразить значения Юникода для текстовых символов.

Заключение

В этом руководстве вы узнали, как создать надстройку Office, которая использует общий код с исходной надстройкой VSTO. Вы узнали, как использовать код VSTO в Office для Windows и надстройку Office в Office на других платформах. Вы преобразовали код C# VSTO в общую библиотеку и развернули ее для службы приложений Azure. Вы создали надстройку Office, которая использует общую библиотеку, чтобы не перезаписывать код в JavaScript.