Изучение структуры манифеста приложения и пакета надстройки SharePoint
Структура пакета надстройки SharePoint
Пакет надстройки SharePoint — это файл с расширением APP, который соответствует стандарту Open Packaging Conventions (OPC). Панель инструментов поиска содержит перечисленные ниже элементы.
Манифест надстройки. Это обязательный файл с именем appmanifest.xml. Он сообщает SharePoint некоторые важные свойства надстройки, такие как название и необходимые для запуска разрешения. Дополнительные сведения о содержимом этого файла см. в разделе Файл манифеста надстройки SharePoint.
Пакеты решений SharePoint. Надстройка может дополнительно включать пакет решений SharePoint (WSP-файл), содержащий компоненты сайта надстройки. К последним могут относиться страницы, экземпляры списков, представления, документы, компоненты на уровне веб-сайта и другие компоненты SharePoint. (Дополнительные сведения о том, какие компоненты SharePoint можно включить в надстройку SharePoint, см. в разделе Типы компонентов SharePoint, которые могут быть в надстройке SharePoint.) WSP-файл также может содержать надстройки Office. Компоненты в WSP-файле развертываются на веб-сайте надстройки. Пример пакета надстройки, включающего пакет решений SharePoint, приведен в статье Создание надстройки с размещением у поставщика, которая включает пользовательский список SharePoint и тип контента.
Компоненты хост-сайта с дополнительными действиями или веб-частями надстройки. Кроме компонентов SharePoint, которые разворачиваются на сайте надстройки, надстройка SharePoint может также разворачивать одно или несколько дополнительных действий (элементов контекстного меню или расширений ленты) на хост-сайте. Для этого в пакет надстройки включается компонент, не входящий в WSP-файл пакета и разворачивающий компоненты, которые попадут на хост-сайт. Этот "свободный" компонент называется компонентом хост-сайта.
Части надстроек развертываются на хост-сайте таким же образом. Компонент хост-сайта состоит из стандартного файла feature.xml SharePoint и одного или нескольких связанных elements.xml файлов. Например, файл elements.xml для настраиваемого действия содержит разметку CustomAction для настраиваемого действия. Он также может включать разметку для частей надстройки. В функции хост-сайта могут находиться только эти два типа компонентов. Эти функции хост-сайта не отображаются в манифесте надстройки. Однако они являются "частями" в смысле OPC, и существует явная связь OPC между манифестом надстройки и каждым из этих файлов. Пример пакета надстройки, который включает функцию хост-сайта, см. в статье Создание пользовательских действий для развертывания с помощью надстроек SharePoint.
Примечание.
Администраторы клиента могут выполнять пакетную установку надстройки SharePoint на несколько веб-сайтов. Надстройка, установленная таким образом, называется надстройкой на уровне клиента. Если надстройка устанавливается не в пакетном режиме, а отдельно на каждый веб-сайт, то это надстройка на уровне Web (Интернет). Если компонент хост-сайта включает расширения ленты или веб-части надстройки, то при пакетной установке надстройки они не развертываются на хост-сайтах, так что только элементы контекстного меню развертываются с надстройками на уровне Tenant (Клиент).
Уровень надстройки не следует путать с уровнем компонента. Уровень компонента определяет, где будут развернуты элементы компонента. Возможные уровни: Farm (Ферма), WebApplication (Веб-приложение), Site (Сайт, т. е. семейство веб-сайтов) и Web (Интернет). Для компонентов в надстройках SharePoint (и для компонентов хост-сайтов, и для компонентов в WSP-файле в пакете надстройки) разрешен только вариант Web (Интернет).
Уровень надстройки относится к уровню, на котором установлена надстройка. Возможные уровни: Web (Интернет), когда надстройка установлена на одном или нескольких веб-сайтах по очереди, и Tenant (Клиент), когда надстройка установлена в пакетном режиме на несколько веб-сайтов в области клиента пользователя.
Дополнительные сведения об уровнях Tenant (Клиент) и Web (Интернет) см. в статье Области клиентов и области развертывания для надстроек SharePoint.
Файлы ресурсов для локализации (.resx). Это составляющие манифеста надстройки для локализации, которые включают название надстройки и составляющие компонентов хост-сайта в пакете надстройки. (Отдельные части пакета надстройки, находящиеся внутри собственных пакетов, такие как файлы .wsp, пакеты веб-сайтов Azure и манифесты надстроек, отличаются собственными процессами локализации, которые применяются точно так же, как если бы элементы, о которых идет речь, не входили в надстройку SharePoint). Пример пакета надстройки, содержащего файлы .resx для компонента хост-сайта, можно найти в статье Локализация надстроек SharePoint.
Манифесты надстроек Office. При необходимости пакет надстройки Office может включать один или несколько манифестов надстроек Office. Эту часть можно включить в пакет надстройки, только если надстройку планируется отправить в корпоративный каталог надстроек SharePoint, а не в общедоступный магазин. Дополнительные сведения см. в статье Публикация надстроек SharePoint.
Файл манифеста надстройки SharePoint
Каждая надстройка SharePoint содержит appmanifest.xml файл. appmanifest.xml сообщает SharePoint, что она должна знать о надстройке, и определяет наиболее важные свойства надстройки. Далее приводятся некоторые элементы, которые задаются в манифесте.
Внутреннее имя, идентификатор продукта и версия надстройки.
URL-адрес начальной страницы, которая открывается при запуске надстройки. Это может быть страница в веб-сайте надстройки, облачная страница или страница на веб-сервере независимого поставщика программного обеспечения.
Примечание.
При определенных обстоятельствах могут накладываться ограничения, из-за которых в элементе StartPage можно указывать не все типы файлов. Подробнее см. в статье Элемент StartPage (complexType PropertiesDefinition, манифест надстройки SharePoint). При объединении нескольких параметров запроса в значении StartPage необходимо использовать код амперсанда
&вместо&или точки с запятой, чтобы указать их вместе.Другие свойства надстройки. К ним относятся заголовок и языковые стандарты, поддерживаемые надстройкой (оба являются обязательными), URL-адреса служб, которые обрабатывают события после установки, обновления и предварительного удаления, а также веб-шаблон, используемый при создании веб-сайта надстройки.
Запросы разрешений, необходимых надстройке для доступа к ресурсам SharePoint вне сайта надстройки.
Идентификация субъекта надстройки в целях проверки подлинности и авторизации. Это субъект, который предоставляет разрешения. Это не требуется для надстройки, размещенной в SharePoint.
Список необходимых компонентов (при наличии), которые должны быть доступны для установки надстройки. Например, вам может потребоваться установить, лицензировать и активировать определенные компоненты или службы.
Примечание.
Файл манифеста надстройки — единственный обязательный элемент в пакете надстройки, но не все элементы в списке выше должны обязательно входить в этот файл.
Подробнее о разметке манифеста надстройки см. в статье Справочник по схеме для манифестов надстроек SharePoint. Эта статья не заменяет сведения из указанного статьи, в том числе информацию об обязательных элементах и атрибутах. Кроме того, обратите внимание, что схема манифестов надстроек SharePoint отличается от схемы манифестов надстроек Office. Дополнительные сведения можно найти в статье Справка по схеме для манифестов надстроек Office (версия 1.1).
Далее приводится пример файла appmanifest.xml. Обратите внимание, что в этом примере начальной страницей надстройки является страница ASP.NET, находящаяся на удаленном сервере, а не страница сайта SharePoint. URL-адрес этой страницы включает строку запроса, которая передает в удаленное веб-приложение URL-адрес хост-сайта. Часть {HostUrl} строки является маркером, который разрешается при запуске надстройки. Надстройка запрашивает разрешение на запись во все списки на хост-сайте. Субъектом надстройки, которому необходимо предоставить это разрешение, является удаленное веб-приложение.
В манифесте надстройки вам необходимо использовать элемент SupportedLocales или SupportedLanguages. Элемент SupportedLanguages устарел и теперь заменяется элементом SupportedLocales. Элемент SupportedLanguages будет работать даже после выпуска, однако следует воздерживаться от его использования. Дополнительные сведения об этих элементах см. в статьях Элемент SupportedLocales (complexType PropertiesDefinition, манифест надстройки SharePoint) и Элемент SupportedLanguages (complexType PropertiesDefinition, манифест надстройки SharePoint).
Примечание.
Значения атрибута Scope элемента AppPermissionRequest структурированы как универсальный код ресурса (URI), но фактически это строковые литералы. Ни одна часть значения Scope в примере ниже не является заполнителем. Дополнительные сведения о разрешениях см. в статье Разрешения для надстроек SharePoint.
<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
Version="1.0.0.0"
SharePointMinVersion="15.0.0.0"
Name="MySampleApp"
>
<Properties>
<Title>My Sample App</Title>
<StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
<SupportedLocales>
<SupportedLocale CultureName="en-US" />
</SupportedLocales>
</Properties>
<AppPermissionRequests>
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
</AppPermissionRequests>
<AppPrincipal>
<RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
</AppPrincipal>
</App>
Маркеры URL-адресов в манифесте надстройки
SharePoint предоставляет несколько маркеров, которые можно использовать в элементе StartPage и других местах в надстройках и компонентах надстроек для представления сведений, которые неизвестны до запуска надстройки. Инфраструктура SharePoint разрешает эти маркеры. Одни маркеры используются в начале URL-адреса, а другие можно использовать в URL-адресе в качестве значения параметра запроса. Эти маркеры и ряд других маркеров также можно использовать в различных контекстах разработки SharePoint.
Подробные сведения обо всех этих маркерах и о том, где их можно использовать, см. в статье Токены и строки URL-адресов в надстройках SharePoint. Общие сведения об остальных маркерах и URL-адресах в SharePoint см. в статье URL-адреса и маркеры в SharePoint.
Примечание.
Эти маркеры не используются в атрибуте Scope элемента AppPermissionRequest.