Utilisation de récepteurs d’événements dans SharePoint Foundation 2010 (Partie 1 sur 2)

Résumé :  les récepteurs d’événements dans Microsoft SharePoint Foundation 2010 permettent à votre code personnalisé de répondre lorsque des actions spécifiques se produisent sur un objet SharePoint. Les exemples pratiques de cet article vous montrent comment utiliser des événements pour améliorer vos applications SharePoint.

Dernière modification : lundi 9 mars 2015

S’applique à : Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

Dans cet article
Notions de base relatives aux événements dans SharePoint Foundation 2010
Utilisation d’événements dans SharePoint Foundation 2010
Utilisation du modèle de récepteur d’événements dans Visual Studio 2010
Ressources supplémentaires

Auteur :  Ali Badereddin, Microsoft Corporation | Nick Gattuccio, Microsoft Corporation

Sommaire

• Notions de base relatives aux événements dans SharePoint Foundation 2010

• Utilisation d’événements dans SharePoint Foundation 2010

• Utilisation du modèle de récepteur d’événements dans Visual Studio 2010

• Ressources supplémentaires

Notions de base relatives aux événements dans SharePoint Foundation 2010

Un récepteur d’événements dans Microsoft SharePoint Foundation 2010 est simplement une méthode qui est appelée lorsqu’une action de déclenchement se produit sur un objet SharePoint spécifié. Les événements de déclenchement incluent des actions telles que l’ajout, la mise à jour, la suppression, le déplacement, l’archivage et l’extraction. Les objets SharePoint qui écoutent les événements, autrement dit les hôtes récepteurs d’événements, incluent des objets tels que les collections de sites, les sites, les listes et les flux de travail.

Les événements sont de précieux outils pour les développeurs SharePoint. Lorsqu’un utilisateur effectue une action qui affecte un site SharePoint, vous pouvez intercepter cette action et y répondre avec du code personnalisé. Par exemple, si un responsable de projet doit être informé lorsque de nouveaux documents ou fichiers sont ajoutés à une bibliothèque de documents donnée, vous pouvez écrire du code de récepteur d’événements afin d’envoyer une notification par courrier électronique au responsable de projet, puis lier ce code à l’action d’ajout d’élément sur la bibliothèque de documents. SharePoint Foundation 2010 offre une très grande flexibilité quant à la détection et à la réponse aux événements SharePoint.

Les événements ont fait leur apparition dans Windows SharePoint Services 2.0, mais ils étaient initialement pris en charge uniquement sur les bibliothèques de documents. Dans Windows SharePoint Services 3.0, l’infrastructure d’événements SharePoint a pris sa forme actuelle, avec des récepteurs d’événements gérés.

Les récepteurs d’événements offrent aujourd’hui plusieurs améliorations. Ils sont plus simples d’utilisation, ils ont davantage de types d’événements et ils sont pris en charge sur les listes, les types de contenu, les flux de travail et les sites. Dans SharePoint Foundation 2010, de nouveaux événements Web et de listes ont été introduits ; par ailleurs, les collections de sites peuvent désormais assumer la fonction d’hôtes d’événements, les événements After peuvent maintenant être synchrones et l’annulation et l’emprunt d’identité d’événement ont été améliorés.

Fonctionnement des événements SharePoint : tout ce que vous devez savoir en un paragraphe

Un récepteur d’événements SharePoint est lié à un objet SharePoint (l’hôte d’événements) et répond à une action utilisateur en déclenchant du code de récepteur d’événements. La compilation du code de récepteur d’événements s’effectue dans un assembly managé, autrement dit un fichier .dll déployé dans le Global Assembly Cache.

Où puis-je utiliser des récepteurs d’événements ?

Si vous souhaitez ajouter des comportements aux opérations qui se produisent dans SharePoint, vous pouvez utiliser des récepteurs d’événements pour déclencher votre code personnalisé chaque fois qu’une certaine opération a lieu. Le Tableau 1 répertorie les différentes opérations sur lesquelles vous pouvez enficher votre code personnalisé.

Tableau 1. Opérations disponibles pour les récepteurs d’événements

Qu’est-ce qu’un récepteur d’événements ?

Un récepteur d’événements est un fragment de code managé qui répond à des événements SharePoint lorsque des actions de déclenchement spécifiques se produisent sur un objet SharePoint. Les actions de déclenchement incluent des activités telles que l’ajout, la mise à jour, la suppression, le déplacement, l’archivage et l’extraction.

Pour créer un récepteur d’événements, vous devez hériter de l’une des classes de base de récepteur d’événements. SharePoint en fournit cinq. (Voir le Tableau 2 dans la section suivante.) Notez que chaque classe de base prend en charge uniquement des événements et hôtes d’événements spécifiques. Vous devez sélectionner la classe de base de récepteur d’événements correcte pour le type d’hôte que vous souhaitez prendre en charge.

Après avoir écrit vos récepteurs d’événements dans votre classe de récepteurs d’événements, vous devez compiler le récepteur dans un assembly managé et le placer dans le Global Assembly Cache. Pour finir, vous devez lier les récepteurs d’événements à un hôte d’événements convenable. Plus loin dans cet article, nous discuterons de la liaison d’événement et des différentes méthodes avec lesquelles vous pouvez lier des événements.

Qu’est-ce qu’un hôte d’événements ?

Un hôte d’événements est un objet SharePoint courant qui s’attend à recevoir des événements, autrement dit un objet dont les récepteurs d’événements sont « à l’écoute » d’événements SharePoint. Ces types d’hôtes d’événements SharePoint incluent des instances d’objets courants tels que des collections de sites, des sites et des listes SharePoint. Chaque type d’hôte d’événements a un ensemble spécifique de types de base de récepteurs d’événements desquels il peut hériter.

Le Tableau 2 répertorie les classes de base de récepteurs d’événements, les types d’hôtes d’événements qui prennent en charge chaque récepteur, ainsi que les événements qu’ils prennent en charge.

Tableau 2. Classes de base de récepteurs d’événements et événements pris en charge

Concepts clé liés au modèle d’événement SharePoint

Au-delà des éléments fondamentaux du modèle d’événement (récepteurs d’événements, hôtes d’événements et événements proprement dits), il existe certains concepts clés liés au modèle d’événement SharePoint.

Événements Before

Un événement Before se produit avant que l’opération demandée ait lieu. Par exemple, l’événement ItemAdding est un événement Before déclenché avant l’ajout d’un élément à une liste SharePoint.

Vu sous un autre angle, les événements Before sont déclenchés lorsqu’une action se produit avant que SharePoint écrive dans la base de données de contenu. Cela permet au récepteur d’événements d’effectuer des tâches avant que les données soient validées dans une base de données. La validation de données constitue un bon exemple d’utilisation d’événements Before car ceux-ci se déclenchent avant la validation des données. Vous pouvez également utiliser des événements Before (ou synchrones) pour annuler des actions utilisateur, par exemple en cas d’échec de la validation des données.

Du code de récepteur d’événements déclenché par un événement Before s’exécute dans le même thread que le code qui exécute l’action utilisateur qui l’a déclenché. Pour cette raison, les événements Before sont toujours synchrones. Il est facile d’identifier les événements Before car les noms de leurs membres se terminent par le suffixe « ing » : ItemAdding, ListAdding, et ainsi de suite.

Événements After

Un événement After est déclenché après que l’opération demandée a eu lieu. Par exemple, l’événement ItemAdded est un événement After déclenché après l’ajout d’un élément à une liste SharePoint.

Les événements After déclenchent des récepteurs d’événements qui s’exécutent après la validation des actions utilisateur dans la base de données de contenu ; ils appellent du code qui s’exécute après que la base de données de contenu a été modifiée. Cela vous permet d’exécuter une logique qui se produit après qu’un utilisateur a terminé une action spécifique.

Les événements After peuvent s’exécuter de manière synchrone ou asynchrone. Si l’événement After est synchrone, il s’exécute dans le même thread que celui dans lequel l’action de déclenchement se produit. En revanche, s’il est asynchrone, il s’exécute dans un thread distinct.

Il est facile d’identifier les événements After car les noms de leurs membres se terminent par le suffixe « ed » : ItemDeleted, WebProvisioned, et ainsi de suite.

Événements synchrones

Un événement synchrone s’exécute dans le même thread que celui dans lequel l’action de déclenchement se produit. Par exemple, lorsqu’un utilisateur ajoute un élément à partir de l’interface utilisateur de SharePoint, l’événement s’exécute entièrement avant d’être renvoyé à l’utilisateur et d’indiquer que l’élément a été ajouté.

Tous les événements Before sont synchrones.

Événements asynchrones

Un événement asynchrone se produit après l’action qui l’a déclenché et s’exécute sur un thread différent de celui dans lequel l’action de déclenchement s’exécute. Par exemple, lorsqu’un utilisateur ajoute un élément à une bibliothèque de documents à l’aide de l’interface utilisateur de SharePoint, l’événement commence à s’exécuter avant de renvoyer le contrôle à l’utilisateur ; cependant, il n’est pas garanti que le récepteur d’événements terminera de s’exécuter avant qu’il ne soit indiqué à l’utilisateur que l’élément a été ajouté.

Liaison d’événement

La liaison d’événement (également appelée enregistrement d’événement) peut s’effectuer à l’aide du modèle objet côté serveur ou de Feature XML. Les sections suivantes fournissent des informations détaillées sur la liaison d’événements dans SharePoint Foundation.

Annulation d’événement

L’annulation d’événement vous permet d’annuler une opération de récepteur d’événements dans un événement Before avant la conclusion de l’action. Par exemple, nous pouvons écrire du code dans le récepteur d’événements ItemAdding qui annule l’action d’ajout d’élément. Ainsi, lorsqu’un utilisateur tente d’ajouter un élément, l’opération est annulée et l’élément n’est pas ajouté à la liste. Lorsque l’opération est annulée, assurez-vous d’afficher un message d’erreur à l’utilisateur ou de fournir un message d’erreur personnalisé en redirigeant l’utilisateur vers une URL spécifique.

Séquence de récepteur d’événements

La séquence de récepteur d’événements spécifie l’ordre dans lequel un récepteur d’événements est exécuté dans les cas où un événement déclenche plusieurs récepteurs d’événements. Par exemple, si vous avez deux récepteurs d’événements ItemAdded liés à la même liste (un de l’Assembly « 1 » et l’autre de l’Assembly « 2 »), le récepteur d’événements lié avec un numéro d’ordre inférieur est exécuté en premier. En guise d’exemple pratique, on peut citer l’ajout d’un récepteur d’événements à une liste système à laquelle un récepteur d’événements système est déjà lié. Dans ce cas, vous devez assigner au nouveau récepteur d’événements un numéro d’ordre plus élevé.

Pipeline d’événements SharePoint

La Figure 1 illustre la façon dont les événements SharePoint se produisent du point de vue de la synchronisation et de l’ordonnancement.

Figure 1. Pipeline d’événements SharePoint

Remarquez les détails suivants :

• Les récepteurs d’événements synchrones sont appelés de manière séquentielle en fonction du numéro d’ordre spécifié durant la liaison d’événement. Cela s’applique aux événements synchrones Before et After.

• Les threads de récepteurs d’événements After asynchrones sont initiés de manière séquentielle en fonction du numéro d’ordre. Cependant, il n’est pas garanti qu’ils se termineront dans le même ordre.

• Un événement After asynchrone peut démarrer à tout moment après que son action utilisateur associée a été exécutée. Il peut commencer avant, en même temps ou après que la demande Web s’est terminée.

Après qu’un utilisateur a initié une action dans l’interface utilisateur de SharePoint, et avant que SharePoint Foundation exécute l’action utilisateur, les événements Before synchrones sont déclenchés. S’il en existe plusieurs, ils sont déclenchés en fonction de leur numéro d’ordre. De même, les événements After synchrones sont déclenchés après que SharePoint Foundation a exécuté l’action utilisateur. Ces événements sont également déclenchés en fonction de leur numéro d’ordre. Comme vous pouvez le voir, tous les événements synchrones sont traités dans le même thread que celui dans lequel l’action utilisateur se produit.

Les événements After asynchrones, en revanche, sont traités sur des threads secondaires.

Utilisation d’événements dans SharePoint Foundation 2010

La création d’un événement SharePoint s’effectue en deux étapes. Tout d’abord, on identifie l’opération que l’on souhaite associer à un événement, on hérite de la classe de base de récepteurs d’événements appropriée, puis on écrit le code personnalisé pour le récepteur d’événements. Ensuite, on lie l’événement à un hôte d’événements SharePoint approprié. (Cette étape porte également le nom d’« enregistrement » de l’événement.)

Une fois le code de récepteur d’événements rédigé et compilé dans un assembly signé de façon sécurisée, vous pouvez procéder de deux manières pour lier l’événement à son hôte d’événements : vous pouvez soit utiliser des API dans le modèle objet SharePoint, soit utiliser Feature XML dans une solution SharePoint. Nous allons examiner ces deux méthodes en détail.

Utilisation du modèle objet ou utilisation de solutions ?

En gros, la différence entre l’utilisation du modèle objet et l’utilisation de solutions pour lier des événements SharePoint est la suivante : l’approche faisant appel au modèle objet est plus flexible et plus facile à développer, mais elle est difficile à déployer et à maintenir. L’approche faisant appel aux solutions est moins flexible et plus difficile à développer, mais elle est beaucoup plus facile à déployer et à maintenir.

Lors de l’utilisation du modèle objet, vous avez l’ensemble du modèle objet SharePoint à votre disposition. Vous écrivez votre code de récepteur d’événements, vous le compilez dans un assembly que vous déployez dans le Global Assembly Cache et vous exécutez du code pour lier les événements dans l’assembly à un hôte d’événements SharePoint.

Cette approche est utile lorsque vous êtes en mode de développement car il est facile de tester et de modifier votre code de récepteur d’événements et la liaison d’événement, puis de reconstruire et redéployer le projet. Toutefois, lorsque vous déplacez votre code d’une plateforme de développement vers un environnement de production, cette simplicité s’évapore car vous devez déployer tout manuellement. Cela signifie que vous devez copier le code de récepteur d’événements (autrement dit, l’assembly managé) sur chaque serveur Web frontal dans l’environnement de production. Vous devez ensuite exécuter le fichier exécutable sur l’un des serveurs Web frontaux, puis exécuter iisreset sur chaque serveur Web frontal afin d’actualiser le cache sur le processus de travail IIS (w3wp.exe). Dans un environnement de production à grande échelle, cela risque d’être une tâche extrêmement complexe (et risquée).

L’approche faisant appel à une solution SharePoint diffère dans la manière dont elle lie la définition du récepteur d’événements. Par ailleurs, du fait que le code de récepteur d’événements se trouve dans le package de déploiement (.wsp) avec les fichiers de solution, le déploiement dans une batterie de serveurs est beaucoup plus simple et fiable et il suffit d’activer une Fonctionnalité pour rendre la définition de récepteur d’événements disponible. L’un des autres grands avantages offerts par cette approche est que vous pouvez implémenter des récepteurs d’événements dans du code d’un niveau de confiance partiel (autrement dit, dans des solutions en bac à sable (sandbox)). Les administrateurs au niveau de la collection de site peuvent ensuite ajouter des récepteurs d’événements. (Avant SharePoint 2010, seuls les administrateurs de batterie pouvaient ajouter des récepteurs d’événements).

Le déploiement ne requiert par conséquent aucune autre étape que celles normalement nécessaires au déploiement d’une solution SharePoint à l’aide d’un fichier .wsp. L’exécution d’une commande de déploiement unique permet de déployer l’assembly de récepteur et les liaisons d’événements sur tous les serveurs Web frontaux une fois la Fonctionnalité activée.

Visual Studio 2010 rend ce processus encore plus simple. Le recours à Visual Studio permet de bénéficier de la flexibilité du modèle objet tout en tirant parti de l’aspect économique offert par les solutions. Dans les sections suivantes, nous allons utiliser des récepteurs d’événements et souligner les manières dont Visual Studio 2010 a grandement simplifié ce processus.

Utilisation du modèle objet côté serveur

Lors de l’utilisation du modèle objet côté serveur, trois actions principales doivent être effectuées : la création du code d’événement, la liaison d’événements et la modification du code d’événement. Les sections qui suivent décrivent chaque étape en détail.

Création d’événements à l’aide du modèle objet

La première étape dans l’écriture d’un récepteur d’événements personnalisé consiste à substituer l’une des classes de base de récepteurs d’événements. Les cinq classes de base de récepteurs d’événements SharePoint sont répertoriées dans le Tableau 2 plus haut dans cet article, mais toutes héritent de la classe de base de récepteurs d’événements, SPEventReceiverBase.

Pour créer un récepteur d’événements

1. Dans Visual Studio 2008 ou Visual Studio 2010, créez un projet de bibliothèque de classes C# nommé par exemple MyReceiverAssembly.

   Important

   Si vous utilisez Visual Studio 2010, assurez-vous de cibler le Microsoft .NET Framework 3.5. En effet, SharePoint 2010 repose sur le .NET Framework 3.5. Ce paramètre se trouve sous l’onglet Application des propriétés du projet, comme indiqué à la Figure 2.

   Figure 2. Ciblage du .NET Framework 3.5

   

2. Sous l’onglet Build des propriétés du projet, affectez à Plateforme cible la valeur x64 ou Any CPU, comme indiqué à la Figure 3. Ne sélectionnez pas x86.

   Figure 3. Ciblage de la plateforme appropriée

   

3. Sous l’onglet Signature des propriétés du projet, sélectionnez Signer l’assembly.

4. Cliquez sur Choisir un fichier de clé de nom fort, puis sur Nouveau.

5. Dans la boîte de dialogue Créer une clé de nom fort, dans la zone de texte Nom du fichier de clé, tapez un nom quelconque. Désactivez la case à cocher Protéger mon fichier de clé par un mot de passe, puis cliquez sur OK.

6. Renommez votre classe, par exemple MyReceiverClass.

7. Ajoutez une référence à Microsoft.SharePoint.dll.

8. Dans votre classe, créez une référence à l’espace de noms Microsoft.SharePoint en insérant l’instruction suivante :

   using Microsoft.SharePoint;

9. Héritez de la sous-classe appropriée de SPEventReceiverBase, en fonction de l’événement que vous souhaitez créer. (Voir le Tableau 2.) Par exemple, si vous souhaitez créer et lier un événement ItemAdded, héritez de la classe de base SPItemEventReceiver, comme suit :

   Public class MyReceiverClass : SPItemEventReceiver

10. Définissez les méthodes pour les événements que vous souhaitez implémenter. Une technique utile consiste à taper substitution publique et à appuyer sur la barre Espace. Dans Visual Studio, IntelliSense affiche les événements disponibles sur la classe, comme indiqué à la Figure 4.

    Figure 4. Utilisation d’IntelliSense pour afficher les événements disponibles

    

    Si vous avez sélectionné l’événement ItemAdded, vous avez maintenant la définition de méthode suivante :

    Public override void ItemAdded(SPItemEventProperties properties)
    {
        base.ItemAdded(Properties;
    }
    

11. Générez la bibliothèque de classes dans une DLL

12. Placez la DLL dans le Global Assembly Cache en naviguant jusqu’au dossier %WINDIR%\assembly puis en faisant glisser votre assembly dans le dossier.

    Si vous recevez une erreur « Accès refusé » ou un autre problème vous empêche de faire glisser l’assembly dans le cache, vous pouvez appliquer la procédure suivante.

    1. Assurez-vous que les Outils de développement SharePoint dans Visual Studio 2010 sont installés sur votre ordinateur.

    2. Démarrez l’invite de commandes Visual Studio.

    3. Entrez gacutil /i suivi du chemin d’accès à l’assembly. Si l’opération réussit, le message « Assembly ajouté au cache  » s’affiche à l’écran.

    4. Pour vérifier que votre assembly a bien été ajouté, entrez la commande suivante à l’invite de commandes pour répertorier tous les assemblys qui se trouvent dans le répertoire spécifié dans le cache d’assemblys (dans le cas présent, dans le répertoire de cache nommé MyReceiverAssembly) :

       gacutil /l MyReceiverAssembly

Liaison d’événements à l’aide du modèle objet

Lorsque vous utilisez le modèle objet SharePoint Foundation, vous pouvez lier (enregistrer) tout objet qui possède la propriété EventReceivers. La propriété EventReceivers est de type SPEventReceiverDefinitionCollection, ce qui facilite l’ajout de définitions de récepteurs d’événements à des hôtes d’événements. Vous trouverez ci-dessous une liste d’objets SharePoint qui possèdent cette propriété et qui peuvent servir d’hôtes d’événements.

• SPSite (SPSite.EventReceivers)

• SPWeb (SPWeb.EventReceivers)

• SPList (SPList.EventReceivers)

• SPContentType (SPContentType.EventReceivers)

• SPFile (SPFile.EventReceivers)

• SPWorkflow (SPWorkflowEventReceivers())

Pour lier un récepteur d’événements

1. Dans Visual Studio 2008 ou Visual Studio 2010, créez un projet d’application console C# nommé par exemple RegisterEvents.

   Important

   Si vous utilisez Visual Studio 2010, assurez-vous de cibler le Microsoft .NET Framework 3.5. En effet, SharePoint 2010 repose sur le .NET Framework 3.5. Ce paramètre se trouve sous l’onglet Application des propriétés du projet, comme indiqué plus haut à la Figure 2.

2. Ajoutez une référence à Microsoft.SharePoint.dll.

3. Dans votre classe, créez une référence à l’espace de noms Microsoft.SharePoint en insérant l’instruction suivante :

   using Microsoft.SharePoint;

4. Ajoutez un nouvel élément de type SPEventReceiverDefinition à la collection EventReceivers sur l’objet spécifié, comme suit :

   SPEventReceiverDefinition def = list.EventReceivers.Add();

5. Pour obtenir le nom complet de l’assembly que vous avez créé lors de la procédure précédente, accédez au Global Assembly Cache, recherchez l’assembly, cliquez avec le bouton droit sur l’entrée de l’assembly, puis cliquez sur Propriétés. La fenêtre de propriétés doit ressembler à la Figure 5.

   Figure 5. Propriétés d’assembly dans le Global Assembly Cache

   

6. Copiez les valeurs à partir de la fenêtre de propriétés afin de spécifier le nom complet, la version, la culture et le jeton de clé publique. Dans cet exemple, le code source apparaît comme suit :

   def.Assembly = "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral,PublicKeyToken=12e5e5525fb3d28a";

7. Définissez la propriété Class. La propriété Class représente le nom complet de la classe qui contient le récepteur d’événements, au format espace_de_noms.classe. Dans cet exemple, le code source apparaît comme suit :

   def.Class = "MyReceiverAssembly.MyReceiverClass";

8. Définissez la propriété Type. Dans cet exemple, le code source apparaît comme suit :

   def.Type = SPEventReceiverType.ItemAdded;

9. Définissez la propriété Name. Cette propriété est facultative. Vous pouvez affecter un nom à votre définition de récepteur d’événements ou ignorer cette valeur. Dans cet exemple, le code source apparaît comme suit :

   def.Name = "My ItemAdded Event Receiver";

10. Définissez la propriété Synchronization. Cette propriété est facultative. Si vous ne spécifiez aucune valeur pour cette propriété, la valeur Default lui est affectée (autrement dit, SPEventReceiverSynchronization.Default). Par défaut, les événements Before sont synchrones et les événements After sont asynchrones. Dans cet exemple, le code source apparaît comme suit :

    def.Synchronization = SPEventReceiverSynchronization.Synchronous;

11. Définissez la propriété SequenceNumber. Cette propriété est facultative. Utilisez-la pour définir l’ordre dans lequel les événements sont déclenchés lorsqu’il existe plusieurs événements dans votre définition de récepteur d’événements. Si vous ne définissez pas cette valeur, la valeur par défaut 10000 lui est affectée. Vous pouvez lui assigner une valeur comprise entre 0 et (216)-1.

12. Enregistrez la définition de récepteur d’événements dans la base de données de contenu SharePoint en ajoutant l’instruction suivante :

    def.Update();

Voici le code source complet de la procédure précédente. Lorsque vous l’exécutez, votre événement est enregistré dans la liste Tâches du site https://localhost. Lorsque vous créez un élément dans la liste, votre événement ItemAdded se déclenche.

using (SPSite site = new SPSite("https://localhost"))
{
    using (SPWeb web = site.OpenWeb())
    {
        SPList list = web.Lists["Tasks"];
        SPEventReceiverDefinition def = list.EventReceivers.Add();
        def.Assembly = 
          "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=12e5e5525fb3d28a";
        def.Class = "MyReceiverAssembly.MyReceiverClass";
        def.Type = SPEventReceiverType.ItemAdded;
        def.Name = "My ItemAdded Event Receiver";
        def.Synchronization = SPEventReceiverSynchronization.Synchronous;
        def.SequenceNumber = 1000;
        def.Update();
    }
}

Modification d’événements

Le modèle objet SharePoint simplifie la modification et le redéploiement de votre code de récepteur d’événements. Les instructions suivantes illustrent comment apporter des modifications à l’exemple de projet MyReceiverAssembly.

Pour mettre à jour un récepteur d’événements

1. Dans Visual Studio, ouvrez votre projet (tel que le projet MyReceiverAssembly) et apportez vos modifications.

2. Regénérez le projet afin de créer une nouvelle build du fichier DLL.

3. Placez la nouvelle build de la DLL dans le Global Assembly Cache. Assurez-vous de remplacer ou de supprimer la DLL précédente.

4. Exécutez iisreset pour effacer le cache IIS et ainsi charger la nouvelle version de l’assembly dans le Global Assembly Cache. Cette action permet de s’assurer que SharePoint détecte vos modifications.

Utilisation de solutions SharePoint

L’alternative à l’utilisation du modèle objet SharePoint pour créer et déployer vos récepteurs d’événements consiste à recourir à des solutions SharePoint. Dans cette section, nous allons examiner le processus de création manuelle d’une solution de récepteur d’événements.

La création d’événements pour l’implémentation s’effectue de manière semblable que vous utilisiez des solutions SharePoint ou le modèle objet SharePoint. Appliquez la procédure de la section Création d’événements à l’aide du modèle objet pour créer vos événements.

La réelle différence entre ces deux approches d’implémentation d’événements réside dans la liaison, pour laquelle on utilise une Fonctionnalité SharePoint déployée dans un fichier de solution (.swp).

Liaison d’événements à l’aide de solutions

La procédure suivante permet de créer une Fonctionnalité SharePoint qui prend l’exemple d’événement (l’événement ItemAdded que nous avons créé dans la DLL MyReceiverAssembly) et le lie à la liste Tâches sur le site Web où vous souhaitez activer la Fonctionnalité.

Pour créer une Fonctionnalité SharePoint

1. Créez un dossier portant le même nom que la Fonctionnalité.

2. Dans ce nouveau dossier, créez deux fichiers XML nommés feature.xml et eventbinder.xml.

3. Activez IntelliSense dans les fichiers XML en accédant aux propriétés de fichiers et en ajoutant une référence au fichier de schéma cible (.xsd), qui se trouve dans le répertoire …/TEMPLATE/XML/wss.xsd.

   Normalement, vous devez recréer ce lien chaque fois que vous ouvrez le fichier XML. Toutefois, si vous travaillez dans un projet Visual Studio, il vous suffit d’ajouter le fichier de schéma au projet.

   Néanmoins, si vous créez fréquemment de nombreux fichiers CAML dans plusieurs projets Visual Studio, ce processus peut se révéler fastidieux. Une alternative consiste à charger simplement le fichier XSD chaque fois qu’un fichier XML faisant référence au schéma est ouvert. Pour cela, procédez comme suit.

   1. Recherchez le fichier XML nommé Catalog.xml dans le dossier d’installation de Visual Studio, qui est couramment C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas.

   2. Faites référence au fichier de schéma wss.xsd à partir du fichier Catalog.xml en ajoutant la balise suivante. Assurez-vous que la valeur href pointe vers l’emplacement correct du fichier wss.xsd.

      <Schema href="C:/Program Files/Common Files/Microsoft Shared/Web Server Extensions/12/TEMPLATE/XML/wss.xsd" targetNamespace="https://schemas.microsoft.com/sharepoint/" />

   Conseil
   Si vous utilisez Visual Studio 2010, vous pouvez ignorer l’Étape 3. Lorsque vous ouvrez un fichier XML qui contient l’attribut xmlns="https://schemas.microsoft.com/sharepoint/", Visual Studio 2010 ajoute automatiquement une référence à wss.xsd et active par conséquent IntelliSense.

4. Dans le fichier feature.xml, créez un élément <Feature>. Affectez à l’attribut xmlns la valeur « https://schemas.microsoft.com/sharepoint/ » affectez à l’attribut Id un identificateur global unique (GUID), affectez à l’attribut Scope la valeur « Web » et affectez à l’attribut Title la valeur « EventBinderFeature ».

   Important

   Pour l’attribut Id, vous devez fournir un GUID valide, que vous pouvez obtenir dans Visual Studio en exécutant guidgen.exe.

5. Dans l’élément <Feature>, ajoutez un élément <ElementManifests>.

6. Dans l’élément <ElementManifests>, ajoutez un élément <ElementManifest>. Affectez à l’attribut Location la valeur « eventbinder.xml ».

7. Dans le fichier eventbinder.xml, créez un élément <Elements>. Affectez à l’attribut xmlns la valeur « https://schemas.microsoft.com/sharepoint/ ».

8. Dans l’élément <Elements>, ajoutez un élément <Receivers>. Affectez à l’attribut ListUrl la valeur « Tasks ».

9. Dans l’élément <Receivers>, ajoutez un élément <Receiver>.

10. Dans l’élément <Receiver> ,ajoutez les éléments suivants, avec une valeur appropriée pour chacun :

    • <Assembly>

    • <Class>

    • <Type>

    • <Name>

    • <Synchronization>

    • <SequenceNumber>

Une fois cette procédure terminée, le fichier feature.xml doit ressembler à ce qui suit.

<Feature Id="E54C7FF5-1DF3-4B0B-8FFF-DB3185ECE8A6" 
         Scope="Web" 
         Title="Event Binder Feature"
         xmlns="https://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementManifest Location="eventbinder.xml" />
  </ElementManifests>
</Feature>

Et le fichier eventbinder.xml doit ressembler à ce qui suit.

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Receivers ListUrl="Lists/Tasks">
    <Receiver>
      <Assembly>MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, 
        PublicKeyToken=12e5e5525fb3d28a</Assembly>
      <Class>MyReceiverAssembly.MyReceiverClass</Class>
      <Type>ItemAdded</Type>
      <Name>My ItemAdded Event Receiver</Name>
      <Synchronization>Synchronous</Synchronization>
      <SequenceNumber>1000</SequenceNumber>
    </Receiver>
  </Receivers>
</Elements>

Empaquetage de la solution

Pour déployer des récepteurs d’événements sur votre installation de SharePoint, vous devez assembler les fichiers dans un fichier de package de solution (.wsp). Le fichier .wsp est simplement un fichier .cab dont l’extension de nom de fichier est .wsp.

Le fichier manifeste de solution indique à SharePoint ce qu’il faut faire avec les fichiers empaquetés dans le fichier .wsp. Par exemple, l’élément <FeatureManifest> indique que ce dossier est une Fonctionnalité SharePoint et doit par conséquent être déployé dans %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES et installé sur la batterie de serveurs. De même, l’élément <Assembly> indique que ce fichier est un assembly ; son attribut DeploymentTarget indique s’il faut déployer l’assembly dans le Global Assembly Cache ou dans un dossier bin d’application Web.

La préparation, la création et la modification du fichier manifest.xml s’effectuent comme suit :

Pour préparer le contenu de la solution

1. Créez un dossier nommé « EventSolution ».

2. Copiez le dossier de Fonctionnalité EventBinder dans le dossier EventSolution.

3. Copiez l’assembly MyReceiverAssembly.dll dans le dossier EventSolution.

4. Créez un fichier XML nommé « manifest.xml  dans le dossier EventSolution.

Pour modifier le fichier manifest.xml

1. Dans le fichier manifest.xml, créez un élément <Solution>. Affectez à l’attribut xmlns la valeur « https://schemas.microsoft.com/sharepoint/ », affectez à l’attribut SolutionId la valeur d’un GUID et affectez à l’attribut Title la valeur « Event Receiver Solution ».

2. Dans l’élément <Solution>, ajoutez un élément <FeatureManifests>.

3. Dans l’élément <FeatureManifests>, ajoutez un élément <FeatureManifest>. Affectez à l’attribut Location la valeur « EventBinder\feature.xml ».

4. Dans l’élément <Solution>, ajoutez un élément <Assemblies>.

5. Dans l’élément <Assemblies>, ajoutez un élément <Assembly>. Affectez à l’attribut Location la valeur « MyReceiverAssembly » et affectez à l’attribut DeploymentTarget la valeur « GlobalAssemblyCache ».

Le fichier manifest.xml doit maintenant ressembler à ce qui suit.

<Solution SolutionId="11C76135-CEEC-475B-9A93-67E5EF151B3C"
          Title="Event Receiver Solution"
          xmlns="https://schemas.microsoft.com/sharepoint/">
  <FeatureManifests>
    <FeatureManifest Location="EventBinder\feature.xml"/>
  </FeatureManifests>
  <Assemblies>
    <Assembly Location="MyReceiverAssembly" 
              DeploymentTarget="GlobalAssemblyCache">
    </Assembly>
  </Assemblies>
</Solution>

Maintenant que le contenu de la solution est prêt, il reste à créer le fichier DDF (Diamond Directive File). Un fichier DDF contient des informations utilisées par Microsoft Cabinet Maker (makecab.exe) pour identifier comment empaqueter et compresser les fichiers dans un fichier .cab. (Le fichier DDF proprement dit n’est pas placé dans le fichier .cab.)

Pour créer un fichier DDF

1. Dans le dossier EventSolution, créez un fichier nommé « cab.ddf ».

2. Ouvrez cab.dff dans un éditeur de texte, tel que le Bloc-notes, et ajoutez les informations suivantes.

   ;
   .OPTION EXPLICIT
   .Set CabinetNameTemplate=MyEventSolution.wsp 
   .set DiskDirectoryTemplate=CDROM
   .Set CompressionType=MSZIP
   .Set UniqueFiles="ON"
   .Set Cabinet=on
   .Set DiskDirectory1=Package
   manifest.xml manifest.xml
   MyReceiverAssembly.dll MyReceiverAssembly.dll
   EventBinder\feature.xml EventBinder\feature.xml
   EventBinder\EventBinder.xml EventBinder\EventBinder.xml
   

3. Enregistrez le fichier.

La directive OPTION EXPLICIT force la déclaration explicite de toutes les variables dans le fichier. L’affectation de la valeur « ON » à UniqueFiles permet de s’assurer que les fichiers de destination sont uniques. « ON » est la valeur par défaut, car le fait d’utiliser le même nom de fichier à deux reprises signifie généralement que le même fichier a été inclus accidentellement deux fois, ce qui constitue un gaspillage de l’espace disque.

Les quatre dernières lignes de ce fichier DDF sont les mappages de fichiers : le premier nom de chaque ligne est la source, tandis que le second nom est la destination.

Pour créer le fichier de package de solution, ouvrez une invite de commandes, naviguez jusqu’au dossier EventSolution et entrez la commande suivante :

makecab /F cab.ddf

Cabinet Maker crée le fichier .wsp dans un sous-dossier du dossier EventSolution nommé « Package W. Le nom du nouveau fichier est MyEventSolution.wsp.

Déploiement de la solution

SharePoint 2010 fournit deux genres de solutions : les solutions de batterie et les solutions solutions en bac à sable (sandbox). Les solutions en bac à sable (sandbox) sont importantes car elles permettent à l’administrateur d’une collection de sites de télécharger et d’activer des solutions au niveau de la collection de sites. Avec les solutions en bac à sable (sandbox), il n’est plus nécessaire de disposer d’un accès ordinateur aux fichiers WFE.

Toutefois, par définition l’utilisation de solutions en bac à sable (sandbox) limite le code qui peut être exécuté. Par exemple, si du code dans notre récepteur d’événements tente d’accéder au disque, le code s’exécute sans problème lorsque la solution est déployée comme solution de batterie. En revanche, si le récepteur d’événements est déployé comme solution en bac à sable (sandbox), une exception est levée au moment de l’exécution lors de la tentative d’accès au disque.

Pour déployer une solution de batterie

1. Téléchargez la solution dans le magasin de solutions de batterie en exécutant la commande Windows PowerShell suivante :

   Add-SPSolution -LiteralPath full_path_to_solution

2. Activez la solution en exécutant la commande suivante :

   Install-SPSolution solution_name.wsp -GACDeployment

Pour déployer une solution en bac à sable (sandbox)

1. Téléchargez la solution dans la galerie de solutions de la collection de sites en exécutant la commande Windows PowerShell suivante :

   Add-SPUserSolution -LiteralPath full_path_to_solution -Site siteUrl

2. Activez la solution en exécutant la commande suivante :

   Install-SPUserSolution solution_name.wsp -Site siteUrl

Lorsque la solution est déployée, les Fonctionnalités sont copiées dans le dossier TEMPLATE\FEATURES, les assemblys managés sont placés dans le Global Assembly Cache et les autres fichiers sont placés dans leurs dossiers respectifs sous TEMPLATES. Vous pouvez maintenant activer les Fonctionnalités.

Si vous devez retirer une solution, utilisez l’une des commandes Windows PowerShell suivantes :

• Solution de batterie : Uninstall-SPSolution solution_name.wsp

• Solution en bac à sable (sandbox) : Uninstall-SPUserSolution solution_name.wsp -Site siteUrl

Après avoir retiré une solution, vous pouvez la supprimer à l’aide de l’une des commandes suivantes :

• Solution de batterie : Remove-SPSolution solution_name.wsp

• Solution en bac à sable (sandbox) : Remove-SPUserSolution solution_name.wsp -Site siteUrl

Utilisation du modèle de récepteur d’événements dans Visual Studio 2010

Visual Studio 2010 fournit un ensemble étendu de modèles de projets SharePoint dans Microsoft Visual Basic et C#, notamment un modèle pour les récepteurs d’événements SharePoint. Le modèle de projet simplifie la gestion des événements pour les objets SharePoint tels que les sites, les listes, les flux de travail et autres éléments courants.

Lorsque vous créez un projet de récepteur d’événements à l’aide du modèle de projet Récepteur d’événements dans Visual Studio, certaines des étapes décrites dans cet article sont effectuées automatiquement, notamment la création et la signature de l’assembly, la création de la Fonctionnalité pour la liaison d’événement, l’empaquetage de solution, le déploiement et le débogage.

Pour créer un récepteur d’événements SharePoint à l’aide du modèle de projet Récepteur d’événements Visual Studio

1. Dans Visual Studio 2010, créez un projet à l’aide du modèle Récepteur d’événements SharePoint 2010.

2. Sélectionnez le niveau d’approbation de votre solution SharePoint en fonction de l’implémentation de votre code de récepteur d’événements. Si la solution ne nécessite pas d’accès au niveau des disques, du réseau ou du système, une solution en bac à sable (sandbox) est le choix le plus approprié car son utilisation est plus simple et plus probable.

3. Sélectionnez les événements à remplacer. Dans notre cas, nous souhaitons remplacer l’événement ItemAdded et le lier à la liste Tâches.

   • Quel type de récepteur d’événements voulez-vous ? Événements d’éléments de listes

   • Quel élément doit être la source d’événement ? Tâches

   • Gérer les événements suivants : un élément a été ajouté

4. Cliquez sur Terminer.

5. Dans l’événement ItemAdded, ajoutez votre code personnalisé.

6. Dans la barre de menus, cliquez sur Générer, puis sur Déployer la solution.

Votre solution est empaquetée, ajoutée et déployée ! Vous pouvez même définir un point d’arrêt dans votre code de récepteur d’événements et le déboguer.

Pour explorer plusieurs exemples pratiques d’utilisation du modèle d’événement SharePoint, consultez la seconde partie de cet article : Utilisation de récepteurs d’événements dans SharePoint Foundation 2010 (partie 2 / 2).

Ressources supplémentaires

Pour plus d’informations, voir les ressources suivantes :

• Utilisation de récepteurs d’événements dans SharePoint Foundation 2010 (partie 2 / 2)

• Utilisation de solutions

• Installation et déploiement d'une solution de batterie de serveurs

• Solutions en mode bac à sable

• Comment : créer un récepteur d’événements(éventuellement en anglais)

• Centre pour développeurs SharePoint