Использование асинхронных операций в надстройках SharePoint
Реализуйте асинхронные операции в надстройках SharePoint с помощью веб-заданий Microsoft Azure.
Область применения: SharePoint 2013 | надстройки SharePoint | SharePoint Online
В примере Core.QueueWebJobUsage показано, как создавать и выполнять асинхронные операции с помощью надстроек, размещенных у поставщика, и веб-заданий Azure в Office 365.
Используйте это решение для следующих задач:
Повышение производительности удаленных приемников событий.
Перейдите в SharePoint Online и реализуйте те же функции задания таймера, что и в локальной среде SharePoint.
Реализуйте длительные операции, которые необходимо выполнять в среде SharePoint. Например:
События AppInstalled , которые выполняются дольше 30-секундного интервала ожидания. В обработчиках событий надстроек существуют асинхронные процессы. Дополнительные сведения см. в разделах Обработка событий в надстройках SharePoint и Создание приемника событий надстройки в надстройках SharePoint.
Подготовка пользовательского семейства веб-сайтов.
Операции, которые синхронизируют данные между Office 365 и локальными системами.
Операции, выполняющие сложные вычисления.
На следующей схеме показана высокоуровневая архитектура необходимых компонентов и поток обработки между этими компонентами при выполнении асинхронной операции.
Чтобы реализовать асинхронные операции в надстройке, размещенной у поставщика, с помощью веб-заданий Azure:
Пользователи запускают надстройку, развернутую в SharePoint Online.
Надстройка, размещенная у поставщика, предоставляет входные параметры, необходимые для веб-задания Azure, а затем добавляет новое сообщение в очередь службы хранилища Azure.
Очередь службы хранилища Azure активирует событие в непрерывно работающем веб-задании Azure, чтобы начать обработку нового сообщения.
Веб-задание Azure запускает настраиваемую бизнес-логику на сайте SharePoint Online.
Примечание.
При добавлении сообщения в очередь службы хранилища Azure используется процесс, отличный от процесса, выполняющего веб-задание Azure. Таким образом, надстройка может реализовывать асинхронные операции, добавляя новые сообщения в очередь с помощью одного процесса, а затем используя веб-задание Azure для обработки этих сообщений в другом процессе.
Подготовка к работе
Чтобы приступить к работе, скачайте пример надстройки Core.QueueWebJobUsage из проекта шаблонов и практик разработчиков Office 365 на сайте GitHub, а затем создайте учетную запись Azure, добавьте в нее сведения и убедитесь, что веб-задание Azure запущено.
Чтобы создать учетную запись хранения Azure для доступа к очереди хранилища Azure, выполните следующие действия.
Войдите в microsoft портал Azure.
Выберите Создать>хранилище>служб> данныхБыстрое создание.
В поле URL-адрес введите доменное имя. Например, введите contoso.
В поле LOCATION/AFFINITY GROUP выберите подходящее расположение.
В разделе РЕПЛИКАЦИЯ выберите Геоизбыточное.
Выберите CREATE STORAGE ACCOUNT (Создать учетную запись хранения).
Чтобы добавить сведения в только что созданную учетную запись хранения, выполните следующие действия:
После создания учетной записи хранения Azure выберите УПРАВЛЕНИЕ КЛЮЧАМИ ДОСТУПА.
В разделе Управление ключами доступа скопируйте имя учетной записи хранения и первичный ключ доступа.
Примените идентификатор клиента, секрет клиента и сведения об учетной записи хранения Azure к нескольким файлам конфигурации.
В helper Project\Core.QueueWebJobUsage.Console.SendMessage откройте Файл Program.cs и введите URL-адрес сайта в поле siteUrl .
В разделе Свойства в Core.QueueWebJobUsage.Job установите для параметра Копировать локальное значение True для ссылок Microsoft.SharePoint.Client и Microsoft.SharePoint.Client.Runtime . Установка параметра Копировать локальное значение True копирует сборки, на которые ссылается ссылка, в Azure, чтобы веб-задание Azure давало разрешение ссылок на эти сборки.
Разверните веб-задание Azure. Дополнительные сведения см. в разделе Развертывание проекта веб-заданий.
Чтобы убедиться, что веб-задание Azure запущено:
Войдите в портал Azure.
Выберите веб-приложения, а затем веб-сайты Microsoft Azure, которые вы ввели.
Выберите WEBJOBS.
Убедитесь, что веб-задание Azure отображается в списке, а параметр SCHEDULE имеет значение Выполняется непрерывно.
Нажмите кнопку НАСТРОИТЬ.
В разделе Параметры надстройки создайте новые параметры надстройки для ClientId и ClientSecret. Скопируйте пары ClientId и ClientSecret "ключ-значение" из файла Core.QueueWebJobUsage.Job\app.config.
В строках подключения создайте новые строки подключения для AzureWebJobsDashboard и AzureWebJobsStorage. Скопируйте пары ключ (имя) и значение AzureWebJobsDashboard и AzureWebJobsStorage из файла Core.QueueWebJobUsage.Job\app.config, а затем задайте для типа Значение Пользовательский.
Выберите Сохранить.
Применение параметров конфигурации
Используйте сведения, приведенные в следующей таблице, чтобы применить параметры конфигурации к решению Core.QueueWebJobUsage Visual Studio.
| Расположение файла | Ключ для обновления | Обновляемая информация о значении |
|---|---|---|
| Вспомогательный Project\Core.QueueWebJobUsage.Console.SendMessage\app.config | StorageConnectionString | Замените [имя вашей учетной записи] именем учетной записи хранения, скопированной из портал Azure. |
| Замените [Ключ учетной записи] первичным ключом доступа, скопированным из портал Azure. | ||
| Core.QueueWebJobUsageWeb\web.config | StorageConnectionString | Замените [YourAccountName] именем учетной записи хранения, скопированной из портал Azure. |
| Замените [YourAccountKey] первичным ключом доступа, скопированным из портал Azure. | ||
| Core.QueueWebJobUsage.Job\app.config | StorageConnectionString | Замените [YourAccountName] именем учетной записи хранения, скопированной из портал Azure. |
| Замените [YourAccountKey] первичным ключом доступа, скопированным из портал Azure. | ||
| Clientid | Замените [Идентификатор надстройки] идентификатором клиента, скопированным из Core.QueueWebJobUsageWeb\web.config. | |
| ClientSecret | Замените [секрет надстройки] секретом клиента, скопированным из Core.QueueWebJobUsageWeb\web.config. | |
| AzureWebJobsDashboard | Замените [YourAccount] именем учетной записи хранения, скопированной из портал Azure. | |
| Замените [YourKey] первичным ключом доступа, скопированным из портал Azure. | ||
| AzureWebJobsStorage | Замените [YourAccount] именем учетной записи хранения, скопированной из портал Azure. | |
| Замените [YourKey] первичным ключом доступа, скопированным из портал Azure. |
Примечание.
Если ClientId и ClientSecret в Core.QueueWebJobUsageWeb обновляются, например при приращении номера версии в AppManifest.xml, убедитесь, что вы обновили ClientId и ClientSecret в Core.QueueWebJobUsage.Job\app.config.
Использование надстройки Core.QueueWebJobUsage
В следующей таблице описаны все проекты Visual Studio в решении Core.QueueWebJobUsage.
| Проект Visual Studio | Описание |
|---|---|
| Core.QueueWebJobUsage | Проект надстройки SharePoint. Требуются следующие разрешения:
|
| Core.QueueWebJobUsage.Common | Содержит бизнес-объекты и код бизнес-логики, например методы добавления сообщений в очередь хранилища, для этого решения. Этот проект включается для совместного использования бизнес-объектов и бизнес-логики между разными проектами. Это может не понадобиться в реализации. |
| Core.QueueWebJobUsage.Job | Веб-задание Azure, которое запускается при добавлении нового сообщения в очередь службы хранилища Azure. Этот проект содержит пользовательский код бизнес-логики. |
| Core.QueueWebJobUsageWeb | Надстройка, размещенная у поставщика, которая содержит пользовательский интерфейс для проекта Core.QueueWebJobUsage. |
| Helper Project\Core.QueueWebJobUsage.Console.SendMessage | Вспомогательный проект, который можно использовать для проверки сведений об учетной записи хранения и процесса создания очереди, а также для отправки сообщений в очередь для обработки без настройки всего решения, описанного в этой статье. |
При запуске примера кода Core.QueueWebJobUsage отображается надстройка с размещением у поставщика и отображает две кнопки: Синхронная операция и Асинхронная операция. При выборе параметра Синхронная операцияbtnSync_Click в Pages\Default.aspx имитирует длительный синхронный процесс. В этом примере кода btnSync_Click переводит текущий поток в спящий режим на 10 секунд, а затем создает библиотеку документов. При выборе асинхронной операцииbtnAsync_Click в Pages\Default.aspx выполняет следующие действия:
Возвращает текущего пользователя.
Создает бизнес-объект SiteModifyRequest , который хранит данные для включения в сообщение, отправляемое в очередь службы хранилища Azure. В этом примере кода отправляемые данные включают имя текущего пользователя и URL-адрес текущего сайта.
Вызывает SiteManager(). AddAsyncOperationRequestToQueue , чтобы добавить сообщение в очередь службы хранилища Azure.
Примечание.
Код, приведенный в этой статье, предоставляется "как есть" без какой-либо явной или подразумеваемой гарантии, включая подразумеваемые гарантии пригодности для какой-либо цели, для продажи или гарантии отсутствия нарушения прав иных правообладателей.
protected void btnAsync_Click(object sender, EventArgs e)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
using (var clientContext = spContext.CreateUserClientContextForSPHost())
{
// Get the current user.
var currUser = clientContext.Web.CurrentUser;
clientContext.Load(currUser);
clientContext.ExecuteQuery();
// Create business object, and then add the request to the queue.
SiteModifyRequest request = new SiteModifyRequest() { RequestorName = currUser.Title, SiteUrl = Page.Request["SPHostUrl"] };
new SiteManager().AddAsyncOperationRequestToQueue(request,
ConfigurationManager.AppSettings["StorageConnectionString"]);
processViews.ActiveViewIndex = 1;
lblStatus.Text = "Asynchronous operation to create document library started.";
}
}
В Файле Core.QueueWebJobUsage.Common в Файле SiteManager.cs AddAsyncOperationRequestToQueue выполняет следующие действия:
Создает объект CloudStorageAccount , используя сведения о конфигурации AccountName и AccountKey в файле Core.QueueWebJobUsageWeb\web.config.
Создает клиент очереди службы хранилища Azure с помощью CloudStorageAccount.CreateCloudQueueClient.
Использует CloudQueueClient.GetQueueReference для получения ссылки на очередь службы хранилища Azure с именем, равным значению константы SiteManager.StorageQueueName .
Использует CloudQueue.CreateIfNotExists для создания очереди службы хранилища Azure, если она не существует.
Использует CloudQueue.AddMessage для добавления нового сообщения в очередь службы хранилища Azure. Бизнес-объект modifyRequest сериализуется в объект CloudQueueMessage , который добавляется в очередь службы хранилища Azure.
public void AddAsyncOperationRequestToQueue(SiteModifyRequest modifyRequest,
string storageConnectionString)
{
CloudStorageAccount storageAccount =
CloudStorageAccount.Parse(storageConnectionString);
// Get queue or create a new one if one does not exist.
CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
CloudQueue queue = queueClient.GetQueueReference(SiteManager.StorageQueueName);
queue.CreateIfNotExists();
// Add a message to queue.
queue.AddMessage(new CloudQueueMessage(JsonConvert.SerializeObject(modifyRequest)));
}
После добавления сообщения в очередь службы хранилища Azure непрерывно работающее веб-задание Azure ожидает, а затем обрабатывает новое сообщение. Веб-задание Azure определяется в Core.QueueWebJobUsage.Job. При запуске веб-задания Azure Main в Core.QueueWebJobUsage.Job\Program.cs создает новый JobHost, а затем вызывает RunAndBlock. JobHost координирует вызовы методов, помеченных атрибутом QueueTrigger, и следит за сообщениями в определенной очереди. RunAndBlock гарантирует, что веб-задание Azure выполняется непрерывно и вызывает ProcessQueueMessage, который является методом для активации при добавлении нового сообщения в очередь службы хранилища Azure. Пакет SDK веб-заданий Azure связывает основной поток с ProcessQueueMessage. Дополнительные сведения см . в статье Создание веб-задания .NET в службе надстроек Azure.
static void Main()
{
var host = new JobHost();
// The following code ensures that the WebJob will run continuously.
host.RunAndBlock();
}
ProcessQueueMessage обрабатывает новые сообщения, которые добавляются в очередь службы хранилища Azure:
Использование атрибута QueueTrigger для указания того, что при записи нового сообщения в очередь должно быть активировано processQueueMessage с именем, равным значению SiteManager.StorageQueueName.
Запись в журнал для веб-задания Azure с помощью переменной журнала , переданной в качестве параметра в ProcessQueueMessage.
Вызов SiteManager(). PerformSiteModification для выполнения длительного бизнес-процесса на сайте. В этом примере кода поток помещается в спящий режим на 10 секунд, а затем создается библиотека документов.
public static void ProcessQueueMessage(
[QueueTrigger(SiteManager.StorageQueueName)]
SiteModifyRequest modifyRequest, TextWriter log)
{
log.WriteLine(string.Format("{0} '{1}' {2} '{3}'.",
"Received new site modification request with URL",
modifyRequest.SiteUrl,
"from person named as ",
modifyRequest.RequestorName));
try
{
Uri targetSite = new Uri(modifyRequest.SiteUrl);
// Get the realm for the URL.
string realm = TokenHelper.GetRealmFromTargetUrl(targetSite);
// Get the access token for the URL.
// Requires this add-in to be registered with the tenant.
string accessToken = TokenHelper.GetAppOnlyAccessToken(
TokenHelper.SharePointPrincipal,
targetSite.Authority, realm).AccessToken;
// Get client context with access token.
using (var ctx =
TokenHelper.GetClientContextWithAccessToken(
targetSite.ToString(), accessToken))
{
// Call business logic code.
new SiteManager().PerformSiteModification(ctx, modifyRequest);
}
}
catch (Exception ex)
{
log.WriteLine(string.Format("Site modification to URL {0} failed with following details.", modifyRequest.SiteUrl));
log.WriteLine(ex.ToString());
throw;
}
}