Преобразование надстройки SharePoint с автоматическим размещением в надстройку, размещаемую у поставщика
Microsoft SharePoint представил новый подход к расширению сайтов SharePoint в дополнение к предыдущему подходу, в котором использовались настройки на основе решений. Эта новая модель расширения для SharePoint, называемая моделью надстроек, позволяет разработчикам создавать настраиваемые реализации, которые можно развернуть в средах SharePoint независимо от того, где они выполняются локально, в SharePoint Online или в гибридном развертывании.
Разработчики могут создавать надстройки SharePoint двух разных типов. Надстройки первого типа (размещаемые в SharePoint) в основном выполняются в браузере, а все поддерживающие их ресурсы, например HTML, CSS, изображения и JavaScript, хранятся в SharePoint и поступают из него. Надстройки других типов попадают в категорию модели облачных надстроек (CAM), работают в основном за пределами SharePoint на других серверах и обмениваются данными с SharePoint, используя клиентскую объектную модель (CSOM) и REST API. Они создают удостоверение, используя популярный протокол OAuth 2.0, который поддерживается в SharePoint.
Используя модель надстройки, разработчики могут реализовывать надстройки одним из двух способов: в виде надстройки, размещаемой у поставщика, или надстройки с автоматическим размещением. Надстройки с автоматическим размещением появились в рамках ознакомительной программы при выпуске SharePoint, но в мае 2014 г. корпорация Майкрософт объявила о предстоящем закрытии этой программы и прекращении поддержки создания надстроек с автоматическим размещением. Это объявление см. в статье Обновление ознакомительной программы надстроек с автоматическим размещением.
В этой статье рассказывается о преобразовании и миграции надстройки с автоматическим размещением в надстройку с размещением у поставщика. Тем не менее, очень важно, чтобы разработчики понимали некоторые принципиальные различия между двумя подходами, так как это значительно упростит процесс преобразования.
Компоненты, необходимые для преобразования надстройки с автоматическим размещением в надстройку, размещаемую у поставщика
Основные понятия, которые необходимо знать, прежде чем выполнять преобразование надстройки с автоматическим размещением
Прежде чем выполнять преобразование надстройки с автоматическим размещением в надстройку, размещаемую у поставщика, необходимо изучить базовые сведения о надстройках SharePoint и о том, чем отличаются надстройки SharePoint, размещаемые в SharePoint, надстройки SharePoint, размещаемые у поставщика, и надстройки SharePoint с автоматическим размещением. Эти сведения есть в статьях, указанных в приведенной ниже таблице.
| Название статьи | Описание |
|---|---|
| Надстройки SharePoint | Изучите новую модель надстроек в SharePoint, с помощью которой можно создавать небольшие и удобные в использовании надстройки для пользователей. |
| Важные аспекты разработки и архитектуры для надстроек SharePoint | Узнайте обо всех аспектах архитектуры Надстройки SharePoint и Модель для надстроек SharePoint, включая варианты размещения надстроек, параметры пользовательского интерфейса, системы развертывания, систему безопасности и жизненный цикл. |
| Выбор шаблонов для разработки и размещения надстройки SharePoint | Узнайте о различных способах размещения надстроек SharePoint. |
| Хост-сайты, сайты надстроек и компоненты SharePoint в SharePoint | Узнайте о различиях между хост-сайтами и сайтами надстроек. Узнайте также, какие компоненты SharePoint могут быть включены в Надстройка SharePoint, которые разворачиваются на хост-сайте, на сайте надстройки, и о порядке развертывания сайта надстройки в изолированном домене. |
Преобразование надстройки
При преобразовании надстройки SharePoint с автоматическим размещением в надстройку, размещаемую у поставщика, изменяются два или три компонента:
- сама надстройка SharePoint;
- удаленное веб-приложение или службы;
- база данных SQL Microsoft Azure (если она есть) в надстройке.
При установке автоматически размещаемой надстройки SharePoint она автоматически развертывается на веб-сайте Azure и в базе данных SQL Azure. Однако удаленные веб-приложения и другие службы надстроек, размещаемых у поставщика, могут находиться на любой веб-платформе. В этой статье предполагается, что удаленные компоненты в автоматически размещаемой надстройке останутся службами Azure после ее преобразования в надстройку, размещаемую у поставщика.
В разделе ниже пошагово описан процесс преобразования надстройки с автоматическим размещением в надстройку, размещаемую у поставщика. Использованный пример надстройки с автоматическим размещением Customer Manager (Менеджер по работе с клиентами) прост. Это позволяет сконцентрироваться на действиях по преобразованию, а не на самой надстройке. Пример состоит из трех указанных ниже проектов.
CustomersDb — проект базы данных SQL, создающий необходимый файл *.dacpac. Обратите внимание на то, что в этом проекте не задана схема. Он используется просто для создания базы данных, так как схему создает веб-приложение ASP.NET.
CustomerManagerAH — надстройка SharePoint с автоматическим размещением, настроенная на включение проекта веб-приложения ASP.NET и приложения уровня данных SQL Azure в пакет конечной надстройки SharePoint.
CustomerManagerAHWeb — веб-приложение MVC ASP.NET, в случае которого используется Entity Framework Code First Migrations для создания схемы базы данных, а также для выполнения операций чтения и записи данных в базе данных.
Надстройка представляет собой веб-приложение MVC ASP.NET, которое может отображать сведения о пользователях из таблицы базы данных SQL Azure, а также добавлять новых пользователей. Это анонимное веб-приложение, с помощью которого кто угодно может просматривать и добавлять пользователей. Решение Visual Studio для автоматически размещаемой надстройки и связанных проектов можно скачать из следующего общедоступного репозитория: Autohosted-Migration-Code-Samples.
Процесс преобразования надстройки SharePoint с автоматическим размещением в надстройку, размещаемую у поставщика, предусматривает несколько действий. Все они описаны в указанных ниже разделах.
Развертывание базы данных SQL Azure
Создание веб-сайта Azure для размещения удаленного веб-приложения
Регистрация надстройки на сайте SharePoint
Обновление и развертывание веб-сайта Azure для удаленного веб-приложения
Изменение конфигурации проекта надстройки SharePoint
Развертывание базы данных SQL Azure
Первое действие в процессе преобразования надстройки с автоматическим размещением в надстройку, размещаемую у поставщика, — развертывание базы данных SQL Azure, которую использует веб-приложение ASP.NET. Существует много различных способов создать базу данных SQL Azure. Некоторые из них описаны на сайте документации Azure: Миграция базы данных SQL Server в базу данных SQL в облаке.
В описанном далее подходе используется модель развертывания надстройки уровня данных, так как это позволяет развернуть базу данных в надстройке SharePoint с автоматическим размещением. Она включает создание пакета надстройки уровня данных (DACPAC) и его использование для создания базы данных.
Создание базы данных SQL Azure
Откройте решение надстройки с автоматическим размещением в Visual Studio.
Щелкните правой кнопкой мыши проект базы данных CustomerDb, а затем нажмите кнопку Построить. В результате будет создан файл CustomerDb.dacpac в папке
[..]\bin\[debug | release].Создайте базу данных SQL Azure. Войдите на портал Azure. Когда загрузится панель мониторинга, перейдите по ссылке Базы данных SQL в поле.
Щелкните ссылку Серверы на верхней панели навигации, а затем нажмите кнопку Добавить в нижнем колонтитуле, как показано на рисунке ниже.
В открывшемся диалоговом окне Создание сервера выберите подписку Azure, в полях Имя для входа и Пароль укажите имя и пароль пользователя, у которого будут права на доступ к серверу, а в поле Область — ту же область, которую указывали при создании веб-сайта Azure. Запишите имя для входа и пароль, так как они потребуются вам позже.
После заполнения формы щелкните значок с галочкой в правом нижнем углу, чтобы создать базу данных. Пока создается сервер, единственные ресурсы, которые могут получить доступ к нему, — другие службы Azure. Запишите имя базы данных SQL Azure, так как оно потребуется вам на одном из следующих этапов.
Развертывание базы данных SQL Azure
Чтобы подключиться к базе данных SQL Azure и развернуть базу данных, необходимо создать правила брандмауэра, разрешающие трафик с компьютера, развертывающего базу данных. В противном случае попытки подключения к базе данных SQL Azure будут отклонены с ошибками, аналогичными показанной на рисунке ниже.
Чтобы создать правило брандмауэра, на портале Azure выберите ранее созданную базу данных SQL Azure и перейдите по ссылке Настройка на верхней панели навигации.
В разделе Разрешенные IP-адреса ваш IP-адрес будет отображаться так, как показано на приведенном ниже рисунке. Чтобы добавить правило брандмауэра, выберите пункт Добавить в разрешенные IP-адреса. В результате будут разрешены подключения к базе данных SQL Azure и развертывание базы данных. Щелкните Сохранить в нижнем колонтитуле.
Развертывание базы данных из Visual Studio с помощью пакета Azure SDK для .NET 2.3.
В Visual Studio откройте окно инструментов Обозреватель объектов SQL Server, щелкните правой кнопкой мыши узел SQL Server и выберите пункт Добавить SQL Server.
В диалоговом окне Подключение к серверу введите имя сервера в поле Имя сервера, выберите значение Проверка подлинности SQL Server в поле Проверка подлинности, а затем введите имя пользователя и пароль, которые вы указали при создании базы данных SQL Azure. В качестве имени сервера необходимо использовать полное доменное имя сервера (
[server-name].database.windows.net), как показано на рисунке ниже.
После подключения к базе данных SQL Azure разверните узел для добавленного сервера, щелкните правой кнопкой мыши узел Базы данных и выберите пункт Опубликовать приложение уровня данных. Откроется мастер публикации.
В разделе Исходное приложение уровня данных (.dacpac) нажмите кнопку Обзор и найдите DACPAC-файл, сгенерированный при создании проекта базы данных на предыдущем этапе. Убедитесь, что для параметра Имя базы данных задано значение CustomerDb.
Щелкните Опубликовать, чтобы опубликовать базу данных CustomerDb в службе "База данных SQL Azure".
Обновите окно инструментов Обозреватель объектов SQL Server в Visual Studio, чтобы отобразить базу данных CustomerDb в узле Базы данных.
Примечание.
То, как создана база данных для надстройки с автоматическим размещением, определяет, нужно ли выполнять дополнительные действия для ее развертывания в Azure. Дополнительные сведения см. в статье Создание баз данных и приложений уровня данных и управление ими в Visual StudioСоздание приложений уровня данных и управление ими
Действия после развертывания
Создав базу данных SQL Azure, скопируйте строку подключения, используемую для подключения к базе данных. Это можно сделать двумя способами.
Первый способ — войти на портал Azure и перейти к базе данных SQL Azure, созданной на предыдущем этапе (CustomerDb). Чтобы открыть список строк подключения, на странице Панель мониторинга базы данных нажмите Показать строки подключения. Создайте копию строки подключения ADO.NET для использования в будущем.
Другой способ получения строки подключения — использовать Visual Studio (если установлен пакет Azure SDK версии 2.3). В окне инструментов Обозреватель объектов SQL Server в Visual Studio выберите базу данных CustomerDb. Выбрав базу данных, найдите строку подключения в окне инструментов Свойства. Это то же значение, что и на портале Azure.
Создание веб-сайта Azure
Теперь нужно создать веб-сайт Azure, где будет размещено удаленное веб-приложения для размещаемой у поставщика надстройки. Это следует сделать в первую очередь, так как URL-адрес удаленного веб-приложения необходим для регистрации надстройки. Однако надстройку необходимо зарегистрировать в SharePoint до развертывания файлов веб-приложения ASP.NET, так как в результате регистрации создается два элемента (идентификатор и секрет клиента), необходимых для развертывания файлов веб-приложения ASP.NET.
Создание веб-сайта Azure
Войдите на портал Azure. После загрузки панели мониторинга перейдите по навигационной ссылке Веб-сайты в поле слева, а затем нажмите кнопку Создать в нижнем колонтитуле, как показано на приведенном ниже рисунке.
В мастере создания веб-сайта выберите Вычисление, Веб-сайт и Быстрое создание, а затем укажите URL-адрес и план размещения веб-сайтов. В завершение укажите область, в которой следует создать веб-сайт. Запомните выбранную область, так как именно ее необходимо будет использовать для базы данных SQL Azure, которую вы создадите позже.
Если тарифный план веб-хостинга еще не существует либо необходим новый тарифный план, выберите вариант Создать тарифный план веб-хостинга. На следующем рисунке показан пример.
После создания веб-сайта Azure запишите URL-адрес, используемый для этого сайта. На приведенных выше рисунках созданный сайт расположен по адресу
http://spahapptoph.azurewebsites.net.
Регистрация новой надстройки
Все надстройки SharePoint, созданные с использованием модели надстроек, необходимо зарегистрировать в ферме SharePoint или в области клиентов, в которой они размещены, чтобы создать доверие между SharePoint и удаленным веб-приложением. Этот процесс включает регистрацию нового субъекта надстройки в SharePoint с использованием указанных ниже значений.
- Идентификатор клиента — идентификатор надстройки.
- Секрет клиента — пароль надстройки.
- Название — название надстройки.
- Домен надстройки — домен верхнего уровня для удаленного веб-приложения.
Когда надстройка с автоматическим размещением устанавливается в SharePoint Online, Office 365 автоматически создает субъект надстройки. У него есть сведения об URL-адресе удаленного веб-приложения, так как он создает сайт автоматически. Кроме того, он использует идентификатор клиента и секрет клиента, добавляя их в файл web.config удаленного веб-приложения. В этом файле класс, предоставляемый корпорацией Майкрософт (в файле TokenHelper.cs или VB-файле), выполняет поиск идентификатора и секрета клиента при проверке запросов и проверке подлинности с помощью SharePoint.
В случае надстройки, размещаемой у поставщика, разработчику необходимо вручную ее зарегистрировать и вручную изменить содержимое файла web.config в веб-проекте ASP.NET.
Регистрация новой надстройки
Перейдите на страницу регистрации надстройки на веб-сайте SharePoint, на котором предполагается установить надстройку. Эта страница находится по адресу
http://[SharePoint-site-url]/_layouts/15/appregnew.aspx.На странице регистрации надстройки задайте для параметра Тип надстройки значение Надстройка, работающая на веб-сервере и нажмите две кнопки Создать, чтобы создать идентификатор клиента и секрет клиента.
Введите имя надстройки в поле Название, а затем в поле Домен надстройки укажите URL-адрес целевого веб-сайта Azure, созданного на предыдущем этапе. В завершение нажмите кнопку Создать.
Когда надстройка будет зарегистрирована, SharePoint отобразит сводку сведений, которые были использованы в форме для регистрации. Очень важно скопировать и сохранить эти сведения, особенно идентификатор и секрет клиента, так как они понадобятся нам в дальнейшем.
Обновление и развертывание веб-сайта Azure для удаленного веб-приложения
Теперь необходимо изменить конфигурацию удаленного веб-приложения так, чтобы его можно было развернуть в качестве надстройки, размещаемой у поставщика, а не автоматически размещаемой надстройки. Развернуть сайт ASP.NET на веб-сайте Azure можно несколькими способами, в том числе непосредственно из Visual Studio, автоматически из системы управления версиями (например, Visual Studio Team Services), из GitHub или даже с использованием испытанного протокола FTP. В этой статье мы используем Visual Studio. Чтобы можно было развернуть веб-приложение, сначала необходимо внести в него ряд изменений, благодаря которым оно сможет работать с надстройкой, размещаемой у поставщика.
Обновление проекта удаленного веб-приложения
Самые большие изменения веб-приложения MVC ASP.NET необходимо выполнить в файле web.config. В этом файле находятся три параметра в <узле appSettings> . Это параметры ClientId, ClientSecret и SqlAzureConnectionString. Первые два параметра используются классом, предоставленным корпорацией Майкрософт (в файле TokenHelper.cs или в VB-файле), для упрощения проверки подлинности и обмена данными с SharePoint из удаленного веб-приложения. Последняя, SqlAzureConnectionString, используется надстройкой для подключения к базе данных Azure SQL.
В автоматически размещаемой надстройке SharePoint среда Office 365 задает значения для этих параметров при создании веб-сайта Azure и базы данных SQL Azure, когда устанавливается надстройка. В надстройке, размещаемой у поставщика, необходимо задать эти параметры вручную перед развертыванием надстройки.
Первый способ сделать это — скопировать значения для трех параметров, указанных ранее в этой статье, и вставить их. Недостаток такого подхода заключается в том, что если потребуется изменить значения этих параметров, придется вручную редактировать содержимое файла web.config и повторно развертывать его на веб-сайте Azure.
Другой способ — просто очистить эти параметры (то есть оставить ключи параметров на своих местах, но задать в качестве значения атрибута value="" пустую строку) и определить их в параметрах веб-сайта Azure на портале Azure. При таком подходе можно менять параметры, не обновляя базу кода. Для этого выполните указанные ниже действия.
Войдите на портал Azure и перейдите на созданный ранее веб-сайт Azure.
На странице панели мониторинга веб-сайта Azure выберите пункт Настроить в верхнем меню навигации, а затем прокрутите содержимое окна до раздела Параметры надстройки.
Добавьте три новых параметра надстройки, используя их имена из файла web.config. Используйте значения, полученные на предыдущих этапах, для параметров ClientId, ClientSecret и SqlAzureConnectionString.
Убедитесь, что используется правильная и допустимая строка подключения к базе данных SQL Azure, так как при предоставлении строки подключения через портал Azure и Visual Studio атрибут пароля заменяется маской. Пароль с маской в строке подключения следует заменить правильным паролем, определенным при создании учетных данных входа для базы данных SQL Azure.
Развертывание удаленного веб-приложения на веб-сайте Azure
Теперь необходимо развернуть файлы веб-приложения MVC ASP.NET на веб-сайте Azure в качестве удаленного веб-приложения.
В Visual Studio щелкните веб-проект правой кнопкой мыши и выберите команду Опубликовать. Откроется диалоговое окно мастера публикации веб-страниц.
В этом диалоговом окне выберите пункт Веб-сайты Windows Azure и нажмите кнопку Опубликовать.
Выберите имя веб-сайта Azure, созданного на предыдущем этапе, как показано на приведенном ниже рисунке, нажмите кнопку ОК и убедитесь, что в URL-адресе сайта используется протокол HTTPS.
Выберите команду Проверить подключение и убедитесь, что параметры и подключение в порядке.
Выберите команду Опубликовать, после чего Visual Studio развернет веб-приложение ASP.NET на веб-сайте Azure.
Скопируйте URL-адрес сайта.
После того как веб-сайт будет развернут, Visual Studio запустит браузер, используемый по умолчанию для отладки, и в этом браузере откроется веб-сайт Azure. Сайт отобразится с ошибкой, так как контроллеры MVC ASP.NET содержат атрибут (SharePointContextFilter), использование которого предполагает, что SharePoint отправляет определенные значения контроллеру в заголовке HTTP-запроса POST. Но по умолчанию браузер отправил HTTP-запрос GET, так что эта ошибка закономерна.
Примечание.
Сведения о дополнительных вариантах развертывания веб-приложений ASP.NET на веб-сайте Azure см. в статье Развертывание локального репозитория Git в службе приложений Azure.
Личные домены и SSL-сертификаты для веб-сайтов Azure
Для всех веб-сайтов Azure используется следующее соглашение об именовании: http[s]://[site-name].azurewebsites.net. Корпорация Майкрософт уже добавила шаблон SSL-сертификата на все веб-сайты в домене *.azurewebsites.net, но пользователи могут самостоятельно сопоставлять личные домены со своими веб-сайтами Azure, а также использовать собственные SSL-сертификаты для этих личных доменов.
Сведения о том, как использовать личные домены, см. в статье Руководство. Сопоставление существующего настраиваемого DNS-имени со Службой приложений Azure.
Сведения о том, как добавлять настраиваемые SSL-сертификаты для личного доменного имени, см. в статье Привязывание существующего настраиваемого SSL-сертификата к веб-приложениям Azure.
Изменение конфигурации проекта надстройки SharePoint
Последний этап — изменение конфигурации проекта надстройки SharePoint. Проект Visual Studio для надстройки SharePoint имеет тип надстройки, настроенный для автоматического размещения. Необходимо заменить этот тип на тип надстройки, размещаемой у поставщика.
Изменение конфигурации проекта надстройки SharePoint
Откройте файл AppManifest.xml в проекте надстройки SharePoint и измените значение параметра Тип размещения, выбрав Размещение у поставщика вместо пункта Автоматическое размещение.
Для параметра Начальная страница надстройки укажите URL-адрес начальной страницы удаленного веб-приложения, который представляет собой URL-адрес веб-сайта Azure. Не забудьте включить в URL-адрес значение строки запроса {StandardTokens}, если оно еще не указано. Благодаря этому SharePoint добавит базовые маркеры строки запроса в URL-адрес, когда откроет удаленное веб-приложение.
Удалите ссылку на веб-приложение MVC ASP.NET в проекте надстройки SharePoint, выбрав проект надстройки SharePoint в обозревателе решений Visual Studio. В окне инструментов Свойства задайте для свойства Веб-проект значение (Нет), как показано на рисунке ниже.
На этом этапе необходимо вручную внести изменения в файл AppManifest.xml, так как некоторые параметры недоступны в конструкторе. Для этого сохраните все изменения, внесенные в файл AppManifest.xml, щелкните правой кнопкой мыши этот файл в обозревателе решений и выберите пункт Просмотреть код.
В представлении кода файла AppManifest.xml удалите две ссылки на проект веб-приложения MVC ASP.NET и проект приложения уровня данных SQL, так как они не нужны в надстройке SharePoint, размещаемой у поставщика.
Создайте GUID и замените им существующий GUID в атрибуте ProductId. Благодаря этому SharePoint будет "знать", что это новая надстройка, а не обновление существующей надстройки.
Важно!
Если использовался существующий атрибут ProductId, то при установке преобразованной надстройки SharePoint вернет ошибку "Указанная надстройка отличается от другой надстройки с такой же версией и идентификатором продукта".
Найдите элемент RemoteWebApplication> и обновите атрибут ClientId, чтобы он был таким же ИДЕНТИФИКАТОРом GUID, который был получен при регистрации надстройки в SharePoint и использовался в параметрах web.config надстройки веб-сайта< Azure.
После сохранения всех изменений в файле AppManifest.xml надстройка будет готова для тестирования в качестве надстройки SharePoint, размещаемой у поставщика. Разверните надстройку в ферме SharePoint или на сайте SharePoint Online, чтобы проверить, правильно ли были выполнены действия по преобразованию надстройки.