Обработка событий в надстройках SharePoint
Пользовательский код в надстройках с размещением у поставщика может обрабатывать три категории событий:
- События списков, например добавление или удаление списка на веб-сайте.
- События элементов списков, например редактирование элемента в списке.
- События надстройки, например установка надстройки.
Надстройки SharePoint с размещением в SharePoint не поддерживают обработку событий, но вы можете превратить рабочий процесс в подобие обработчика событий списков или их элементов, сделав так, чтобы событие вызывало рабочий процесс. Дополнительные сведения см. в статье Рабочие процессы в SharePoint. События надстроек не могут вызывать рабочие процессы, поэтому они не могут обрабатываться надстройкой с размещением в SharePoint.
Примечание.
События веб-сайтов и семейств веб-сайтов не поддерживаются в надстройках SharePoint.
События делятся на два типа:
События до операции вызываются до обработки события инфраструктурой SharePoint (в том числе сохранения изменений в базе данных контента). В SharePoint пользовательские обработчики событий до операции всегда выполняются синхронно. Помимо прочего, их можно использовать для отмены события. Например, если у надстройки есть функция удаления списка, обработчик соответствующего события может отменить удаление, если не соблюдаются определенные условия. Если событие является частью последовательности, его отмена предотвратит возникновение последующих событий. Например, если обработчик события ItemAdding отменяет его, то следующее событие ItemAdded не вызывается.
События после операции вызываются после обработки события инфраструктурой SharePoint. В SharePoint обработчики удаленных событий после операции всегда выполняются асинхронно. (Исключение составляют события приложений.). Помимо прочего, их можно использовать для регистрации событий.
Обработка событий списков и событий элементов списков
Для обработки событий списка и элементов списка создаются удаленные приемники событий (RER), которые представляют собой веб-службы, которые выполняются извне в ферме SharePoint или SharePoint Online. URL-адрес службы RER регистрируется для обрабатываемых ей событий. Зарегистрировать обработчик можно двумя способами:
События на хост-сайте регистрируются программно с помощью CSOM (клиентской объектной модели) или REST API SharePoint. Обычно для этого используется логика "первого запуска" в надстройке или обработчике события надстройки. (Обзор событий надстройки см. в разделе Обработка событий надстройки этой статьи.) Пример кода, который программно регистрирует событие списка, см. на странице SharePoint/PnP/Samples/Core.EventReceivers.
События на сайте надстройки обычно регистрируются в компоненте сайта с помощью простой разметки XML. Подробные сведения о создании разметки и службы представлены в статье Создание удаленного приемника событий в надстройках SharePoint. Кроме того, события на сайте надстройки можно регистрировать программным способом.
Примечание.
Удаленные приемники событий служат для того же, что и приемники событий в фермах. Но последние содержат специальный код, выполняемый на серверах SharePoint, поэтому их нельзя использовать в надстройках SharePoint.
Надстройка может обрабатывать приведенные ниже события списков и события библиотеки документов. События с окончанием "ing" выполняются до события (синхронно), а события с окончанием "ed" — после (асинхронно).
| До (синхронно) | После (асинхронно) |
|---|---|
| ListAdding | ListAdded |
| ListDeleting | ListDeleted |
| FieldAdding | FieldAdded |
| FieldDeleting | FieldDeleted |
| FieldUpdating | FieldUpdated |
События обновления полей связаны с изменением свойств поля (столбца) в списке, например возможности сортировки, а не с изменением данных в поле.
Надстройка может обрабатывать следующие события элементов списков:
| До (синхронно) | После (асинхронно) |
|---|---|
| ItemAdding | ItemAdded |
| ItemUpdating | ItemUpdated |
| ItemDeleting | ItemDeleted |
| ItemCheckingOut | ItemCheckedOut |
| ItemCheckingIn | ItemCheckedIn |
| ItemUncheckingOut | ItemUncheckedOut |
| ItemAttachmentAdding | ItemAttachmentAdded |
| ItemAttachmentDeleting | ItemAttachmentDeleted |
| ItemFileMoving | ItemFileMoved |
| ItemVersionDeleting* | ItemVersionDeleted* |
| ItemFileConverted |
Примечание.
*Эти два новых события могут быть недоступны в пользовательском интерфейсе Visual Studio. Если это так, выберите событие ItemDeleting или ItemDeleted и измените имена вручную.
При работе в Visual Studio и добавлении RER в проект надстройки SharePoint Инструменты разработчика Office для Visual Studio делают следующее:
Файл веб-службы, например RemoteEventReceiver1.svc, добавляется в веб-приложение для обработки событий, указанных при добавлении удаленного приемника событий в надстройку SharePoint. Веб-служба содержит файл с кодом для обработки удаленных событий.
После создания приемника удаленных событий следует добавить код в файл, используемый службой веб-приложения для обработки событий. По умолчанию файл кода содержит два метода, к которым добавляется код обработки:
ProcessEvent()обрабатывает события до операции (такие, как в левых столбцах выше) и возвращает в SharePoint объект, сообщающий, отменять ли событие.ProcessOneWayEvent()обрабатывает события "после". Он выполняется асинхронно и не возвращает в SharePoint никаких данных.
Когда происходит зарегистрированное событие, SharePoint вызывает соответствующий метод в службе и передает объект, который предоставляет контекстные сведения для кода. Например, определяется тип события (указанный в одной из двух таблиц выше), чтобы код мог перейти к логике, соответствующей этому событию.
Элемент проекта для удаленного приемника событий добавляется в проект надстройки SharePoint. Файл Elements.xml для удаленного приемника событий ссылается на веб-службу в веб-приложении, а также на указанные удаленные события. В следующем примере показано, как файл Elements.xml обрабатывает добавление или удаление элемента списка.
<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <Receivers ListTemplateId="104"> <Receiver> <Name>RemoteEventReceiver1ItemAdding</Name> <Type>ItemAdding</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> <Receiver> <Name>RemoteEventReceiver1ItemDeleting</Name> <Type>ItemDeleting</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> </Receivers> </Elements>
Чтобы изменить события, обрабатываемые удаленным приемником событий, откройте обозреватель решений, затем окно Свойства для удаленного приемника событий, разверните узел События SharePoint и задайте для нужных событий значения True.
Примечание.
Дополнительные сведения об удаленных приемниках событий, в том числе сведения об устранении неполадок, см. в разделе Удаленные приемники событий: вопросы и ответы.
Обработка событий надстройки
События надстройки также обрабатываются удаленными веб-службами, но настраиваются в пакете надстройки не так, как удаленные приемники событий списков и событий элементов списков, поэтому рассматриваются как отдельная категория компонента. В этом случае удаленная веб-служба регистрируется в манифесте надстройки, а не в компоненте сайта надстройки. Для надстройки даже не нужен сайт. Существует три события надстройки, которые описаны в следующих разделах.
Событие AppInstalled
Событие AppInstalled выполняется сразу после установки надстройки, но до отправки пользователю уведомления о ее завершении. Хотя это и происходит послезавершения, SharePoint запускает обработчик синхронно. Надстройка не доступна для использования до завершения работы обработчика, он может отменить установку (в результате чего SharePoint отменит все выполненные действия). Рекомендуется для выявления ошибок в обработчике и уведомления SharePoint об отмене установки. Дополнительные сведения см. в разделе Включение логики отката и логики проверки выполненных действий в обработчики событий надстроек.
Примечание.
При установке надстройки на уровне клиента она устанавливается в семействе веб-сайтов каталога надстроек, и событие AppInstalled запускается только после этого. Надстройка видима на нескольких веб-сайтах в клиентской организации, но событие не запускается для каждого из них отдельно.
Помимо отмены установки надстройки, это событие можно использовать для других целей, в том числе:
Установки на хост-сайте компонентов SharePoint, которые невозможно декларативно установить с помощью компонента хост-сайта, например списков и дочерних веб-сайтов.
Программной регистрации обработчиков событий списков и их элементов на хост-сайте или сайте надстройки.
Установки параметров инициализации, зависящих от экземпляра надстройки. Например, у надстройки может быть контейнер свойств для хранения параметров, которые отличаются для разных экземпляров надстройки. Обработчик AppInstalled может записывать в контейнер свойств разные значения, зависящие, к примеру, от типа хост-сайта (например, сайта группы или блога).
Примечание.
Проверка того, является ли хост-сайт сайтом AppCatalog, — хороший способ определить, установлена ли надстройка с областью клиента. В разделе Сроки аренды и области развертывания надстроек для SharePoint.
Выполнения в удаленном веб-приложении настройки, зависящей от экземпляра надстройки, например добавления таблицы в базу данных.
Важно!
Ваша реализация события AppInstalled должна завершаться в течение 30 секунд, иначе инфраструктура установки SharePoint посчитает, что произошел сбой. Инфраструктура перезапустит событие и повторит ваш код с начала (еще три раза). Если время ожидания истечет четыре раза, SharePoint выполнит полный откат установки надстройки. Подробное описание последствий представлено в разделе Включение логики отката и логики проверки выполненных действий в обработчики событий надстроек.
Событие AppUninstalling
Событие AppUninstalling не запускается при удалении надстройки с хост-сайта. Надстройка всего лишь перемещается в корзину пользователя. Перед вызовом события AppUninstalling необходимо выполнить два действия. Во-первых, пользователь должен удалить надстройку из корзины, что приведет к перемещению надстройки во вторую корзину. Во-вторых, пользователь должен удалить надстройку из корзины второго этапа. Эта последняя задача активирует событие AppUninstalling. Событие AppUninstalling является синхронным, его можно использовать для отмены удаления, чтобы надстройка осталась во второй корзине.
Основное назначение обработчика этого события — удаление или перемещение в корзину элементов, развернутых обработчиком события AppInstalled (или AppUpdated). SharePoint не может удалить эти элементы или переместить их в корзину, так как не располагает данными о них, по крайней мере не как о компонентах надстройки. Эти элементы рекомендуется удалять. Но вы можете оставить элементы, которые будут использоваться после удаления надстройки. Если список или веб-сайт, созданный обработчиком события AppInstalled, еще будет использоваться, не удаляйте его в обработчике события AppUninstalling.
Событие AppUpgraded
Событие AppUpgraded запускается сразу после обновления надстройки до новой версии, но до отправки пользователю уведомления о его завершении. Как и событие AppInstalled, оно выполняется после операции, но, по сути, является синхронным и рекомендуется для выявления ошибок и уведомления SharePoint об откате обновления.
Некоторые примеры того, что может делать обработчик этого события:
Добавление, изменение или удаление компонентов надстройки с хост-сайта.
Действия в надстройке, которые невозможно выполнить с помощью описательной семантики обновления в компоненте сайта надстройки. Например, с помощью декларативной разметки обновления невозможно удалять элементы, но это можно сделать программно в обработчике события AppUpgraded.
Изменение компонентов, зависящих от экземпляра надстройки, в веб-приложении или удаленной базе данных надстройки.
Подробные инструкции по созданию обработчиков событий надстроек см. в статье Создание приемника событий надстройки в надстройках для SharePoint.
Включение логики отката и логики проверки выполненных действий в обработчики событий надстроек
Если при обработке любого из трех событий надстройки возникает ошибка, SharePoint отменяет событие и откатывает все связанные с ним изменения. Обработчики событий надстроек должны учитывать эту систему, так как при сбое части реализуемого события нужно откатить все событие, а не продолжать работу, рискуя оставить надстройку в поврежденном состоянии. Как правило, обработчик должен сделать следующее:
Сообщить SharePoint об ошибке. Сообщение SOAP, которое веб-служба обработки событий надстроек возвращает в SharePoint, содержит свойство Status со значением Continue, CancelWithError или CancelWithoutError. Оба состояния Cancel сообщают SharePoint, что необходимо откатить событие.
Выполнить откат действий, уже выполненных обработчиком до обнаружения ошибки. Как правило, среда SharePoint не может это сделать, поскольку ей неизвестно, какие действия выполнил обработчик. Это правило не является универсальным. Например, если произошла отмена установки надстройки, SharePoint полностью удалит сайт надстройки, поэтому обработчику события AppInstalled нет смысла отменять все действия, выполненные с этим сайтом. Тем не менее, обычно он должен отменять действия, выполненные с хост-сайтом или удаленными компонентами надстройки.
Примечание.
Указанное выше относится как к событию AppUninstalling, так и к двум другим событиям надстроек. Например, если после удаления строки из удаленной базы данных возникает ошибка, строку необходимо восстановить. Так как служба отправляет в SharePoint сообщение об отмене, надстройка не удаляется из корзины. При восстановлении и повторном использовании она может не работать без этой записи в базе данных. Однако обработчик AppUninstalling завершает работу до удаления надстройки из корзины. Таким образом, при возникновении ошибки в самом SharePoint и отмене удаления обработчик не может отменить выполненные действия.
Если среда SharePoint не получает сообщение от обработчика в течение 30 секунд, она снова вызывает обработчик. После трех повторных попыток (всего четырех) выполняется полный откат события. При каждом вызове обработчика код запускается сначала. Как правило, вам не нужно, чтобы обработчик повторял уже выполненные действия, например создание списка на хост-сайте, и вам неизвестно, завершила ли логика отката свою работу, или вообще запустилась, до истечения времени ожидания обработчика. По этой причине логика вашего обработчика не должна предпринимать никаких действий, не проверив, не совершено ли уже какое-либо действие, кроме случаев, когда повторение действий является безопасным.
Ошибки установки и обновления отображаются в пользовательском интерфейсе SharePoint, как показано на следующем рисунке.
Получение сведений об ошибке установки
Стратегии архитектуры обработчиков событий надстройки
Обработчик, выраженный в псевдокоде, обычно должен быть структурирован примерно следующим образом. Если в разделе Try возникает ошибка, следует вызвать раздел Catch и Rollback . (Это может произойти автоматически в зависимости от языка и платформы.)
Try
If X not already done,
Do X.
Catch
Send cancel message to SharePoint.
If X not already undone,
Undo X.
Однако логика отката и проверки выполненных действий в веб-службе может замедлить работу обработчика. Логика установки и отката обычно изменяет объекты, более или менее удаленные от веб-службы, например хост-сайт SharePoint или внутреннюю базу данных. Если код установки и отката поделен между разделами Try и Catch, то служба вызывает удаленные компоненты по отдельности, часто несколько раз в каждом разделе.
Рекомендуется реализовать логику установки и отката непосредственно в удаленном компоненте с помощью процедуры, которая может вызываться из раздела Try обработчика. Процедура должна возвращать сообщение об успешном завершении или сбое. В последнем случае код из раздела Try вызывает раздел Catch (например, сообщив об исключении). Раздел Catch лишь уведомляет SharePoint. Назовем это стратегией делегирования обработчика. Она проиллюстрирована следующим псевдокодом:
Try
Call the "Do X" procedure on remote platform.
If remote platform reports failure, call Catch.
Catch
Send cancel message to SharePoint.
Процедура "Do X", которая выполняется в удаленной системе, содержит логику отката и проверки выполненных действий, как показано ниже.
Try
If X not already done,
Do X.
Set success flag to true.
Catch
If X was done before error,
Undo X.
Set success flag to false.
Send
Return success flag to the event handler.
Например, если обработчик должен выполнить действие с базой данных SQL Server, вы можете установить на сервере SQL Server хранимую процедуру, которая использует блок TRY-CATCH для реализации логики отката, с блоками IF-ELSE для реализации логики проверки выполненных действий.
Модель надстроек SharePoint не позволяет хранить пользовательский серверный код в SharePoint и вызывать его из клиентской объектной модели (CSOM). Но CSOM позволяет объединить логику try-catch и if-then-else и отправить ее на сервер для выполнения.
Подробный пример обработчика событий надстройки, который использует стратегию делегирования для добавления списка на хост-сайт, см. в статье Создание приемника событий надстройки в надстройках для SharePoint. Пример кода см. на странице SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation.
Стратегию делегирования обработчика можно использовать не всегда. Например, если обработчик вызывает несколько компонентов, например базу данных и хост-сайт SharePoint, один из вызовов может завершиться успешно, а другой — с ошибкой. В этом случае логика отката для первого компонента не выполняется, если она реализована согласно стратегии делегирования обработчика. По этой причине при синхронном вызове компонентов только последний из них может использовать эту стратегию. При асинхронном вызове эту стратегию нельзя использовать ни в одном из них.
Пример обработчика событий надстройки, который не использует стратегию делегирования обработчика, см. в статье SharePoint/PnP/Samples/Core.AppEvents.
Совет
Если происходит сбой события AppInstalled, SharePoint удаляет сайт надстройки (если он существует), если же происходит сбой события AppUpated, SharePoint восстанавливает состояние надстройки до обновления. По этой причине обработчикам никогда не нужно отменять действия, выполненные на сайте надстройки. Если обработчик выполняет действия как на хост-сайте, так и на сайте надстройки, то начать следует с сайта надстройки. Это позволит использовать стратегию делегирования обработчика для хост-сайта. Даже если действия с сайтом надстройки выполняются успешно, а действия с хост-сайтом завершаются с ошибкой, выполняется вся логика отката.
Удаленные приемники событий в надстройках, поддерживающих несколько зон безопасности
Некоторые ограничения на разработку надстроек поддерживают несколько зон безопасности и имеют удаленный приемник событий.
Удаленные приемники событий: вопросы и ответы
Ниже приведены распространенные вопросы, которые могут возникнуть при использовании удаленных приемников событий.
Чем удаленные приемники событий отличаются от приемников событий в SharePoint 2010?
В SharePoint 2010 приемники событий обрабатывают события, которые происходят в списках, сайтах и других объектах SharePoint, выполняя код на сервере SharePoint (с полным доверием или в песочнице). Этот тип приемника событий по-прежнему существует в SharePoint. Однако SharePoint также поддерживает удаленные приемники событий, в которых код, выполняющийся при вызове события, размещается в веб-службе. Это означает, что при регистрации удаленного приемника событий также необходимо сообщить SharePoint, какую веб-службу вызывать.
В следующих примерах кода первый пример (решения SharePoint) реализует функции с помощью обработчика событий. Второй пример (надстройки SharePoint) реализует те же функции с помощью удаленного приемника событий.
Решения SharePoint
// Trigger an event when an item is added to the SharePoint list.
Public class OnPlantUpdated : SPItemEventReceiver
{
Public override void ItemAdding (SPItemEventProperties properties)
{
Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties));
Properties.status =SPEventReceiverStatus.Continue;
}
/// When an item updates, run the following.
Public override void ItemUpdating(SPItemEventProperties properties)
{
Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties));
Properties.Status= SPEventReceiverStatus.Continue;
}
Надстройки SharePoint
/* Trigger an event when an item is added to the SharePoint list*/
Public class OnPlantUpdated : IRemoteEventService
{
public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties)
{
SPRemoteEventResult result =new SPRemoteEventResult();
If (properties.EventType == SPRemoteEventType.ItemAdding ||
properties.EventType == SPRemoteEventType.ItemUpdating)
{
// Add code that runs when an item is added or updated.
}
Полный пример кода см. в статье Добавление свойств элементов списков с помощью приемника удаленных событий.
Подробную демонстрацию примера кода см. в видео Перенос приемника событий SharePoint в удаленный приемник событий.
Дополнительные сведения см. в статье Перечисление SPRemoteEventType.
Как работают удаленные приемники событий?
На следующем рисунке показано, как работают удаленные приемники событий:
Пользователь выполняет действие в SharePoint (например, изменяет элемент списка).
Затем SharePoint обращается к зарегистрированной веб-службе. Вы можете выполнять некоторые операции, например обновлять свойство элемента списка или серверную систему.
Веб-служба также может обратиться к службе контроля доступа, чтобы запросить собственный подписанный маркер для обратного вызова SharePoint. С помощью этого маркера можно выполнять удаленные действия из веб-службы в результате предыдущей операции над элементом списка или серверной системой.
Принцип работы приемников событий emote в SharePoint
Как отлаживать удаленные приемники событий?
См. статью Устранение неполадок и отладка удаленного приемника событий в надстройке SharePoint.
Можно ли запускать клиентский код (JavaScript) из удаленных приемников событий?
Нет, вы не можете запускать клиентский код (JavaScript) из удаленных приемников событий.
Существуют ли ограничения на размещение удаленного приемника событий или его URL-адрес?
Удаленный приемник событий может быть размещен в облаке или на локальном сервере, который не используется в качестве сервера SharePoint. URL-адрес производственного приемника не может использовать определенный порт. Это значит, что вам необходимо использовать порт 443 для протокола HTTPS (рекомендовано) или порт 80 для HTTP. Если вы используете HTTPS, приемник размещен локально, а надстройка находится в SharePoint Online, сервер размещения должен иметь доверенный сертификат, выданный центром сертификации. (Самозаверяющий сертификат подходит, только если надстройка расположена в локальной ферме SharePoint.)
Будет ли обработчик событий SharePoint 2010 работать в SharePoint после обновления?
Если пакет решения SharePoint 2010, содержащий обработчик событий, обновляется до SharePoint, то, в зависимости от ваших настроек, пакет решения может работать без изменений. Это касается и обработчика событий. Если решение SharePoint 2010 преобразуется в надстройку SharePoint, обработчик событий должен быть переписан как удаленный приемник событий. См. видео Перенос приемника событий SharePoint в удаленный приемник событий.