Utilisation des opérations asynchrones dans les compléments SharePoint
Implémentez des opérations asynchrones dans les compléments SharePoint à l’aide de Microsoft Azure WebJobs.
S’applique à : SharePoint 2013 | Compléments SharePoint | SharePoint Online
L’exemple Core.QueueWebJobUsage vous montre comment créer et exécuter des opérations asynchrones à l’aide de compléments hébergés par un fournisseur et d’Azure WebJobs dans Office 365.
Utiliser cette solution pour :
Améliorez les performances de vos récepteurs d’événements distants.
Migrez vers SharePoint Online et implémentez la même fonctionnalité de travail du minuteur que celle que vous aviez dans votre environnement SharePoint local.
Implémentez les opérations de longue durée que vous souhaitez exécuter sur votre environnement SharePoint. Par exemple :
Événements AppInstalled qui s’exécutent plus longtemps que l’intervalle de délai d’attente de 30 secondes. Il existe des processus asynchrones dans les gestionnaires d’événements de complément. Pour plus d’informations, voir Gérer les événements dans les compléments SharePoint et Créer un récepteur d’événements de complément dans les compléments SharePoint.
Provisionnement de collection de sites personnalisé.
Opérations qui synchronisent les données entre Office 365 et vos systèmes locaux.
Opérations qui effectuent des calculs complexes.
Le diagramme suivant montre une architecture générale des composants requis et le flux de traitement entre ces composants lorsqu’une opération asynchrone est effectuée.
Pour implémenter des opérations asynchrones dans votre complément hébergé par un fournisseur à l’aide d’Azure WebJobs :
Les utilisateurs exécutent le complément déployé dans SharePoint Online.
Le complément hébergé par un fournisseur fournit les paramètres d’entrée requis par azure WebJob, puis ajoute un nouveau message à la file d’attente stockage Azure.
La file d’attente stockage Azure déclenche un événement dans une tâche web Azure en cours d’exécution continue pour commencer à traiter le nouveau message.
Azure WebJob exécute une logique métier personnalisée sur votre site SharePoint Online.
Remarque
L’ajout d’un message à la file d’attente stockage Azure utilise un processus différent du processus qui exécute la tâche web Azure. Par conséquent, votre complément peut implémenter des opérations asynchrones en ajoutant de nouveaux messages à la file d’attente à l’aide d’un processus, puis en utilisant Azure WebJob pour gérer ces messages dans un autre processus.
Avant de commencer
Pour commencer, téléchargez l’exemple de complément Core.QueueWebJobUsage à partir du projet Office 365 Modèles et pratiques développeur sur GitHub, puis créez un compte Azure, ajoutez des détails à ce compte et vérifiez qu’Azure WebJob est en cours d’exécution.
Pour créer un compte stockage Azure afin d’accéder à la file d’attente de stockage Azure :
Connectez-vous à votre Portail Azure Microsoft.
Choisissez Créationrapided’un nouveau>stockage>Data Services>.
Dans URL, entrez votre nom de domaine. Par exemple, entrez contoso.
Dans EMPLACEMENT/GROUPE D’AFFINITÉs, choisissez un emplacement approprié.
Dans RÉPLICATION, choisissez Géoredondant.
Choisissez CRÉER UN COMPTE DE STOCKAGE.
Pour ajouter des détails à votre compte de stockage nouvellement créé :
Une fois le compte stockage Azure créé, choisissez GÉRER LES CLÉS D’ACCÈS.
Dans Gérer les clés d’accès, copiez le NOM DU COMPTE DE STOCKAGE et la CLÉ D’ACCÈS PRIMAIRE.
Appliquez l’ID client, la clé secrète client et les informations de votre compte de stockage Azure à plusieurs fichiers de configuration.
Dans Helper Project\Core.QueueWebJobUsage.Console.SendMessage, ouvrez Program.cs et entrez l’URL de votre site dans la zone siteUrl .
Dans Propriétés sur Core.QueueWebJobUsage.Job, définissez Copy Local sur True sur les références Microsoft.SharePoint.Client et Microsoft.SharePoint.Client.Runtime . La définition de Copier local sur True copie les assemblys référencés dans Azure afin que la tâche web Azure puisse résoudre les références à ces assemblys.
Déployez Azure WebJob. Pour plus d’informations, consultez Déployer un projet WebJobs.
Pour vérifier que votre tâche web Azure est en cours d’exécution :
Connectez-vous à votre Portail Azure.
Choisissez applications web, puis choisissez les sites web Microsoft Azure que vous avez entrés.
Choisissez WEBJOBS.
Vérifiez que votre tâche web Azure s’affiche dans la liste et que SCHEDULE est défini sur S’exécute en continu.
Choisissez CONFIGURER.
Dans les paramètres du complément, créez des paramètres de complément pour ClientId et ClientSecret. Copiez les paires clé-valeur ClientId et ClientSecret à partir du fichier Core.QueueWebJobUsage.Job\app.config.
Dans les chaînes de connexion, créez des chaînes de connexion pour AzureWebJobsDashboard et AzureWebJobsStorage. Copiez les paires clé (nom) et valeur AzureWebJobsDashboard et AzureWebJobsStorage à partir du fichier Core.QueueWebJobUsage.Job\app.config, puis définissez le type sur Personnalisé.
Cliquez sur Enregistrer.
Appliquer les paramètres de configuration
Utilisez les informations du tableau suivant pour appliquer les paramètres de configuration à la solution Visual Studio Core.QueueWebJobUsage.
| Emplacement du fichier | Clé à mettre à jour | Informations de valeur à mettre à jour |
|---|---|---|
| Project\Core.QueueWebJobUsage.Console.SendMessage\app.config d’assistance | StorageConnectionString | Remplacez [Nom de votre compte] par le nom du compte de stockage copié à partir du Portail Azure. |
| Remplacez [Votre clé de compte] par la clé d’accès primaire copiée à partir du Portail Azure. | ||
| Core.QueueWebJobUsageWeb\web.config | StorageConnectionString | Remplacez [YourAccountName] par le nom du compte de stockage copié à partir du Portail Azure. |
| Remplacez [YourAccountKey] par la clé d’accès primaire copiée à partir du Portail Azure. | ||
| Core.QueueWebJobUsage.Job\app.config | StorageConnectionString | Remplacez [YourAccountName] par le nom du compte de stockage copié à partir du Portail Azure. |
| Remplacez [YourAccountKey] par la clé d’accès primaire copiée à partir du Portail Azure. | ||
| Clientid | Remplacez [Votre ID de complément] par l’ID client copié à partir du Core.QueueWebJobUsageWeb\web.config. | |
| ClientSecret | Remplacez [Votre secret de complément] par la clé secrète client copiée à partir du Core.QueueWebJobUsageWeb\web.config. | |
| AzureWebJobsDashboard | Remplacez [YourAccount] par le nom du compte de stockage copié à partir du Portail Azure. | |
| Remplacez [YourKey] par la clé d’accès primaire copiée à partir du Portail Azure. | ||
| AzureWebJobsStorage | Remplacez [YourAccount] par le nom du compte de stockage copié à partir du Portail Azure. | |
| Remplacez [YourKey] par la clé d’accès primaire copiée à partir du Portail Azure. |
Remarque
Si le ClientId et le ClientSecret dans Core.QueueWebJobUsageWeb sont mis à jour, par exemple, lorsque vous incrémentez le numéro de version dans le AppManifest.xml, veillez à mettre à jour clientId et ClientSecret dans le Core.QueueWebJobUsage.Job\app.config.
Utilisation du complément Core.QueueWebJobUsage
Le tableau suivant décrit tous les projets Visual Studio dans la solution Core.QueueWebJobUsage.
| Projet Visual Studio | Description |
|---|---|
| Core.QueueWebJobUsage | Votre projet de complément SharePoint. Les autorisations suivantes sont requises :
|
| Core.QueueWebJobUsage.Common | Contient les objets métier et le code de logique métier, tels que les méthodes permettant d’ajouter des messages à la file d’attente de stockage, pour cette solution. Ce projet est inclus pour partager des objets métier et une logique métier entre différents projets. Vous n’en aurez peut-être pas besoin dans votre implémentation. |
| Core.QueueWebJobUsage.Job | Tâche web Azure qui s’exécute lorsqu’un nouveau message est ajouté à la file d’attente stockage Azure. Ce projet contient votre code de logique métier personnalisé. |
| Core.QueueWebJobUsageWeb | Complément hébergé par un fournisseur qui contient l’interface utilisateur du projet Core.QueueWebJobUsage. |
| Projet d’assistance\Core.QueueWebJobUsage.Console.SendMessage | Un projet d’assistance qui peut être utilisé pour valider les informations de compte de stockage et le processus de création de file d’attente, et pour envoyer des messages à la file d’attente pour traitement sans configurer la solution complète décrite dans cet article. |
Lorsque vous exécutez l’exemple de code Core.QueueWebJobUsage, le complément hébergé par le fournisseur s’affiche et affiche deux boutons : Opération synchrone et Opération asynchrone. Lorsque vous choisissez Opération synchrone, btnSync_Click dans Pages\Default.aspx simule un processus synchrone de longue durée. Dans cet exemple de code, btnSync_Click met le thread actuel en veille pendant 10 secondes, puis crée une bibliothèque de documents. Lorsque vous choisissez Opération asynchrone, btnAsync_Click dans Pages\Default.aspx effectue les opérations suivantes :
Obtient l’utilisateur actuel.
Crée un objet métier SiteModifyRequest qui stocke les données à inclure dans le message envoyé à la file d’attente stockage Azure. Dans cet exemple de code, les données envoyées incluent le nom de l’utilisateur actuel et l’URL du site actuel.
Appelle SiteManager(). AddAsyncOperationRequestToQueue pour ajouter le message à la file d’attente stockage Azure.
Remarque
Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.
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.";
}
}
Dans Core.QueueWebJobUsage.Common, dans SiteManager.cs, AddAsyncOperationRequestToQueue effectue les opérations suivantes :
Crée un objet CloudStorageAccount à l’aide des informations de configuration AccountName et AccountKey dans le fichier Core.QueueWebJobUsageWeb\web.config.
Crée un client de file d’attente stockage Azure à l’aide de CloudStorageAccount.CreateCloudQueueClient.
Utilise CloudQueueClient.GetQueueReference pour obtenir une référence à la file d’attente stockage Azure dont le nom est égal à la valeur de la constante SiteManager.StorageQueueName .
Utilise CloudQueue.CreateIfNotExists pour créer la file d’attente stockage Azure si elle n’existe pas.
Utilise CloudQueue.AddMessage pour ajouter un nouveau message à la file d’attente stockage Azure. L’objet métier modifyRequest est sérialisé dans un objet CloudQueueMessage , qui est ajouté à la file d’attente stockage 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)));
}
Une fois le message ajouté à la file d’attente stockage Azure, une tâche web Azure en cours d’exécution continue attend et traite le nouveau message. Azure WebJob est défini dans Core.QueueWebJobUsage.Job. Lors de l’exécution d’Azure WebJob, Main dans Core.QueueWebJobUsage.Job\Program.cs crée un jobHost, puis appelle RunAndBlock. JobHost coordonne les appels aux méthodes marquées avec l’attribut QueueTrigger et surveille les messages dans une file d’attente spécifique. RunAndBlock garantit que la tâche web Azure s’exécute en continu et appelle ProcessQueueMessage, qui est la méthode à déclencher lorsqu’un nouveau message est ajouté à la file d’attente stockage Azure. Le Kit de développement logiciel (SDK) Azure WebJobs associe le thread principal à ProcessQueueMessage. Pour plus d’informations, consultez Créer une tâche web .NET dans le service de complément Azure.
static void Main()
{
var host = new JobHost();
// The following code ensures that the WebJob will run continuously.
host.RunAndBlock();
}
ProcessQueueMessage traite les nouveaux messages ajoutés à la file d’attente stockage Azure par :
Utilisation de l’attribut QueueTrigger pour spécifier que ProcessQueueMessage doit être déclenché lorsqu’un nouveau message est écrit dans la file d’attente avec un nom égal à la valeur de SiteManager.StorageQueueName.
Écriture dans le journal pour azure WebJob à l’aide de la variable de journal qui a été passée en tant que paramètre à ProcessQueueMessage.
Appel de SiteManager(). PerformSiteModification pour effectuer un processus métier de longue durée sur le site. Dans cet exemple de code, le thread est mis en veille pendant 10 secondes, puis une bibliothèque de documents est créée.
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;
}
}