Использование удаленных приемников событий в SharePoint

Статья
04/08/2023

Обработка событий в модели надстроек SharePoint с помощью удаленных приемников событий. С помощью событий AppInstalled и AppUninstalling можно настраивать и удалять объекты SharePoint, а также другие приемники событий, которые нужны надстройке.

Область применения: надстройки для SharePoint | SharePoint 2013 | SharePoint Online

Важно! С января 2017 г. SharePoint Online поддерживает веб-перехватчики списка, которые можно использовать вместо удаленных приемников событий "-ed". Дополнительную информацию о веб-перехватчиках см. в статье Обзор веб-перехватчиков SharePoint. Обратите также внимание, что некоторые примеры веб-перехватчиков доступны в репозитории GitHub sp-dev-samples.

В примере Core.EventReceivers показано, как использовать надстройку, размещенную у поставщика, с удаленным приемником событий для обработки событий AppInstalled и AppUninstalling. События AppInstalled и AppUninstalling настраивают и удаляют объекты SharePoint, которые использует надстройка во время работы. Кроме того, обработчик событий AppInstalled добавляет обработчик событий ItemAdded в список. Используйте это решение, если вы хотите:

Настроить надстройку во время первого запуска с помощью события AppInstalled для настройки различных объектов SharePoint или дополнительных приемников событий, с которыми работает надстройка.
Заменить приемники событий, реализованные с помощью решений с кодом, имеющим полное доверие. В таких решениях вы можете запускать приемники событий на сервере SharePoint. В новой модели надстроек SharePoint невозможно запустить приемник событий на сервере SharePoint, поэтому необходимо реализовать удаленный приемник событий на веб-сервере.
Получать уведомления об изменениях, происходящих в SharePoint. Например, чтобы выполнять задачу при добавлении нового элемента в список.
Дополнить решение для журнала изменений. Использование удаленного приемника событий с журналом изменений обеспечивает более надежную архитектуру для обработки всех изменений, внесенных в базы данных контента, семейства веб-сайтов, сайты и списки SharePoint. Удаленные приемники событий выполняются незамедлительно, но так как это происходит на удаленном сервере, могут возникнуть ошибки связи. Шаблон журнала изменений позволяет обрабатывать все изменения, но приложение, которое этим занимается, обычно выполняется по расписанию (например, задание таймера). Это означает, что изменения не обрабатываются немедленно. При совместном использовании этих двух шаблонов, убедитесь, что реализован механизм предотвращения двойной обработки одного и того же изменения. Дополнительные сведения см. в статье Запрашивание журнала изменений SharePoint с помощью классов ChangeQuery и ChangeToken.

Примечание.

Надстройки, размещенные в SharePoint, не поддерживают удаленные приемники событий. Чтобы их использовать, нужна надстройка с размещением у поставщика. Не следует использовать удаленные приемники событий для сценариев синхронизации или длительных процессов. Дополнительные сведения см. в разделе Практическое руководство. Создание приемника событий надстройки.

Подготовка к работе

Чтобы приступить к работе, скачайте пример надстройки Core.EventReceivers из проекта шаблонов и методик разработчиков Office 365 на сайте GitHub.

Прежде чем запустить эту надстройку, сделайте вот что:

Убедитесь, что в свойствах проекта Core.EventReceivers установлено значение True. При установке параметра Handle App Installed and Handle App Uninstalling to True создается служба WCF, которая определяет обработчик событий AppInstalled и AppUninstalling . В проекте Core.EventReceivers откройте контекстное меню файла AppManifest.xml (щелкните его правой кнопкой мыши) и перейдите на вкладку Свойства. УстановленныеEventEndpoint и UninstallingEventEndpoint указывают на удаленный приемник событий, обрабатывающий события AppInstalled и AppUninstalling.
Присоединение удаленного приемника событий к объекту на хост-сайте обычно требует разрешения на управление только для этого объекта. Например, при подключении приемника событий к существующему списку надстройке нужно разрешение Управление только для параметра Список. В этом примере кода нужны разрешения Управление в области Интернет, ведь добавляется список и активируется функция на хост-сайте. Чтобы настроить разрешения на управление в Интернете:
1. Дважды щелкните файл Core.EventReceivers\AppManifest.xml.
2. Выберите Разрешения.
3. Убедитесь, что для области задано значение Интернет, а для разрешения — значение Управление.
Для запуска этого примера кода нужна подписка Azure. Чтобы использовать пробную версию, перейдите на страницу бесплатной пробной версии на 30 дней.
Создайте пространство имен служебной шины Azure.
1. Выполните действия, описанные в статье Создание пространства имен служебной шины.
2. Скопируйте основную строку подключения из только что созданного пространства имен служебной шины.
3. Вернитесь к Visual Studio.
4. Щелкните правой кнопкой мыши Core.EventReceivers >Properties>SharePoint.
5. Выберите Включить отладку с помощью служебная шина Microsoft Azure.
6. В служебная шина Microsoft Azure строке подключения вставьте строку подключения.
7. Выберите Сохранить.
Запустите пример кода и выполните такие дополнительные действия:
- Щелкните Доверять в окне Предоставление разрешений приложению .
- Закройте окно Предоставление разрешений для приложения .
- После завершения установки надстройки и службы WCF откроется браузер.
- Войдите на сайт Office 365. Отобразится начальная страница надстройки Core.EventReceivers.

Использование надстройки Core.EventReceivers

Чтобы посмотреть демоверсию примера кода Core.EventReceivers:

Запустите пример и на начальной странице выберите Вернуться на сайт.
Выберите Контент сайта.
Выберите Удаленные задания приемника событий.
Выберите новый элемент.
В поле Заголовок введите Contoso, а в поле Описание введите тест Contoso.
Вернитесь к списку и обновите страницу.
Убедитесь, что описание добавленного элемента обновлено до теста Contoso Обновлено ReR 192336, где 192336 является меткой времени.

В файле Services/AppEventReceiver.cs AppEventReceiver реализует интерфейс IRemoteEventService . Этот пример кода обеспечивает реализацию для метода ProcessEvent, так как он использует синхронные события. Если вы используете асинхронные события, нужно обеспечить реализацию для метода ProcessOneWayEvent.

ProcessEvent обрабатывает следующие удаленные события SPRemoteEventType:

События AppInstalled при установке надстройки. Когда возникает событие AppInstalled, метод ProcessEvent вызывает HandleAppInstalled.
События AppUninstalling при удалении надстройки. Когда возникает событие AppUninstalling, метод ProcessEvent вызывает свойство HandleAppUninstalling. Событие AppUninstalling запускается только тогда, когда пользователь полностью удаляет надстройку либо путем удаления надстройки из корзины сайта (для конечных пользователей), либо путем удаления надстройки из списка "Приложения в тестировании " (для разработчиков).
События ItemAdded при добавлении элемента в список. Когда возникает событие ItemAdded, метод ProcessEvent вызывает HandleItemAdded.

Примечание.

В свойствах проекта Core.EventReceiver доступны только свойства Handle App Installed и Handle App Uninstalling . В этом примере кода показано, как можно добавить обработчик событий ItemAdded в список на хост-сайте с помощью события AppInstalled во время установки надстройки.

Примечание.

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

public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {

            SPRemoteEventResult result = new SPRemoteEventResult();

            switch (properties.EventType)
            {
                case SPRemoteEventType.AppInstalled:
                    HandleAppInstalled(properties);
                    break;
                case SPRemoteEventType.AppUninstalling:
                    HandleAppUninstalling(properties);
                    break;
                case SPRemoteEventType.ItemAdded:
                    HandleItemAdded(properties);
                    break;
            }


            return result;
        }

HandleAppInstalled вызывает RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb в RemoteEventReceiverManager.cs.

 private void HandleAppInstalled(SPRemoteEventProperties properties)
        {
            using (ClientContext clientContext =
                TokenHelper.CreateAppEventClientContext(properties, false))
            {
                if (clientContext != null)
                {
                    new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
                }
            }
        }

AssociateRemoteEventsToHostWeb создает или включает различные объекты SharePoint, которые использует надстройка Core.EventReceivers. У вас могут быть другие требования. Свойство AssociateRemoteEventsToHostWeb делает следующее:

Включает функцию push-уведомлений с помощью Web.Features.Add.
Использует объект clientContext для поиска списка. Если список не существует, CreateJobsList создает его. Если список существует, List.EventReceivers используется для поиска существующего приемника событий с именем ItemAddedEvent.
Если приемник события ItemAddedEvent не существует:
- Создает экземпляр нового объекта EventReceiverDefinitionCreationInformation для создания нового удаленного приемника событий. Тип приемника событий ItemAdded добавляется в EventReceiverDefinitionCreationInformation.EventType.
- Задает в поле EventReceiverDefinitionCreationInformation.ReceiverURL URL-адрес удаленного приемника событий AppInstalled .
- Добавляет в список новый приемник событий с помощью List.EventReceivers.Add.

public void AssociateRemoteEventsToHostWeb(ClientContext clientContext)
        {
            // Add Push Notification feature to host web.
            // Not required but it is included here to show you
            // how to activate features.
            clientContext.Web.Features.Add(
                     new Guid("41e1d4bf-b1a2-47f7-ab80-d5d6cbba3092"),
                     true, FeatureDefinitionScope.None);


            // Get the Title and EventReceivers lists.
            clientContext.Load(clientContext.Web.Lists,
                lists => lists.Include(
                    list => list.Title,
                    list => list.EventReceivers).Where
                        (list => list.Title == LIST_TITLE));

            clientContext.ExecuteQuery();

            List jobsList = clientContext.Web.Lists.FirstOrDefault();

            bool rerExists = false;
            if (null == jobsList)
            {
                // List does not exist, create it.
                jobsList = CreateJobsList(clientContext);

            }
            else
            {
                foreach (var rer in jobsList.EventReceivers)
                {
                    if (rer.ReceiverName == RECEIVER_NAME)
                    {
                        rerExists = true;
                        System.Diagnostics.Trace.WriteLine("Found existing ItemAdded receiver at "
                            + rer.ReceiverUrl);
                    }
                }
            }

            if (!rerExists)
            {
                EventReceiverDefinitionCreationInformation receiver =
                    new EventReceiverDefinitionCreationInformation();
                receiver.EventType = EventReceiverType.ItemAdded;

                // Get WCF URL where this message was handled.
                OperationContext op = OperationContext.Current;
                Message msg = op.RequestContext.RequestMessage;
                receiver.ReceiverUrl = msg.Headers.To.ToString();

                receiver.ReceiverName = RECEIVER_NAME;
                receiver.Synchronization = EventReceiverSynchronization.Synchronous;

                // Add the new event receiver to a list in the host web.
                jobsList.EventReceivers.Add(receiver);
                clientContext.ExecuteQuery();

                System.Diagnostics.Trace.WriteLine("Added ItemAdded receiver at " + receiver.ReceiverUrl);
            }
        }

Когда элемент добавляется в список заданий удаленного приемника событий , ProcessEvent в AppEventReceiver.svc.cs обрабатывает событие ItemAdded , а затем вызывает HandleItemAdded. HandleItemAdded вызывает RemoteEventReceiverManager.ItemAddedToListEventHandler. ItemAddedToListEventHandler получает добавленный элемента списка и добавляет строку Кем обновлено: ReR в его описание.

 public void ItemAddedToListEventHandler(ClientContext clientContext, Guid listId, int listItemId)
        {
            try
            {
                List photos = clientContext.Web.Lists.GetById(listId);
                ListItem item = photos.GetItemById(listItemId);
                clientContext.Load(item);
                clientContext.ExecuteQuery();

                item["Description"] += "\nUpdated by RER " +
                    System.DateTime.Now.ToLongTimeString();
                item.Update();
                clientContext.ExecuteQuery();
            }
            catch (Exception oops)
            {
                System.Diagnostics.Trace.WriteLine(oops.Message);
            }

        }

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

Использование удаленных приемников событий в SharePoint

Подготовка к работе

Использование надстройки Core.EventReceivers

См. также

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