Utilisation des opérations asynchrones dans les compléments SharePoint

Implémenter des opérations asynchrones dans SharePoint des applications à l’aide 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 add-ins 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 travail du SharePoint que dans votre environnement local.

  • Implémentez des opérations de longue durée que vous souhaitez exécuter sur votre environnement SharePoint de travail. Par exemple :

    • Événements AppInstalled qui s’exécutent plus longtemps que l’intervalle de délai d’interruption de 30 secondes. Il existe des processus asynchrones dans les gestions d’événements de add-in. Pour plus d’informations, voir Gérer les événements dans les SharePoint et créer un récepteur d’événements de SharePoint dans les modules complémentaires.

    • Mise en service de collection de sites personnalisée.

    • 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 illustre une architecture de haut niveau des composants requis et le flux de traitement entre ces composants lorsqu’une opération asynchrone est effectuée.

Diagramme montrant le flux des opérations asynchrones. Le complément SharePoint appelle le complément hébergé par un fournisseur, ce qui ajoute un message à la file d’attente de stockage Azure. Une tâche web Azure traite le message et effectue une action sur le site SharePoint.

Pour implémenter des opérations asynchrones dans votre application hébergée par un fournisseur à l’aide d’Azure WebJobs :

  1. Les utilisateurs exécutent le add-in déployé dans SharePoint Online.

  2. Le add-in hébergé par un fournisseur fournit les paramètres d’entrée requis par azure WebJob, puis ajoute un nouveau message à la file d’stockage Azure file d’attente.

  3. La stockage Azure file d’attente déclenche un événement dans une azure WebJob en cours d’exécution continue pour commencer à traiter le nouveau message.

  4. Azure WebJob exécute une logique métier personnalisée sur votre site SharePoint Online.

Notes

L’ajout d’un message à stockage Azure file d’attente utilise un processus différent du processus qui exécute Azure WebJob. Par conséquent, votre application 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

To get started, download the Core.QueueWebJobUsage sample add-in from the Office 365 Developer patterns and practices project on GitHub, and then create an Azure account, add details to that account, and verify that Azure WebJob is running.

Pour créer un compte stockage Azure pour accéder à la file d’attente de stockage Azure :

  1. Connectez-vous à votre portail Microsoft Azure client.

  2. Choose New > Data Services > Stockage > Quick Create.

  3. Dans l’URL, entrez votre nom de domaine. Par exemple, entrez contoso.

  4. Dans LOCATION/GROUPE D’AFFINITÉ, choisissez un emplacement approprié.

  5. Dans REPLICATION, choisissez Géo-redondant.

  6. Choisissez CRÉER UN COMPTE DE STOCKAGE.

Pour ajouter des détails à votre compte de stockage nouvellement créé :

  1. Lorsque le compte stockage Azure est créé, choisissez GÉRER LES TOUCHES D’ACCÈS RAPIDE.

  2. Dans Gérer les touches d’accès rapide, copiez le NOM du COMPTE DE STOCKAGE et la CLÉ D’ACCÈS PRIMAIRE.

  3. Appliquez l’ID client, la secret client et vos stockage Azure de compte à plusieurs des fichiers de configuration.

  4. Dans l’Project\Core.QueueWebJobUsage.Console.SendMessage, ouvrez Program.cs et entrez l’URL de votre site dans la zone siteUrl.

  5. Dans Propriétés sur Core.QueueWebJobUsage.Job, définissez Copy Local sur True sur Microsoft.SharePoint. Client et Microsoft.SharePoint. Références Client.Runtime. La définition de La copie locale sur True copie les assemblys référencés dans Azure afin que la webjob Azure puisse résoudre les références à ces assemblys.

  6. Déployez Azure WebJob. Pour plus d’informations, voir Déployer un projet WebJobs.

Pour vérifier que votre webjob Azure est en cours d’exécution :

  1. Connectez-vous à votre portail Azure.

  2. Choisissez les applications web, puis les sites web Microsoft Azure que vous avez entrés.

  3. Choisissez WEBJOBS.

  4. Vérifiez que votre webjob Azure apparaît dans la liste et que SCHEDULE est définie sur S’exécute en continu.

  5. Choose CONFIGURE.

  6. Dans les paramètres du add-in, créez de nouveaux paramètres de add-in pour ClientId et ClientSecret. Copiez les paires clé-valeur ClientId et ClientSecret à partir Core.QueueWebJobUsage.Job\app.config fichier.

  7. Dans les chaînes de connexion, créez de nouvelles 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é.

  8. Choisissez Enregistrer.

Appliquer les paramètres de configuration

Utilisez les informations du tableau suivant pour appliquer les paramètres de configuration à la solution Core.QueueWebJobUsage Visual Studio.

Emplacement du fichier Clé de mise à jour Informations de valeur à mettre à jour
Aide-Project\Core.QueueWebJobUsage.Console.SendMessage\app.config 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 principal 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 principal 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 principal copiée à partir du portail Azure.
ClientId Remplacez [Votre ID de add-in] par l’ID client copié à partir du Core.QueueWebJobUsageWeb\web.config.
ClientSecret Remplacez [Your Add-in Secret] par la secret client copiée à partir de la 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 principal 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 principal copiée à partir du portail Azure.

Notes

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 le ClientId et le ClientSecret dans le Core.QueueWebJobUsage.Job\app.config.

Utilisation du add-in Core.QueueWebJobUsage

Le tableau suivant décrit tous les projets Visual Studio dans la solution Core.QueueWebJobUsage.

Visual Studio projet Description
Core.QueueWebJobUsage Votre SharePoint projet de module de développement. Les autorisations suivantes sont requises :
  • AllowAppOnlyPolicy

  • Autorisations FullControl sur le Web.

Core.QueueWebJobUsage.Common Contient les objets métier et le code de logique métier, tels que les méthodes d’ajout de 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 Azure WebJob qui s’exécute lorsqu’un nouveau message est ajouté à la stockage Azure file d’attente. Ce projet contient votre code de logique métier personnalisé.
Core.QueueWebJobUsageWeb Le add-in hébergé par un fournisseur qui contient l’interface utilisateur pour le projet Core.QueueWebJobUsage.
Helper Project\Core.QueueWebJobUsage.Console.SendMessage Projet d’aide 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 définir la solution entière décrite dans cet article.

Lorsque vous exécutez l’exemple de code Core.QueueWebJobUsage, le add-in hébergé par un fournisseur apparaît et affiche deux boutons : opération synchrone et opération asynchrone. Lorsque vous choisissez Opération synchrone, btnSync_Click pages\Default.aspx simule un processus synchrone de longue durée. Dans cet exemple de code, btnSync_Click le thread actuel est mis en veille pendant 10 secondes, puis crée une bibliothèque de documents. Lorsque vous choisissez l’opération asynchrone, btnAsync_Click dans Pages\Default.aspx :

  1. Obtient l’utilisateur actuel.

  2. Crée un objet métier SiteModifyRequest qui stocke les données à inclure dans le message envoyé à stockage Azure file d’attente. Dans cet exemple de code, les données envoyées incluent le nom de l’utilisateur actuel et l’URL du site actuel.

  3. Appelle SiteManager(). AddAsyncOperationRequestToQueue pour ajouter le message à la file stockage Azure file d’attente.

Notes

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 :

  1. Crée un objet CloudStorageAccount à l’aide des informations de configuration AccountName et AccountKey dans Core.QueueWebJobUsageWeb\web.config fichier.

  2. Crée un client stockage Azure file d’attente à l’aide de CloudStorageAccount.CreateCloudQueueClient.

  3. Utilise CloudQueueClient.GetQueueReference pour obtenir une référence à la file d’attente stockage Azure avec un nom égal à la valeur de la constante SiteManager.StorageQueueName.

  4. Utilise CloudQueue.CreateIfNotExists pour créer la file d’stockage Azure si elle n’existe pas.

  5. Utilise CloudQueue.AddMessage pour ajouter un nouveau message à la file d’stockage Azure de données. L’objet métier modifyRequest est sérialisé dans un objet CloudQueueMessage, qui est ajouté à la stockage Azure file d’attente.

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 que le message est ajouté à la file d’attente stockage Azure, une ligne web Azure en cours d’exécution continue attend et traite le nouveau message. La tâche web Azure est définie dans Core.QueueWebJobUsage.Job. Lorsque azure WebJob s’exécute, Main dans Core.QueueWebJobUsage.Job\Program.cs crée un nouvel JobHost, puis appelle RunAndBlock. JobHost coordonne les appels aux méthodes marquées avec l’attribut QueueTrigger et surveille les messages d’une file d’attente spécifique. RunAndBlock garantit que la webjob 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 SDK Azure WebJobs associe le thread principal à ProcessQueueMessage. Pour plus d’informations, voir Create a .NET WebJob in Azure Add-in Service.

static void Main()
        {
            var host = new JobHost();
            // The following code ensures that the WebJob will run continuously.
            host.RunAndBlock();
        }

ProcessQueueMessage traite les nouveaux messages qui sont ajoutés à la file d’stockage Azure par :

  1. 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.

  2. É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.

  3. Appel de SiteManager(). PerformSiteModification pour effectuer un processus d’entreprise 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;
            }
        }

Voir aussi