Краткий обзор объектной модели SharePoint

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

Примечание.

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

В этой статье мы немного отвлечемся от программирования и кратко рассмотрим клиентскую объектную модель (CSOM) SharePoint. Это большая модель. Она хорошо задокументирована на сайте MSDN в виде справочных статей, инструкций и примеров кода. В этой статье мы предоставим вам только самые поверхностные сведения. Тем не менее благодаря даже такому краткому описанию большая часть кода, с которым вы столкнетесь в этой серии статей, станет намного понятнее.

Иерархия контента

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

Объект	Класс	Замечания
Локальная ферма SharePoint или подписка на SharePoint Online (также называемая клиентом)		К этому уровню CSOM можно получить только ограниченный программный доступ. Например, нет классов Farm, Subscription или Tenant. (в серверной объектной модели SharePoint, которую невозможно использовать в надстройках, имеется программный доступ к этим объектам.)
Семейство веб-сайтов	Site	Семейство веб-сайтов, сгруппированных вместе большей частью по причинам, связанным с администрированием, а также для размещения компонентов SharePoint, например эталонных страниц с фирменным оформлением или пользовательских групп безопасности, которые можно применить ко всем дочерним веб-сайтам. Все веб-сайты принадлежат каким-либо семействам веб-сайтов.
веб-сайт	Web	Набор страниц и компонентов SharePoint. В нем могут содержаться вложенные веб-сайты.
список	List	На этом уровне размещаются библиотеки документов и другие типы библиотек файлов. Библиотека документов — это особый тип списка, в котором каждая строка содержит вложенный документ, а в других столбцах содержатся данные об этом документе, например сведения об авторе, дате и времени последнего изменения документа и о том, кто последним извлекал его.
элемент списка	ListItem	Строка в списке, то есть элемент списка, с определенными значениями в полях строки. Также имеет тип . См. следующую строку.
элемент списка	Тип контента	Тип элемента списка. Представлен классом ContentType. В своей основе каждый тип элемента списка это набор столбцов и метаданных. Самый простой тип содержимого встроенный Item. Все другие типы содержимого являются производными от типа Item. В SharePoint имеется много встроенных типов содержимого, например Event и Announcement.
столбец	Field	Объект Field включает не только информацию о базовом для него типе данных, но и сведения о том, каким образом форматировать и отображать данные в формах, например в формах создания, отображения и изменения элементов списка.

Вы можете программным способом создавать собственные списки, типы контента, типы столбцов и элементы списков.

Помимо доступа к контенту CSOM предоставляет доступ к пользователям, группам, ролям и разрешениям, таксономии, поиску и многому другому.

Клиентская среда выполнения и пакетная обработка

В CSOM используется система пакетной обработки. Она преобразовывает блоки управляемого кода в XML и отправляет их на сервер в одном HTTP-запросе. Для каждой команды система совершает вызов соответствующей серверной объектной модели, а сервер возвращает клиенту отклик в формате нотации объектов JavaScript (JSON).

Код SharePoint на клиенте начинается с получения клиентом объекта контекста, представляющего текущий контекст запроса, который включает идентификатор веб-сайта SharePoint (и его родительского семейства веб-сайтов). С помощью этого контекста вы можете получить доступ к объектам CSOM. Обратите внимание на

  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
      // CRUD operation or query code goes here.

      clientContext.ExecuteQuery();
  }

указанные ниже особенности этого кода.

• Объект spContext имеет тип SharePointContext и определен в файле SharePointContext.cs (или в файле SharePointContext.vb), который создается пакетом "Инструменты разработчика Office для Visual Studio". Вы можете изменять этот файл, но это требуется не так и часто. Для многих проектов надстройки SharePoint этот файл и файл TokenHelper.cs (или файл TokenHelper.vb), который также создается с помощью этих инструментов, эффективно работает в качестве расширений CSOM.

• Объект clientContext относится к типу ClientContext модели CSOM.

• Метод ExecuteQuery объединяет код операции CRUD в XML-сообщение, которое затем отправляет на сервер SharePoint. Там оно преобразуется в эквивалентный код серверной объектной модели, а затем выполняется.

В одной из предыдущих статей этой серии был пример этого шаблона (в приведенном ниже методе GetLocalEmployeeName).

private string GetLocalEmployeeName()
{
    ListItem localEmployee;

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
        localEmployee = localEmployeesList.GetItemById(listItemID);
        clientContext.Load(localEmployee);
        clientContext.ExecuteQuery();
    }
    return localEmployee["Title"].ToString();
}

Обратите внимание на указанные ниже особенности этого метода.

• Первые две строки в блоке using получают ссылки на список и объект элемента списка. Но на самом деле, когда эти строки выполняются в клиентской среде выполнения SharePoint, они просто преобразовываются в формат XML. Метод ExecuteQuery отправляет полученный XML на сервер.

• Метод Load добавляет дополнительную информацию в сообщение: он сообщает серверу, что указанный объект необходимо отправить на клиент. Метод ExecuteQuery получает этот объект (в виде JSON) и использует его для инициализации переменной localEmployee в клиенте. Последующий клиентский код затем ссылается на этот объект ListItem и его члены. Как вы видите, следующая строка ссылается на значение поля "Title" элемента. Если не вызван метод Load, то эта срока приведет к исключению, так как чтобы этот объект появился на стороне клиента, его необходимо загрузить.

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

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