Использование приемников событий в SharePoint Foundation 2010 (часть 1 из 2)

Статья
06/24/2015

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

Дата последнего изменения: 9 марта 2015 г.

В этой статье
Основные сведения об использовании событий в SharePoint Foundation 2010
Работа с событиями в SharePoint Foundation 2010
Использование шаблона приемника событий в Visual Studio 2010
Дополнительные материалы

Предоставлено: Али Бадереддин (Ali Badereddin), корпорация Майкрософт | Ник Гатуччио (Nick Gattuccio), корпорация Майкрософт

Содержание

Основные сведения об использовании событий в SharePoint Foundation 2010
Работа с событиями в SharePoint Foundation 2010
Использование шаблона приемника событий в Visual Studio 2010
Дополнительные материалы

Основные сведения об использовании событий в SharePoint Foundation 2010

Приемник событий в Microsoft SharePoint Foundation 2010 представляет собой метод, вызываемый при возникновении запускающего действия над указанным объектом SharePoint. К запускающим событиям относятся такие события, как добавление, обновление, удаление, перемещение, возвращение и извлечение. К объектам SharePoint, которые прослушиваются на предмет возникновения событий, то есть к узлам приемника событий, относятся такие объекты, как семейства сайтов, списки и рабочие процессы.

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

Примечание
В Microsoft Visual Studio 2010 теперь предоставляется шаблон проекта приемника событий SharePoint, позволяющий автоматически выполнять многие задачи, описанные в данной статье. Чтобы предоставить полное описание действий, происходящих в конвейере события, шаблон проекта Visual Studio 2010 не использовался. Однако приведен краткий обзор использования Visual Studio 2010 для создания приемников событий и примеры применения этого шаблона.

В Microsoft Visual Studio 2010 теперь предоставляется шаблон проекта приемника событий SharePoint, позволяющий автоматически выполнять многие задачи, описанные в данной статье. Чтобы предоставить полное описание действий, происходящих в конвейере события, шаблон проекта Visual Studio 2010 не использовался. Однако приведен краткий обзор использования Visual Studio 2010 для создания приемников событий и примеры применения этого шаблона.

События впервые были реализованы в Windows SharePoint Services 2.0, но изначально поддерживались только для библиотек документов. События SharePoint тогда назывались накопителями событий. В Windows SharePoint Services 3.0 инфраструктура событий SharePoint приобрела свой современный вид, где используются управляемые приемники событий.

Приемники событий превосходят накопители событий по нескольким параметрам. Их удобнее использовать; они поддерживают больше типов событий; они могут использоваться для списков, типов контента, рабочих процессов и сайтов. В SharePoint Foundation 2010 были представлены новые события для списков и Интернета; кроме того, семейства сайтов теперь могут действовать как узлы событий, события "после" теперь могут быть синхронными, улучшены процедуры отмены события и олицетворения.

Принцип работы событий SharePoint — все необходимые сведения в одном абзаце

Приемник событий SharePoint привязан к объекту SharePoint — узлу событий — и реагирует на действия пользователя посредством запуска кода приемника событий. Код приемника событий компилируется в управляемую сборку — DLL-файл, который развертывается в глобальном кэше сборок.

В каких случаях можно использовать приемники событий?

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

Таблица 1. Операции, доступные для приемников событий

Объект	Операции
Семейство сайтов	Удаление
Веб-сайт	Создание Изменение URL-адреса Удаление
Список	Создание Удаление Получение сообщения электронной почты
Поле	Создание Обновление Удаление
Элемент	Создание Обновление Удаление Возврат Извлечение Перемещение файла Преобразование файла Добавление вложения Удаление вложения
Рабочий процесс	Запуск Завершение Откладывание

Что представляют собой приемники событий?

Приемник событий — это фрагмент управляемого кода, реагирующий на события SharePoint при выполнении особых запускающих действий над объектом SharePoint. К запускающим действиям относятся такие операции, как добавление, обновление, удаление, перемещение, возврат и извлечение.

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

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

Что представляют собой узлы событий?

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

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

Таблица 2. Базовые классы приемников событий и поддерживаемые события

Базовый класс приемников событий	Доступные типы узлов событий	Поддерживаемые события
SPWebEventReceiver	SPSite SPWeb	SiteDeleting SiteDeleted WebAdding WebProvisioned WebDeleting WebDeleted WebMoving WebMoved
SPListEventReceiver (списки)	SPSite SPWeb	ListAdding ListAdded ListDeleting ListDeleted
SPListEventReceiver (поля)	SPSite SPWeb SPList SPContentType	FieldAdding FieldAdded FieldDeleting FieldDeleted FieldUpdating FieldUpdated
SPItemEventReceiver	SPSite SPWeb SPList SPContentType	ItemAdding ItemAdded ItemDeleting ItemDeleted ItemUpdating ItemUpdated ItemFileConverted ItemFileMoving ItemFileMoved ItemCheckingIn ItemCheckedIn ItemCheckingOut ItemCheckedOut ItemAttachmentAdding ItemAttachmentAdded ItemAttachmentDeleting ItemAttachmentDeleted
SPEmailEventReceiver	SPSite SPWeb SPList	EmailReceived
SPWorkflowEventReceiver	SPSite SPWeb SPList SPContentType	WorkflowStarting WorkflowStarted WorkflowCompleted WorkflowPostponed

Основные понятия модели событий SharePoint

Кроме основных компонентов модели событий — приемников событий, узлов событий и событий — используются следующие ключевые понятия модели событий SharePoint.

События "до"

Событие "до" происходит перед выполнением текущей запрошенной операции. Например, событие ItemAdding является событием "до", которое происходит перед добавлением элемента в список SharePoint.

С другой стороны, события "до" происходят, когда действие выполняется до того, как SharePoint выполнит запись в базу данных контента. Этот механизм позволяет приемнику событий выполнять задачи до записи данных в базу данных. Хорошим примером использования событий "до" является выполнение проверки данных, поскольку события "до" происходят до записи данных. События "до" (или синхронные события) также можно использовать для отмены действий пользователя — например, если проверка данных заканчивается неудачей.

Код приемника событий, запускаемый событием "до", выполняется в том же потоке, что и код, выполняющий действие пользователя, которое его запустило. Поэтому события "до" всегда являются синхронными. События "до" можно определить по суффиксу "-ing", которым оканчиваются имена их членов — ItemAdding, ListAdding и т. д.

События "после"

Событие "после" происходит после выполнения текущей запрошенной операции. Например, событие ItemAdded является событием "после", которое происходит после добавления элемента в список SharePoint.

События "после" запускают приемники событий, которые выполняются после записи действий пользователя в базу данных контента; они вызывают код, который выполняется после внесения изменений в базу данных контента. Это позволяет выполнять операции в ответ на определенное действие пользователя.

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

События "после" можно определить по суффиксу "-ed", которым оканчиваются имена их членов — ItemDeleted, WebProvisioned и т. д.

Синхронные события

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

Все события "до" являются синхронными.

Асинхронные события

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

Привязка события

Привязка события (называемая также регистрацией события) может выполняться с использованием серверной объектной модели или XML-кода компонента. В следующих разделах приводятся подробные сведения о привязке событий в SharePoint Foundation.

Отмена события

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

Порядок приемников событий

Порядок приемников событий указывает порядок, в котором выполняются приемники событий в случаях, когда событие запускает несколько приемников событий. Например, если имеется два приемника событий ItemAdded, привязанных к одному и тому же списку (один из сборки "1", второй из сборки "2"), приемник событий, привязанный с меньшим порядковым номером, выполняется первым. Практическим примером является добавление приемника событий к системному списку, к которому уже привязан системный приемник событий. В этом случае новому приемнику событий назначается больший порядковый номер.

Конвейер событий SharePoint

На рис. 1 показано, как происходят события SharePoint в зависимости от синхронизации и последовательности.

Рисунок 1. Конвейер событий SharePoint

Конвейер событий SharePoint

Обратите внимание на следующие особенности.

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

После выполнения пользователем действия в пользовательском интерфейсе SharePoint и перед выполнением этого действия приложением SharePoint Foundation возникают синхронные события "до". Если имеется несколько синхронных событий "до", они создаются в порядке, заданном порядковыми номерами. Аналогичным образом синхронные события "после" происходят после выполнения SharePoint Foundation действия пользователя. Они также создаются в порядке, заданном порядковыми номерами. Как можно заметить, все синхронные события обрабатываются в том же потоке, в котором возникает действие пользователя.

Однако асинхронные события "после" обрабатываются во вторичных потоках.

Работа с событиями в SharePoint Foundation 2010

Создание события SharePoint выполняется в два основных этапа. Сначала необходимо определить операцию, которую требуется связать с событием, обеспечить наследование от соответствующего базового класса приемников событий, а затем написать свой код для приемника событий. Затем выполняется привязка события к соответствующему узлу событий SharePoint. (Этот этап называют также "регистрацией" события.)

После написания кода приемника событий и его компиляции в сборку со строгой подписью можно использовать один из двух способов для привязки события к узлу событий: можно использовать программные интерфейсы в объектной модели SharePoint или использовать XML-код компонента в решении SharePoint. Подробно обсудим оба способа.

Что лучше использовать: объектную модель или решения

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

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

Этот подход удобно использовать в режиме разработки, поскольку при его использовании удобно тестировать и вносить изменения в код приемника событий и привязку событий, а затем повторно собирать и развертывать проект. Однако при переносе кода с платформы разработки в рабочую среду эта простота исчезает, поскольку все необходимо развертывать вручную. Это означает, что необходимо скопировать код приемника событий (то есть управляемую сборку) на каждый интерфейсный веб-сервер в рабочей среде. Затем необходимо запустить исполняемый файл на одном из интерфейсных веб-серверов, а затем запустить iisreset на каждом интерфейсном веб-сервере для обновления кэша в рабочем процессе IIS (w3wp.exe). В крупномасштабной рабочей среде это может оказаться очень громоздкой (и рискованной) задачей.

Подход, основанный на использовании решений SharePoint, отличается способом привязки определения приемника событий. Более того, код приемника событий содержится в пакете развертывания (WSP-файле) наряду с файлами решения, процесс развертывания на ферме серверов является существенно более простым и более надежным, определение приемника событий становится доступным после активации компонента. Еще одно преимущество этого подхода заключается в возможности реализовать приемники событий в коде с неполным доверием (то есть в для песочницы). Приемники событий могут затем добавляться администраторами на уровне семейства сайтов. (До SharePoint 2010 только администраторы ферм имели возможность добавлять приемники событий.)

Таким образом, для развертывания требуется не больше действий, чем обычно выполняется при развертывании решения SharePoint с использованием WSP-файла. При выполнении одной команды развертывания осуществляется развертывание сборки приемника событий и привязки событий на всех интерфейсных веб-серверах после активации компонента.

Visual Studio 2010 еще более упрощает этот процесс. Использование Visual Studio обеспечивает гибкость подхода, основанного на использовании объектной модели, одновременно сохраняя экономичность подхода, основанного на использовании решений. В следующих разделах при описании работы с приемниками событий выделены способы, благодаря которым Visual Studio 2010 существенно упрощает этот процесс.

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

При использовании серверной объектной модели выполняются три основных действия: создание кода событий, привязка событий и изменение кода событий. В следующих разделах подробно рассматривается каждый этап.

Примечание
В следующих примерах используется Visual Studio, однако шаблоны проектов SharePoint, включенные в комплект Visual Studio 2010, не используются. Поэтому для повторения действий, описанных в этих примерах, можно использовать Visual Studio 2008 или Visual Studio 2010.

В следующих примерах используется Visual Studio, однако шаблоны проектов SharePoint, включенные в комплект Visual Studio 2010, не используются. Поэтому для повторения действий, описанных в этих примерах, можно использовать Visual Studio 2008 или Visual Studio 2010.

Создание событий с использованием объектной модели

Первый этап программирования своего приемника событий заключается в переопределении одного из базовых классов приемников событий. Пять базовых классов приемников событий SharePoint перечислены в таблице 2, представленной выше в этой статье, но все они наследуются от основного базового класса приемников событий, SPEventReceiverBase.

Создание приемника событий

В Visual Studio 2008 или Visual Studio 2010 создайте проект библиотеки классов C#, например, с именем MyReceiverAssembly.

Важно!
Если применяется Visual Studio 2010, не забудьте учесть использование Microsoft .NET Framework 3.5, поскольку SharePoint 2010 работает на основе .NET Framework 3.5. Этот параметр можно найти на вкладке Приложение в окне свойств проекта, как показано на рис. 2.

Если применяется Visual Studio 2010, не забудьте учесть использование Microsoft .NET Framework 3.5, поскольку SharePoint 2010 работает на основе .NET Framework 3.5. Этот параметр можно найти на вкладке Приложение в окне свойств проекта, как показано на рис. 2.

Рисунок 2. Учет использования .NET Framework 3.5

Определение платформы .NET Framework 3.5

На вкладке Построение в окне свойств проекта установите для параметра Конечная платформа значение x64 или Любой процессор, как показано на рис. 3. Не следует выбирать x86.

Рисунок 3. Выбор конечной платформы
На вкладке Подписывание в окне свойств проекта выберите Подписать сборку.
Щелкните Выберите файл ключа строгого имени, а затем щелкните Создать.
В диалоговом окне Создание ключа строгого имени в поле Имя файла ключей введите любое имя. Снимите флажок Защитить мой файл ключа паролем и нажмите кнопку ОК.
Переименуйте свой класс; например, MyReceiverClass.
Добавьте ссылку на библиотеку Microsoft.SharePoint.dll.
Создайте в своем классе ссылку на пространство имен Microsoft.SharePoint, вставив следующий оператор:

using Microsoft.SharePoint;
Задайте наследование от соответствующего подкласса класса SPEventReceiverBase в зависимости от события, которое требуется создать. (См. таблицу 2.) Например, если требуется создать и привязать событие ItemAdded, задайте наследование от базового класса SPItemEventReceiver следующим образом:

Public class MyReceiverClass : SPItemEventReceiver
Определите методы для событий, которые требуется реализовать. Удобно ввести public override и нажать клавишу ПРОБЕЛ. В Visual Studio средство IntelliSense выведет доступные события для класса, как показано на рис. 4.

Рисунок 4. Использование IntelliSense для просмотра доступных событий

Если было выбрано событие ItemAdded, получится следующее определение метода:
```
Public override void ItemAdded(SPItemEventProperties properties)
{
    base.ItemAdded(Properties;
}
```
Скомпилируйте библиотеку класса в DLL-файл.
Поместите DLL-файл в глобальный кэш сборок, перейдя к папке %WINDIR%\assembly и перетащив в нее свою сборку.

Если появится сообщение об отказе в доступе или возникнет другая неполадка, мешающая перетащить сборку в кэш, можно использовать следующую процедуру.
1. Убедитесь, что на компьютере установлены разработки SharePoint в Visual Studio 2010.
2. Откройте окно командной строки Visual Studio.
3. Введите команду gacutil /i и путь к сборке. Если операция выполнена успешно, появится сообщение "Сборка успешно добавлена в кэш".
4. Чтобы убедиться, что сборка добавлена, введите в командной строке следующую команду, которая позволяет просмотреть список всех сборок, находящихся в указанном каталоге кэша сборок (в данном случае в каталоге MyReceiverAssembly):
  
  gacutil /l MyReceiverAssembly

Привязка событий с использованием объектной модели

При использовании объектной модели SharePoint Foundation можно привязать (зарегистрировать) любой объект, имеющий свойство EventReceivers. Свойство EventReceivers относится к типу SPEventReceiverDefinitionCollection, что упрощает добавление определений приемников событий к узлам событий. Ниже приведен список объектов SharePoint, которые имеют это свойство и могут служить узлами событий.

SPSite (SPSite.EventReceivers)
SPWeb (SPWeb.EventReceivers)
SPList (SPList.EventReceivers)
SPContentType (SPContentType.EventReceivers)
SPFile (SPFile.EventReceivers)
SPWorkflow (SPWorkflowEventReceivers())

Привязка приемника событий

В Visual Studio 2008 или Visual Studio 2010 создайте проект консольного приложения на языке C#, например, с именем RegisterEvents.

Добавьте ссылку на библиотеку Microsoft.SharePoint.dll.
Создайте в своем классе ссылку на пространство имен Microsoft.SharePoint, вставив следующий оператор:

using Microsoft.SharePoint;
Добавьте новый элемент типа SPEventReceiverDefinition в коллекцию EventReceivers для указанного объекта следующим образом:

SPEventReceiverDefinition def = list.EventReceivers.Add();
Чтобы получить полное имя сборки, созданной при выполнении предыдущей процедуры, перейдите в глобальный кэш сборок, найдите сборку, щелкните запись сборки правой кнопкой мыши и выберите пункт Свойства. Окно свойств должно быть таким, как на рис. 5.

Рисунок 5. Свойства сборки в глобальном кэше сборок
Скопируйте значения из окна свойств, чтобы указать полное имя, версию, язык и региональные параметры и маркер открытого ключа. В этом примере исходный код имеет следующий вид:

def.Assembly = "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral,PublicKeyToken=12e5e5525fb3d28a";
Задайте значение свойства Class. Свойство Class представляет полное имя класса, содержащего приемник событий, в формате пространство_имен.класс. В этом примере исходный код имеет следующий вид:

def.Class = "MyReceiverAssembly.MyReceiverClass";
Задайте значение свойства Type. В этом примере исходный код имеет следующий вид:

def.Type = SPEventReceiverType.ItemAdded;
Задайте значение свойства Name. Это свойство является необязательным. Можно предоставить имя для определения приемника событий или игнорировать это значение. В этом примере исходный код имеет следующий вид:

def.Name = "My ItemAdded Event Receiver";
Задайте значение свойства Synchronization. Это свойство является необязательным. Если не указать значение этого свойства, для него устанавливается значение Default (то есть SPEventReceiverSynchronization.Default). Поведением по умолчанию для событий "до" является синхронное, а для событий "после" — асинхронное. В этом примере исходный код имеет следующий вид:

def.Synchronization = SPEventReceiverSynchronization.Synchronous;
Задайте значение свойства SequenceNumber. Это свойство является необязательным. Это свойство используется для указания порядка, в котором следуют события, когда в определении приемника событий имеется несколько событий. Если не указать это значение, по умолчанию устанавливается значение 10000. Можно задать любое значение от 0 до (216)-1.
Сохраните определение приемника событий в базе данных контента SharePoint, добавив следующий оператор:

def.Update();

Важно!
Если применяется Visual Studio 2010, не забудьте учесть использование Microsoft .NET Framework 3.5, поскольку SharePoint 2010 работает на основе .NET Framework 3.5. Этот параметр можно найти на вкладке Приложение в окне свойств проекта, как показано на рис. 2.

Ниже приведен весь исходный код описанной выше процедуры. При выполнении этого кода событие регистрируется в списке задач сайта https://localhost. Когда в этом списке создается новый элемент, запускается созданное событие ItemAdded.

using (SPSite site = new SPSite("https://localhost"))
{
    using (SPWeb web = site.OpenWeb())
    {
        SPList list = web.Lists["Tasks"];
        SPEventReceiverDefinition def = list.EventReceivers.Add();
        def.Assembly = 
          "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=12e5e5525fb3d28a";
        def.Class = "MyReceiverAssembly.MyReceiverClass";
        def.Type = SPEventReceiverType.ItemAdded;
        def.Name = "My ItemAdded Event Receiver";
        def.Synchronization = SPEventReceiverSynchronization.Synchronous;
        def.SequenceNumber = 1000;
        def.Update();
    }
}

Изменение событий

Модель событий SharePoint упрощает изменение и повторное развертывание кода приемника событий. Далее приведены инструкции по внесению изменений в пример проекта MyReceiverAssembly.

Обновление приемника событий

В Visual Studio откройте свой проект (например, проект MyReceiverAssembly) и внесите свои изменения.
Перестройте проект, чтобы создать новое построение DLL-файла.
Поместите новое построение DLL-файла в глобальный кэш сборок. Не забудьте перезаписать или удалить предыдущий DLL-файл.
Запустите iisreset, чтобы очистить кэш IIS и таким образом загрузить новую версию сборки в глобальный кэш сборок. Это действие гарантирует учет внесенных изменений в SharePoint.

Использование решений SharePoint

Альтернативой использованию объектной модели SharePoint для создания и развертывания приемников событий является использование решений SharePoint. В этом разделе последовательно описывается процесс создания решения приемника событий вручную.

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

Фактическое различие между этими двумя способами реализации событий заключается в привязке, для чего используется компонент SharePoint, развертываемый в файле решения (с расширением WSP).

Привязка событий с использованием решений

Следующая процедура позволяет создать компонент SharePoint, принимающий образец события — событие ItemAdded, которое было создано в DLL-файле MyReceiverAssembly, — и привязать его к списку задач на веб-сайте, на котором требуется активировать этот компонент.

Создание компонента SharePoint

Создайте папку с таким же именем, что и у компонента.
В новой папке создайте два XML-файла с именами feature.xml и eventbinder.xml.

Включите IntelliSense в этих XML-файлах, для чего добавьте в свойствах файла ссылку на файл конечной схемы (с расширением XSD), который расположен в каталоге …/TEMPLATE/XML/wss.xsd.

Обычно требуется повторно создавать эту ссылку каждый раз, когда открывается XML-файл. Однако при работе в проекте Visual Studio достаточно добавить файл схемы в проект.

Если часто создавать много CAML-файлов в нескольких проектах Visual Studio, этот процесс может оказаться трудоемким. В качестве альтернативы можно просто загружать XSD-файл всякий раз, когда открывается XML-файл, содержащий ссылку на данную схему. Для этого необходимо выполнить следующие действия.

Найдите XML-файл с именем Catalog.xml в папке, в которой установлено приложение Visual Studio, обычно это папка C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas.
Создайте ссылку на файл схемы wss.xsd в файле Catalog.xml, добавив следующий тег. Убедитесь, что значение href правильно указывает расположение файла wss.xsd.

<Schema href="C:/Program Files/Common Files/Microsoft Shared/Web Server Extensions/12/TEMPLATE/XML/wss.xsd" targetNamespace="https://schemas.microsoft.com/sharepoint/" />

Совет
При использовании Visual Studio 2010 шаг 3 можно пропустить. Когда открывается XML-файл, в котором содержится атрибут xmlns="https://schemas.microsoft.com/sharepoint/", Visual Studio 2010 автоматически добавляет ссылку на файл wss.xsd и таким образом включает IntelliSense.

При использовании Visual Studio 2010 шаг 3 можно пропустить. Когда открывается XML-файл, в котором содержится атрибут xmlns="https://schemas.microsoft.com/sharepoint/", Visual Studio 2010 автоматически добавляет ссылку на файл wss.xsd и таким образом включает IntelliSense.

В файле feature.xml создайте элемент <Feature>. Задайте для атрибута xmlns значение "https://schemas.microsoft.com/sharepoint/", для атрибута Id — идентификатор GUID, для атрибута Scope — значение "Web", а для атрибута Title — значение "EventBinderFeature".

Важно!
Для атрибута Id необходимо предоставить допустимый идентификатор GUID, который можно получить в Visual Studio, запустив программу guidgen.exe.

Добавьте в элемент <Feature> элемент <ElementManifests>.
Добавьте в элемент <ElementManifests> элемент <ElementManifest>. Задайте для атрибута Location значение "eventbinder.xml".
В файле eventbinder.xml создайте элемент <Elements>. Задайте для атрибута xmlns значение "https://schemas.microsoft.com/sharepoint/".
Добавьте в элемент <Elements> элемент <Receivers>. Задайте для атрибута ListUrl значение "Tasks".
Добавьте в элемент <Receivers> элемент <Receiver>.
Добавьте в элемент <Receiver> следующие элементы с соответствующими значениями:
- <Assembly>
- <Class>
- <Type>
- <Name>
- <Synchronization>
- <SequenceNumber>

После выполнения вышеописанной процедуры файл feature.xml должен иметь следующий вид.

<Feature Id="E54C7FF5-1DF3-4B0B-8FFF-DB3185ECE8A6" 
         Scope="Web" 
         Title="Event Binder Feature"
         xmlns="https://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementManifest Location="eventbinder.xml" />
  </ElementManifests>
</Feature>

Файл eventbinder.xml должен иметь следующий вид.

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Receivers ListUrl="Lists/Tasks">
    <Receiver>
      <Assembly>MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, 
        PublicKeyToken=12e5e5525fb3d28a</Assembly>
      <Class>MyReceiverAssembly.MyReceiverClass</Class>
      <Type>ItemAdded</Type>
      <Name>My ItemAdded Event Receiver</Name>
      <Synchronization>Synchronous</Synchronization>
      <SequenceNumber>1000</SequenceNumber>
    </Receiver>
  </Receivers>
</Elements>

Упаковка решения

Для развертывания приемников событий в установленной копии SharePoint необходимо собрать файлы в файл пакета решения (с расширением WSP). WSP-файл представляет собой обычный CAB-файл с расширением имени WSP.

В файле манифеста решения содержатся указания для SharePoint о том, что следует сделать с файлами, упакованными в WSP-файл. Например, элемент <FeatureManifest> указывает, что данная папка относится к компоненту SharePoint и должна быть развернута в каталог %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES и установлена на ферме серверов. Аналогичным образом, элемент <Assembly> указывает, что данный файл является сборкой; его атрибут DeploymentTarget указывает местоположение для развертывания сборки — глобальный кэш сборок или папка bin веб-приложения.

Подготовьте, создайте и измените файл manifest.xml следующим образом.

Подготовка контента решения

Создайте папку с именем "EventSolution".
Скопируйте папку компонента EventBinder в папку EventSolution.
Скопируйте сборку MyReceiverAssembly.dll в папку EventSolution.
Создайте XML-файл с именем "manifest.xml" в папке EventSolution.

Внесение изменений в файл manifest.xml

В файле manifest.xml создайте элемент <Solution>. Задайте для атрибута xmlns значение "https://schemas.microsoft.com/sharepoint/", задайте для атрибута SolutionId идентификатор GUID, а для атрибута Title — значение "Event Receiver Solution".
Добавьте в элемент <Solution> элемент <FeatureManifests>.
Добавьте в элемент <FeatureManifests> элемент <FeatureManifest>. Задайте для атрибута Location значение "EventBinder\feature.xml".
Добавьте в элемент <Solution> элемент <Assemblies>.
Добавьте в элемент <Assemblies> элемент <Assembly>. Задайте для атрибута Location значение "MyReceiverAssembly", а для атрибута DeploymentTarget — значение "GlobalAssemblyCache".

Файл manifest.xml должен теперь иметь следующий вид.

<Solution SolutionId="11C76135-CEEC-475B-9A93-67E5EF151B3C"
          Title="Event Receiver Solution"
          xmlns="https://schemas.microsoft.com/sharepoint/">
  <FeatureManifests>
    <FeatureManifest Location="EventBinder\feature.xml"/>
  </FeatureManifests>
  <Assemblies>
    <Assembly Location="MyReceiverAssembly" 
              DeploymentTarget="GlobalAssemblyCache">
    </Assembly>
  </Assemblies>
</Solution>

Теперь, когда контент решения подготовлен, остается только создать файл DDF (Diamond Directive File). В DDF-файле содержатся сведения, используемые программой Microsoft Cabinet Maker (makecab.exe) для определения способа упаковки и сжатия файлов в CAB-файл. (Сам DDF-файл в CAB-файл не включается.)

Создание DDF-файла

В папке EventSolution создайте файл с именем "cab.ddf".

Откройте файл cab.dff в текстовом редакторе, например в Блокноте, и добавьте следующие сведения.

;
.OPTION EXPLICIT
.Set CabinetNameTemplate=MyEventSolution.wsp 
.set DiskDirectoryTemplate=CDROM
.Set CompressionType=MSZIP
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package
manifest.xml manifest.xml
MyReceiverAssembly.dll MyReceiverAssembly.dll
EventBinder\feature.xml EventBinder\feature.xml
EventBinder\EventBinder.xml EventBinder\EventBinder.xml

Сохраните файл.

Важно!
Убедитесь, что первая строка в DDF-файле начинается с точки с запятой.

Директива OPTION EXPLICIT задает явное объявление всех переменных в данном файле. Если задать для атрибута UniqueFiles значение "ON", то конечные файлы буду уникальны. "ON" является значением по умолчанию, поскольку повторное использование одного и того же имени файла обычно означает, что один и тот же файл случайно был включен дважды, что приводит к неэффективному использованию места на диске.

Последние четыре строки в этом DDF-файле относятся к сопоставлению файлов: первое имя в каждой строке является источником, а второе — конечным файлом.

Чтобы создать файл пакета решения, откройте окно командной строки, перейдите к папке EventSolution и введите следующую команду:

makecab /F cab.ddf

Программа Cabinet Maker создает WSP-файл во вложенной папке Package папки EventSolution. Имя нового файла — MyEventSolution.wsp.

Развертывание решения

SharePoint 2010 предоставляет два вида решений: решения фермы и решения для песочницы. Изолированные решения важны, поскольку они позволяют администратору семейства сайтов загружать и активировать решения в рамках семейства сайтов. Благодаря использованию решений для песочницы больше нет необходимости в доступе с компьютера к WFE-файлам.

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

Примечание
В SharePoint 2010 средство Windows PowerShell заменяет средство администрирования Stsadm.exe. Можно по-прежнему использовать Stsadm для развертывания решений фермы, но рекомендуется использовать Windows PowerShell. Использовать Stsadm для развертывания решений для песочницы невозможно.

В SharePoint 2010 средство Windows PowerShell заменяет средство администрирования Stsadm.exe. Можно по-прежнему использовать Stsadm для развертывания решений фермы, но рекомендуется использовать Windows PowerShell. Использовать Stsadm для развертывания решений для песочницы невозможно.

Развертывание решения фермы

Загрузите решение в хранилище решений фермы, выполнив следующую команду Windows PowerShell:

Add-SPSolution -LiteralPath full_path_to_solution
Активируйте решение, выполнив следующую команду:

Install-SPSolution solution_name.wsp -GACDeployment

Развертывание изолированного решения

Загрузите решение в коллекцию решений семейства сайтов, выполнив следующую команду Windows PowerShell:

Add-SPUserSolution -LiteralPath full_path_to_solution -Site siteUrl
Активируйте решение, выполнив следующую команду:

Install-SPUserSolution solution_name.wsp -Site siteUrl

Когда решение развернуто, компоненты копируются в папку TEMPLATE\FEATURES, управляемые сборки помещаются в глобальный кэш сборок, а другие файлы помещаются в соответствующие папки в каталоге TEMPLATES. Теперь можно выполнить активацию компонентов.

Если требуется отозвать решение, используйте одну из следующих команд Windows PowerShell:

Решение фермы: Uninstall-SPSolution solution_name.wsp
Изолированное решение: Uninstall-SPUserSolution solution_name.wsp -Site siteUrl

После отзыва решение можно удалить с помощью одной из следующих команд:

Решение фермы: Remove-SPSolution solution_name.wsp
Изолированное решение: Remove-SPUserSolution solution_name.wsp -Site siteUrl

Использование шаблона приемника событий в Visual Studio 2010

В Visual Studio 2010 предоставляется расширенный набор шаблонов проектов SharePoint на языках Microsoft Visual Basic и C#, включая один шаблон для приемников событий SharePoint. Этот шаблон проекта упрощает обработку событий для таких объектов SharePoint, как сайты, списки, рабочие процессы и другие распространенные элементы.

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

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

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

Создание приемника событий SharePoint с использованием шаблона проекта приемника событий Visual Studio

В Visual Studio 2010 создайте новый проект с использованием шаблона приемника событий SharePoint 2010.
Выберите уровень доверия для своего решения SharePoint в зависимости от реализации кода приемника событий. Если для решения не требуется доступ к диску или сети или доступ на уровне системы, рекомендуется использовать вариант решения для песочницы, поскольку его проще реализовать и он с большей вероятностью будет использоваться.
Выберите события, которые требуется переопределить. В описываемом случае требуется переопределить событие ItemAdded и привязать его к списку задач.
- Какой тип приемников событий требуется? События элементов списка.
- Какой элемент должен быть источником событий? Задачи.
- Необходимо обрабатывать следующие события: добавлен элемент.
Нажмите кнопку Готово.
Добавьте в событие ItemAdded свой код.
В строке меню щелкните Построение, а затем — Развернуть решение.

Ваше решение упаковано, добавлено и развернуто. Можно даже установить точку останова в коде приемника событий и выполнить отладку.

Чтобы ознакомиться с несколькими практическими примерами использования модели событий SharePoint, прочтите вторую часть данной статьи: Использование приемников событий в SharePoint Foundation 2010 (часть 2 из 2).

Дополнительные материалы

Дополнительные сведения см. в следующих документах:

Использование приемников событий в SharePoint Foundation 2010 (часть 1 из 2)

Основные сведения об использовании событий в SharePoint Foundation 2010

Принцип работы событий SharePoint — все необходимые сведения в одном абзаце

В каких случаях можно использовать приемники событий?

Что представляют собой приемники событий?

Что представляют собой узлы событий?

Основные понятия модели событий SharePoint

Конвейер событий SharePoint

Работа с событиями в SharePoint Foundation 2010

Что лучше использовать: объектную модель или решения

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

Создание приемника событий

Привязка приемника событий

Обновление приемника событий

Использование решений SharePoint

Создание компонента SharePoint

Подготовка контента решения

Внесение изменений в файл manifest.xml

Создание DDF-файла

Развертывание решения фермы

Развертывание изолированного решения

Использование шаблона приемника событий в Visual Studio 2010

Создание приемника событий SharePoint с использованием шаблона проекта приемника событий Visual Studio

Дополнительные материалы

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