Обработка событий в надстройке с размещением у поставщика

Статья
04/08/2023

Это седьмая часть серии статей, посвященной основам разработки надстроек SharePoint, размещаемых у поставщика. Для начала вам следует ознакомиться со статьей Надстройки SharePoint и предыдущими статьями этой серии, представленными в разделе Знакомство с созданием надстроек SharePoint, размещаемых у поставщика.

Примечание.

Если вы изучали предыдущие статьи этой серии о размещаемых у поставщика надстройках, то у вас уже есть решение Visual Studio, которое можно использовать для работы с данной статьей. Кроме того, вы можете скачать репозиторий на веб-странице SharePoint_Provider-hosted_Add-Ins_Tutorials и открыть файл BeforeAdd-inEventHandlers.sln.

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

Два места для программного развертывания компонентов SharePoint

Мы хотим, чтобы наша надстройка Chain Store автоматически создавала и развертывала списки Local Employees (Местные сотрудники) и Expected Shipments (Ожидаемые отгрузки). Надстройка может в любое время развертывать компоненты SharePoint, например настраиваемые списки. Но если надстройка зависит от определенного компонента, например настраиваемого списка, этот компонент необходимо развернуть, прежде чем пользователи начнут работать с надстройкой. Для таких критически важных компонентов настраиваемый код, выполняющий развертывание, можно разместить в двух местах:

в обработчике события установки для надстройки;
в коде, выполняемом при первом запуске надстройки в SharePoint.

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

Настраиваемый обработчик события установки должен выполняться в течение не более 30 секунд. Для кода, выполняемого при первом запуске, таких ограничений нет.
Если в процессе установки надстройки что-то пойдет не так, SharePoint откатит все действия, которые он выполнил в ходе установки. Настраиваемый обработчик события установки запускается после того как SharePoint выполнит все действия, необходимые для установки надстройки, поэтому обработчик может принять участие в работе этой системы.

Например, если ваш настраиваемый код создал исключение, вы можете сообщить SharePoint, что необходимо полностью откатить установку надстройки. Если же что-то пойдет не так в настраиваемом коде, выполняемом при первом запуске, надстройка останется установленной и, возможно, будет работать неправильно.
Если SharePoint придется откатить установку надстройки, он не "успокоится" на этом. Он сразу же попытается установить надстройку еще раз. Будет предпринято до 4 попыток (на каждую попытку выделяется 30 секунд). При каждой повторной попытке настраиваемый обработчик события установки запускается с самого начала. Если обработчик установил, например, список, перед откатом всех действий, то он будет пытаться установить этот же список при каждой новой попытке установить надстройку.

Чтобы не допустить этого, необходимо написать код обработчика события установки таким образом, чтобы он не выполнял никаких действий (например, развертывание компонента), прежде чем проверит, не выполнено ли это действие ранее. Из-за этого код обработчика события установки сложнее кода, выполняемого при первом запуске, так как последний не выполняется повторно (если, конечно, вы намеренно не запрограммируете повторное выполнение). Кроме того, чтобы проверить, не развернут ли какой-либо компонент, необходимо выполнить затратный по времени вызов через Интернет от удаленного обработчика к SharePoint. После этого понадобится выполнить второй вызов для развертывания компонента (если он еще не развернут).

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

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

Настройка решения для отладки приемника событий

Для отладки приемников событий необходимо использовать служебную шину Azure. Следуйте инструкциям в статье Устранение неполадок и отладка удаленного приемника событий в надстройке для SharePoint. Так как в качестве тестового сайта вы используете веб-сайт SharePoint Online, не забудьте выполнить эти инструкции на удаленном тестовом сайте. В следующих статьях этой серии подразумевается, что вы успешно настроили среду отладки.

Создание обработчика установки

Примечание.

Когда решение открывается повторно, для параметров раздела "Запускаемые проекты" в Visual Studio обычно возвращаются значения по умолчанию. После повторного открытия примера решения, который рассматривается в этой серии статей, всегда выполняйте указанные ниже действия.

В верхней части обозревателя решений щелкните узел решения правой кнопкой мыши и выберите пункт Назначить запускаемые проекты.
Убедитесь, что в столбце Действие для всех трех проектов указано значение Запуск.

В обозревателе решений выберите проект ChainStore, чтобы его свойства отобразились в области Свойства в Visual Studio.
Задайте для параметра Управление установленными надстройками значение True (этот параметр может по-прежнему называться Управление установленными приложениями). При этом выполняется два следующих действия:
- В проекте ChainStoreWeb (но не в проекте ChainStore) создается папка Services (Службы), в которую будут добавлены два файла: файл AppEventReceiver.svc и его файл кода программной части AppEventReceiver.svc.cs. (Имена файлов начинаются со строки App, так как ранее надстройки назывались приложениями. Не переименовывайте эти файлы. Для правильной работы пакета "Инструменты разработчика Office для Visual Studio" необходимо, чтобы файлы имели именно эти имена.)
- URL-адрес обработчика регистрируется в манифесте надстройки. Эта часть манифеста не отображается в конструкторе манифеста. Чтобы отобразить ее, щелкните правой кнопкой мыши файл AppManifest.xml и выберите пункт Просмотр кода. Новый дочерний элемент элемента Свойства выглядит, как показано ниже.
```
   <InstalledEventEndpoint>~remoteAppUrl/Services/AppEventReceiver.svc</InstalledEventEndpoint>
```
  Эта разметка сообщает SharePoint, что когда он завершит всю работу по установке надстройки, необходимо будет вызвать метод ProcessEvent этой службы. Настраиваемый обработчик — это последний компонент, запускаемый в процессе установки. Строка ~remoteAppUrl — это заполнитель, который пакет "Инструменты разработчика Office для Visual Studio" заменит URL-адресом узла службы. При отладке в качестве этого URL-адреса используется URL-адрес служебной шины Azure. При создании пакета для развертывания в рабочей среде используется URL-адрес рабочей среды.
Откройте файл AppEventReceiver.svc.cs.
Вы увидите, что пакет "Инструменты разработчика Office для Visual Studio" создал пример реализации метода ProcessEvent. Все реализации этого метода начинаются с инициализации объекта SPRemoteEventResult и заканчиваются возвращением этого объекта в SharePoint. Помимо прочего, этот объект сообщает SharePoint, следует ли откатить событие из-за сбоя кода настраиваемого обработчика.

Кроме того, возможно, пакет инструментов включил в этот метод блок using, который создает объект ClientContext. Настраиваемый обработчик в надстройке Chain Store не будет делать обратный вызов в SharePoint, поэтому удалите этот блок. Теперь метод должен выглядеть примерно так:
```
   public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
 {
     SPRemoteEventResult result = new SPRemoteEventResult();

     return result;
 }
```
Приемник событий можно вызвать с помощью любого из трех возможных событий надстройки, поэтому добавьте приведенную ниже структуру switch в метод ProcessEvent между строками, в которых создается и возвращается объект result. Имена событий включают строку App (Приложение), так как ранее надстройки назывались приложениями.
```
  switch (properties.EventType)
{
    case SPRemoteEventType.AppInstalled:

        // TODO2: Custom installation logic goes here.

        break;
    case SPRemoteEventType.AppUpgraded:
        // This sample does not implement an add-in upgrade handler.
        break;
    case SPRemoteEventType.AppUninstalling:

        // TODO3: Custom uninstallation logic goes here.         

        break;
}
```
Для регистрации магазина в Гонконге в качестве клиента в удаленном веб-приложении наш код, выполняемый во время установки, должен вызывать хранимую процедуру SQL. Очень важно, чтобы при сбое процесса обработчик сообщил SharePoint, что необходимо откатить установку надстройки. Поэтому добавьте указанные ниже блоки try/catch вместо TODO2.
```
  try
{
    CreateTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Обратите внимание на следующие особенности этого кода:
- Вы создадите объект tenantName и метод CreateTenant на одном из следующих этапов.
- Свойство Status объекта SPRemoteEventResult может иметь три одно из трех следующих значений: Continue (используется по умолчанию), CancelNoError и CancelWithError. Два последних значения сообщают SharePoint, что необходимо откатить событие.
URL-адрес хост-сайта, представляющий собой дискриминатор клиента в примере, включается в сведения, которые SharePoint передает в приемник в параметре SPRemoteEventProperties. Добавьте указанную ниже строку в метод ProcessEvent в строку сразу же после блока инициализации объекта SPRemoteEventResult.
```
  string tenantName = properties.AppEventProperties.HostWebFullUrl.ToString();
```
Теперь в нашем коде придется учесть небольшую особенность свойства AppEventProperties.HostWebFullUrl. В большинстве других контекстов SharePoint добавляет закрывающий символ косой черты ""/"" в конец URL-адреса хост-сайта, поэтому в нашем примере кода предполагается, что этот символ присутствует. Но SharePoint добавляет этот символ в конец значения HostWebFullUrl, исключительно когда хост-сайт является корневым веб-сайтом семейства веб-сайтов. Так как наш веб-сайт магазина в Гонконге представляет собой подсайт в семействе веб-сайтов, то нам потребуется добавить этот символ, чтобы во всем примере использовалось одно имя клиента.

Добавьте указанный ниже код сразу после блока инициализации объекта tenantName.
```
  if (!tenantName.EndsWith("/"))
{
    tenantName += "/";
}
```
Добавьте указанные ниже операторы using в начало файла.
```
  using System.Data.SqlClient;
  using System.Data;
  using ChainStoreWeb.Utilities;
```
Добавьте указанный ниже метод в класс AppEventReceiver. Мы не будем подробно рассматривать его, так как цель этой серии статей научить вас программированию надстроек SharePoint, а не программированию для SQL Server или Azure.
```
  private void CreateTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of installation.

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "AddTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();
    }//dispose conn and cmd
}
```
Этот метод будет создавать строку в таблице Tenants (Клиенты) базы данных. Кроме столбца Name (Имя), в таблице имеется столбец Version (Версия) со значением 0000.0000.0000.0000, используемым по умолчанию. В одной из следующих статей этой серии вы создадите код, выполняемый во время первого запуска, который будет использовать это значение, чтобы определить, установлена ли надстройка на хост-сайте. Если номер версии равен 0000.0000.0000.0000, то ваш код развернет списки Local Employees (Местные сотрудники) и Expected Shipments (Ожидаемые отгрузки), а затем увеличит номер версии.

Создание обработчика события удаления

При обработке события установки обычно рекомендуется обрабатывать и событие удаления. Основная причина этого состоит в том, что обработчик события удаления должен перемещать в корзину или удалять объекты, установленные обработчиком события установки. Тем не менее существует много исключений, поэтому вам необходимо хорошо понимать варианты использования вашей надстройки. Например, в списке, который развернут и заполнен надстройкой, могут остаться значения даже после ее удаления, поэтому вам может потребоваться, чтобы обработчик события удаления не удалял этот список.

Если пользователь удаляет надстройку со страницы Site Contents (Содержание сайта), то событие удаления не запускается (как можно было бы ожидать). В этом случае надстройка только перемещается в корзину веб-сайта. Пользователь может восстановить ее, но при восстановлении не будет перезапущен обработчик события установки. Поэтому при восстановлении надстройки вам может потребоваться, чтобы по-прежнему существовали все объекты, развернутые обработчиком события установки. Компоненты SharePoint можно переместить из корзины во вторую корзину. Событие удаления будет создано только после удаления надстройки из второй корзины. Если пользователь сделает это, то надстройка будет безвозвратно удалена, поэтому в этот момент нам понадобится удалить область клиента магазина в Гонконге из корпоративной базы данных.

Присвойте параметру Управление удалением надстроек значение True (этот параметр может по-прежнему называться Управление удалением приложений). Благодаря этому обработчик будет зарегистрирован в файле AppManifest.xml точно так же, как ранее был зарегистрирован обработчик события установки. Если вы просмотрите содержимое файла, то увидите, что у них абсолютно одинаковые URL-адреса. В средствах разработчика Office для Visual Studio предполагается, что вы используете один и тот же файл *.svc. Мы делаем это в данном примере. Кроме того, это стандартная рекомендация.
Добавьте приведенный ниже код вместо заполнителя TODO3 в файле AppEventReceiver.svc.cs.
```
  try
{
    DeleteTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Обратите внимание на следующие особенности этого кода:
- Метод DeleteTenant будет добавлен на следующем этапе.
- При откате удаления надстройка останется во второй корзине, из которой ее все еще можно восстановить.

Добавьте приведенный ниже метод в класс AppEventReceiver.

  private void DeleteTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of un-installation (removal from 2nd level Recycle Bin).

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "RemoveTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();                
    }//dispose conn and cmd
}

Примечание.

В предыдущей статье этой серии вы настроили проект так, чтобы при каждом нажатии клавиши F5 выполнялась перестройка корпоративной базы данных. Это приводит к очистке таблицы Tenants (Клиенты).

Запуск надстройки и тестирование обработчика установки

Нажмите клавишу F5, чтобы развернуть и запустить надстройку. Редактор Visual Studio размещает удаленное веб-приложение в IIS Express, а базу данных SQL — в SQL Express. Кроме того, он временно устанавливает надстройку на вашем тестовом сайте SharePoint, запускает обработчик события установки и немедленно запускает надстройку. Прежде чем откроется начальная страница надстройки, вам будет предложено предоставить надстройке необходимые разрешения.
Когда откроется начальная страница надстройки, щелкните значок с изображением шестеренки на расположенном вверху элементе управления хрома и выберите Параметры учетной записи.
На странице Учетные записи нажмите кнопку Показать версию надстройки. Отобразится номер версии 0000.0000.0000.0000.

Рис. 1. Страница параметров учетной записи
Чтобы завершить сеанс отладки, закройте окно браузера или остановите отладку в Visual Studio. При каждом нажатии клавиши F5 Visual Studio будет отзывать предыдущую версию надстройки и устанавливать ее последнюю версию.
Вы будете работать с этой надстройкой и решением Visual Studio при изучении других статей, поэтому при перерывах в работе рекомендуем отзывать надстройку. В обозревателе решений щелкните проект правой кнопкой мыши и выберите пункт Отозвать.

Дальнейшие действия

В следующей статье этой серии вы добавите в надстройку код, выполняемый при первом запуске, для автоматического развертывания списка Local Employees (Местные сотрудники) и настраиваемой кнопки ленты: Добавление кода, выполняемого при первом запуске, в надстройку, размещаемую у поставщика.

Поделиться через

Обработка событий в надстройке с размещением у поставщика

Два места для программного развертывания компонентов SharePoint

Настройка решения для отладки приемника событий

Создание обработчика установки

Создание обработчика события удаления

Запуск надстройки и тестирование обработчика установки

Дальнейшие действия

Дополнительные ресурсы