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

Résumé :  Grâce aux récepteurs d’événements dans Microsoft SharePoint Foundation 2010, votre code personnalisé peut réagir à des actions spécifiques qui 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
Exemples pratiques d’utilisation des événements
Exemple 1 : Diffusion d’annonces
Exemple 2 : Fractionnement d’éléments
Exemple 3 : Suivi des sources de documents
Exemple 4 : Annulation et redirection
Exemple 5 : Journalisation des événements
Conclusion
Ressources supplémentaires

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

Sommaire

• Exemples pratiques d’utilisation des événements

• Exemple 1 : Diffusion d’annonces

• Exemple 2 : Fractionnement d’éléments

• Exemple 3 : Suivi des sources de documents

• Exemple 4 : Annulation et redirection

• Exemple 5 : Journalisation des événements

• Conclusion

• Ressources supplémentaires

Cet article est la suite de l’article Utilisation de récepteurs d’événements dans SharePoint Foundation 2010 (Partie 1 sur 2).

Exemples pratiques d’utilisation des événements

Maintenant que vous avez une bonne compréhension du modèle d’événement dans Microsoft SharePoint Foundation 2010, vous pouvez commencer à utiliser la gestion des événements dans votre code. Le reste de cet article présente 5 exemples utilisant le modèle d’événement SharePoint de différentes façons :

• Diffusion d’annonces   Les annonces ajoutées à certains sites parmi les centaines de sites dans une collection de sites apparaissent toutes dans le composant WebPart Annonces sur le site racine.

• Fractionnement d’éléments   Quand un élément est ajouté à une liste, cet élément est automatiquement fractionné en deux éléments ou plus. Cet exemple illustre également l’annulation d’un événement sans erreur et l’utilisation des conteneurs de propriétés dans un récepteur d’événement Avant.

• Suivi des sources de documents   Lorsqu’un document d’une bibliothèque de documents est édité, une propriété de métadonnées est mise à jour. Cet exemple illustre la promotion et la rétrogradation de propriétés.

• Annulation et redirection   Lorsqu’une opération d’un utilisateur est annulée, l’utilisateur est redirigé vers une page d’erreur.

• Journalisation des événements   Chaque événement se produisant dans une collection de sites est consigné dans un élément d’une liste stockée sur le site.

Pour chacun de ces exemples, vous pouvez télécharger une solution Microsoft Visual Studio :

• SharePoint 2010 : utilisation de récepteurs d’événements, exemple 1 : Diffusion d’annonces (éventuellement en anglais)

• SharePoint 2010 : utilisation de récepteurs d’événements, exemple 2 : Fractionnement d’éléments (éventuellement en anglais)

• SharePoint 2010 : utilisation de récepteurs d’événements, exemple 3 : Suivi des sources de documents (éventuellement en anglais)

• SharePoint 2010 : utilisation de récepteurs d’événements, exemple 4 : Annulation et redirection (éventuellement en anglais)

• SharePoint 2010 : utilisation de récepteurs d’événements, exemple 5 : Journalisation des événements (éventuellement en anglais)

Pour vous aider à naviguer dans les exemples, vous trouverez ci-après une présentation du modèle d’événement SharePoint. Le tableau 3 liste tous les récepteurs d’événements SharePoint Foundation 2010 par étendue et spécifie les classes auxquelles ils appartiennent et les hôtes auxquels ils peuvent s’associer.

Tableau 3. Récepteurs d’événements regroupés par étendue

Exemple 1 : Diffusion d’annonces

Dans cet exemple, il existe une collection de sites qui contient des centaines de sites individuels ; sur le site racine, il existe un composant WebPart Annonces. Le but de ce scénario est que toutes les annonces affichées sur des sites individuels apparaissent dans le composant WebPart Annonces que vous avez placé sur le site racine de la collection de sites.

Téléchargez l’exemple de code : SharePoint 2010 : utilisation de récepteurs d’événements, exemple 1 : Diffusion d’annonces (éventuellement en anglais)

Conception

Supposons que le site racine de la collection de sites ait une liste Annonces, nous ajoutons d’abord le composant WebPart destiné à cette liste sur la page d’accueil du site racine.

Pour ajouter un composant WebPart Annonces

1. Accédez à la page d’accueil du site racine de la collection de sites.

2. Cliquez sur l’onglet Page, puis cliquez sur Modifier la page.

3. Cliquez sur l’onglet Insertion, puis cliquez sur Liste existante. Toutes les listes et les bibliothèques de documents du site racine sont affichées.

4. Sélectionnez la liste Annonces et cliquez sur Ajouter.

Ensuite, vous devez copier toutes les annonces qui ont été affichées sur des sous-sites dans la liste Annonces sur le site racine. Pour cela, créez un récepteur d’événements ItemAdded qui copie tout élément ayant été ajouté à une liste (basée sur le modèle de liste Annonces) dans la liste Annonces sur le site racine. Cette logique d’événements doit être déclenchée par chaque liste d’annonces appartenant à un site quelconque de la collection de sites (à l’exception de la liste Annonces sur le site racine).

Implémentation

Dans Microsoft Visual Studio 2010, créez un projet basé sur le modèle de projet Récepteur d’événements SharePoint 2010. Optez pour le déploiement de votre solution dans le bac à sable. Dans l’Assistant Personnalisation de SharePoint, sélectionnez la liste Annonces comme source d’événements et ItemAdded comme l’événement à remplacer, comme indiqué dans la figure 6.

Figure 6. Assistant Personnalisation de SharePoint

Cette action crée un nouveau composant fonctionnel (Feature) dont l’étendue est Web, ayant un élément <Receivers> qui relie le récepteur d’événements ItemAdded au modèle de liste Annonces (ListTemplateId="104"), comme indiqué dans l’extrait suivant.

<Receivers ListTemplateId="104">
  <Receiver>
    <Name>EventReceiver1ItemAdded</Name>
    <Type>ItemAdded</Type>
    <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
    <Class>BroadcastAnn.EventReceiver1.EventReceiver1</Class>
    <SequenceNumber>10000</SequenceNumber>
  </Receiver>
</Receivers>

Le tableau 4 explicite les divers éléments contenus dans l’élément <Receiver>.

Tableau 4. Éléments de l’élément Receiver (Récepteur)

Pour que l’événement se déclenche sur tous les sites dans la collection de sites, l’étendue du composant fonctionnel doit être remplacée par Site ; de cette façon, la fonctionnalité est activée lorsque nous activons le composant fonctionnel au niveau de la collection de sites au lieu de devoir l’activer sur chaque sous-site. Notez que l’étendue Site d’un composant fonctionnel renvoie à la collection de sites (voir Figure 7), tandis que l’étendue Web renvoie aux sites.

Figure 7. Définition de l’étendue de la fonctionnalité

Ensuite, vous devez ouvrir le fichier EventReceiver1.cs et ajouter du code à l’événement ItemAdded, qui copie l’élément qui a été ajouté à la liste Annonces sur le sous-site à la liste Annonces sur le site racine. Le code ajoute également au titre le nom de la personne ayant passé l’annonce et ajoute au corps l’URL du sous-site où l’annonce a été faite.

public override void ItemAdded(SPItemEventProperties properties)
{
    // Get a reference to the site collection.
    SPSite site = properties.OpenSite();

    // Get a reference to the current site.
    SPWeb currentWeb = properties.OpenWeb();

    // Get a reference to the root site.
    SPWeb rootWeb = site.RootWeb;

    // Skip if the root web is the same as the current web.
    if (rootWeb.Url == currentWeb.Url)
    {
        return;
    }

    // Get the current list.
    SPList currentList = properties.List;

    // Get the announcement list on the root site.
    SPList rootList = rootWeb.Lists["Announcements"];

    // Get the list item that was added.
    SPListItem currentListItem = properties.ListItem;

    // Add the announcement item to the list on the root web.
    SPListItem rootListItem = rootList.Items.Add();
    foreach (SPField field in currentList.Fields)
    {
        if (!field.ReadOnlyField)
        {
            rootListItem[field.Id] = currentListItem[field.Id];
        }
    }

    // Append the user display name to the title.
    rootListItem["Title"] += " - " + properties.UserDisplayName;

    // Append the web URL to the body.
    rootListItem["Body"] += string.Format("This announcements was made by {0} on subweb {1}",
      properties.UserLoginName, properties.WebUrl);

    rootListItem.Update();
}

Vous pouvez maintenant générer la solution et démarrer le débogueur. Ce processus crée votre solution, la déploie sur la collection de sites SharePoint et lance le navigateur sur la page d’accueil de votre collection de sites. Assurez-vous que votre collection de sites ait la liste Annonces.

Finalement, créez un sous-site basé sur le modèle de site Équipe. Ajoutez un élément à la liste Annonces et confirmez qu’une copie de l’élément soit affichée dans la liste Annonces sur le site racine, comme indiqué dans la figure 8.

Figure 8. Élément ajouté à la liste Annonces sur le site racine

Exemple 2 : Fractionnement d’éléments

Dans cet exemple, le but est d’ajouter un élément à une liste et que cet élément soit fractionné en deux nouveaux éléments. Par exemple, si un utilisateur ajoute un groupement Xbox 360, au lieu de l’ajout de cet élément, vous voulez que deux autres éléments soient ajoutés à la liste : « Xbox 360 » et « Kinect ». Un meilleur exemple est un scénario dans lequel vous téléchargez un fichier .zip dont le contenu est ensuite extrait avec chacun de ses fichiers ajouté en tant qu’élément distinct.

Pour prendre en charge ce scénario de fractionnement d’élément, cet exemple montre également comment annuler une action sans erreur sur un récepteur d’événements Avant.

Téléchargez l’exemple de code : SharePoint 2010 : utilisation de récepteurs d’événements, exemple 2 : Fractionnement d’éléments (éventuellement en anglais)

Conception

Ce projet nécessite trois types de contenu pour représenter les trois éléments, « Xbox 360 Bundle », « Xbox 360 » et « Kinect ». Dans ce scénario, nous avons seulement besoin des titres des éléments, de sorte que chacun des types de contenu hérite du type de contenu « Items » sans ajouter de champ supplémentaire.

Lorsqu’un nouvel élément basé sur le type de contenu « Xbox 360 Bundle » est ajouté, nous voulons soit supprimer cet élément soit annuler son ajout, puis créer deux autres éléments basés sur les types de contenu « Xbox 360 » et « Kinect ».

Pour cela, nous devons d’abord lier l’événement Avant ItemAdding au type de contenu « Xbox 360 Bundle ». L’événement ItemAdding crée les deux autres éléments et annule l’ajout de l’élément actuel. Comme nous ne voulons aucun déclenchement de logique lors de l’ajout d’un élément « Xbox 360 » ou « Kinect », nous ne lions pas ces types de contenu à des récepteurs d’événements. Pour simplifier, nous ne gérons pas les mises à jour, c’est-à-dire lorsque le type de contenu d’un élément « Xbox 360 » devient « Xbox 360 Bundle » ou « Kinect ».

Lors de l’annulation de l’ajout du type de contenu « Xbox 360 Bundle », nous ne voulons pas obtenir de message d’erreur. Comme nous accédons à l’élément étant ajouté dans un événement Avant (avant de soumettre les changements à la base de données de contenu), la propriété properties.ListItem est toujours null. Pour accéder aux champs de l’élément, nous devons utiliser le conteneur de propriétés properties.AfterProperties ; cela nous permet d’accéder aux données que nous voulons copier (juste le titre dans cet exemple), en se basant sur les noms internes des champs dans le schéma de liste.

Implémentation

Créez un projet Visual Studio 2010 basé sur le modèle Projet SharePoint vide. Optez pour le déploiement de votre solution en bac à sable. Cliquez avec le bouton droit sur le projet, puis sélectionnez Ajouter un nouvel élément. Sélectionnez Type de contenu, nommez l’élément Xbox360Bundle, puis cliquez sur Ajouter. Visual Studio crée le type de contenu nommé « nom_projet - Xbox360Bundle ».

Répétez ces étapes pour les deux autres types de contenu, en appliquant les noms Xbox360 et Kinect.

Ensuite, cliquez avec le bouton droit sur le projet et ajoutez un nouvel élément Récepteur d’événements nommé BundleEventReceiver. Sélectionnez Un élément est ajouté et cliquez sur Terminer. Cette étape crée une classe de récepteur d’événements qui remplace l’événement ItemAdding. Cependant, par défaut elle lie également l’événement à un modèle de liste. Nous voulons lier l’événement au type de contenu Xbox360Bundle au lieu du modèle de liste. Par conséquent, nous devons supprimer le fichier Elements.xml de liaison de l’événement (montré sélectionné dans la figure 9) et ajouter la liaison à l’intérieur du fichier Elements.xml du type de contenu Xbox360Bundle.

Figure 9. Liaison Elements.xml

Avant d’ajouter la liaison du récepteur d’événements, vérifiez que l’attribut Inherits du type de contenu dans Elements.xml est défini comme FALSE au lieu de TRUE ; sinon, la liaison du récepteur d’événements ne fonctionnera pas sur le type de contenu. Du fait de l’héritage interrompu, nous devons définir nous-mêmes toutes les références de champ. Nous devons donc ajouter une référence au champ Title. Le fichier Element.xml du type de contenu Xbox360Bundle doit ressembler à l’exemple suivant.

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <!-- Parent ContentType: Item (0x01) -->
  <ContentType ID="0x01004497ac28eb9a47fbabee43f48c3f5973"
               Name="Xbox360Bundle"
               Group="Custom Content Types"
               Description="My Content Type"
               Inherits="FALSE"
               Version="0">
    <FieldRefs>
      <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" 
                Name="Title" 
                Required="TRUE" 
                ShowInNewForm="TRUE" 
                ShowInEditForm="TRUE"/>
    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI="https://schemas.microsoft.com/sharepoint/events">
        <spe:Receivers xmlns:spe="https://schemas.microsoft.com/sharepoint/events">
          <Receiver>
            <Name>Item Adding Event</Name>
            <Type>ItemAdding</Type>
            <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
            <Class>ItemSplitting.BundleEventReceiver.BundleEventReceiver</Class>
            <SequenceNumber>10000</SequenceNumber>
          </Receiver>
        </spe:Receivers>
      </XmlDocument>
    </XmlDocuments>
  </ContentType>
</Elements>

Maintenant, intéressons-nous au fichier BundleEventReceiver.cs et ajoutons le code à l’événement ItemAdding, qui annule l’ajout de l’élément Xbox360Bundle et crée deux nouveaux éléments basés sur les types de contenu Xbox360 et Kinect.

public override void ItemAdding(SPItemEventProperties properties)
{
    // Get a reference to the current list.
    SPList list = properties.List;

    // Get the "Xbox360" content type.
    SPContentType xboxContentType = list.ContentTypes["XBox360"];

    // Get the "Kinect" content type.
    SPContentType kinectContentType = list.ContentTypes["Kinect"];

    // If any of the content types are null, they were not created.
    if (xboxContentType == null || kinectContentType == null)
    {
        properties.Status = SPEventReceiverStatus.CancelWithError;
        properties.ErrorMessage = "The Xbox360 and Kinect content types must be present.";
        return;
    }

    // Disable event firing so that ItemAdding is not called recursively.
    this.EventFiringEnabled = false;

    // Create the "Xbox360" item.
    SPListItem xboxItem = list.AddItem();
    xboxItem["Title"] = properties.AfterProperties["Title"] + " (Xbox 360)";
    xboxItem["ContentTypeId"] = xboxContentType.Id;
    xboxItem.Update();

    // Create the "Kinect" item.
    SPListItem kinectItem = list.AddItem();
    kinectItem["Title"] = properties.AfterProperties["Title"] + " (Kinect)";
    kinectItem["ContentTypeId"] = kinectContentType.Id;
    kinectItem.Update();

    // Re-enable event firing.
    this.EventFiringEnabled = true;

    // Cancel the creation of the "Xbox360Bundle" item but don't throw an error.
    properties.Status = SPEventReceiverStatus.CancelNoError;
}

Notez les détails importants suivants à propos du code précédent :

• Si l’un des types de contenu n’est pas lié à la liste, nous annulons l’événement ItemAdding et affichons le message d’erreur « The Xbox360 and Kinect content types must be present » (Les types de contenu Xbox360 et Kinect doivent exister). Notez qu’il est inutile d’ajouter l’instruction properties.Cancel = true.

• Pour éviter le cas où ItemAdding s’appelle lui-même de façon récursive (jusqu’à une limite dans la pile d’appels), nous désactivons le déclenchement d’événement avant l’ajout des éléments dans l’événement ItemAdding. Une fois tous les éléments ajoutés, nous réactivons le déclenchement d’événement.

• Nous utilisons l’expression properties.AfterProperties["field"] au lieu de properties.ListITem["field"] car ItemAdding est un événement Avant, ce qui signifie que l’élément de liste n’est pas encore créé et que properties.ListItem est null.

• Nous ne voulons pas ajouter l’élément que nous fractionnons. Donc, nous annulons l’événement sans générer d’erreur à l’aide de l’instruction properties.Status = SPEventReceiverStatus.CancelNoError. N’ajoutez pas l’instruction properties.Cancel=true, car cela remplacerait le comportement et génèrerait une erreur.

Vous pouvez maintenant générer la solution et démarrer le débogueur. Cela crée votre solution, la déploie sur la collection de sites SharePoint et lance le navigateur sur la page d’accueil de votre collection de sites.

L’étape suivante consiste à créer une liste et à lier les trois types de contenu à celle-ci. D’abord, assurez-vous qu’il est possible d’ajouter les types de contenu à cette liste. Pour cela, réglez Autoriser la gestion des types de contenu sur Oui dans la page des paramètres avancés de la liste. Puis, ajoutez les trois types de contenu comme indiqué dans la figure 10.

Figure 10. Liaison des types de contenu

Nous pouvons maintenant créer un élément dans la liste, basé sur le type de contenu Xbox360Bundle, comme indiqué dans la figure 11.

Figure 11. Création d’un élément

Lorsque vous cliquez sur Enregistrer, notez que l’élément n’est pas ajouté. Au lieu de cela, deux autres éléments sont ajoutés : Xbox360 et Kinect. Si nous supprimons le type de contenu Xbox360 ou Kinect de la liste, nous obtenons un message d’erreur lors de la tentative d’enregistrement.

Exemple 3 : Suivi des sources de documents

Avoir la possibilité d’utiliser des récepteurs d’événements pour manipuler des propriétés de documents est une fonctionnalité puissante. Cet exemple montre comment effectuer cela en implémentant la promotion et la rétrogradation de propriétés avec des récepteurs d’événements. En utilisant la promotion et la rétrogradation de propriétés, vous pouvez lire, ajouter ou mettre à jour des métadonnées de documents directement à partir du code d’un récepteur d’événements au moment de l’ajout d’un document à une bibliothèque de documents, ou même lorsqu’un document est édité dans une bibliothèque de documents.

Dans cet exemple, nous définissons la valeur de la propriété de métadonnée Source comme le titre de la bibliothèque de documents lorsque nous éditons le document.

Téléchargez l’exemple de code : SharePoint 2010 : utilisation de récepteur d’événements, exemple 3 : Suivi des sources de documents (éventuellement en anglais)

Conception

Dans cet exemple, nous créons un récepteur d’événements ItemUpdating qui se relie à toutes les bibliothèques de documents du site. Lorsqu’un document est enregistré dans la bibliothèque de documents, le code du gestionnaire d’événements ajoute ou met à jour la propriété de métadonnée Source avec le titre de la bibliothèque de documents.

Pour tester ce comportement, nous créons deux bibliothèques de documents et ajoutons un champ Source à chacune. Puis, nous chargeons un document Microsoft Word dans la première bibliothèque de documents et l’enregistrons. Ensuite, nous téléchargeons ce document Word, utilisons le client Word pour examiner ses métadonnées, puis chargeons le document dans l’autre bibliothèque de documents. Au chargement, la valeur du champ Source doit toujours être égale au titre de la bibliothèque de documents dans laquelle il a d’abord été chargé. Toutefois, lorsque nous enregistrons le document dans la nouvelle bibliothèque de documents, la valeur de sa propriété Source doit être remplacée par le titre de la nouvelle bibliothèque de documents. Nous examinons les métadonnées du document enregistré pour vérifier cela.

Implémentation

Le code suivant implémente l’événement ItemUpdating.

public override void ItemUpdating(SPItemEventProperties properties)
{
    string fieldInternalName = properties.List.Fields["Source"].InternalName;
    properties.AfterProperties[fieldInternalName] = properties.ListTitle;
}

Générez la solution et démarrez le débogueur. Ces actions effectuent toutes les opérations nécessaires pour créer la solution, la déployer sur la collection de sites SharePoint, puis lancer le navigateur sur la page d’accueil de votre collection de sites.

Créez une bibliothèque de documents et ajoutez-lui le champ Source. Pour ajouter le champ, accédez aux paramètres de la bibliothèque de documents, cliquez sur Ajouter à partir de colonnes de site existantes, sélectionnez le champ Source, cliquez sur Ajouter, puis cliquez sur OK.

Ensuite, chargez un document Word dans cette bibliothèque de documents. Notez que le champ Source est vide. Mais, lorsque vous cliquez sur Enregistrer, la valeur du champ Source est remplacée par le titre de votre bibliothèque de documents.

Téléchargez une copie du document sur votre ordinateur local. Créez une nouvelle bibliothèque de documents et ajoutez-lui le champ Source. Chargez le document dans cette bibliothèque de documents. Au chargement, notez que la valeur du champ Source est toujours égale au titre de la bibliothèque de documents dans laquelle le document a été enregistré pour la dernière fois.

Maintenant, cliquez sur Save. La valeur du champ Source est remplacée par le titre de votre nouvelle bibliothèque de documents.

Exemple 4 : Annulation et redirection

Cet exemple est basé sur un scénario dans lequel une opération de l’utilisateur est annulée (à cause d’une erreur ou pour toute autre raison), et l’utilisateur est redirigé vers une page d’erreur personnalisée.

Téléchargez l’exemple de code : SharePoint 2010 : Utilisation de récepteurs d’événements, exemple 4: Annulation et redirection (éventuellement en anglais)

Conception

Dans cet exemple, nous créons un récepteur d’événements Web et ajoutons du code à l’événement WebMoving, qui annule l’action de renommer l’URL du site et redirige l’utilisateur vers la page Paramètres du site. (Nous utilisons la page Paramètres du site pour simplifier cet exemple. Vous pourriez rediriger l’utilisateur vers une page de message d’erreur personnalisée.)

Implémentation

Créez un projet Visual Studio 2010 basé sur le modèle de projet Récepteur d’événements SharePoint 2010. Optez pour le déploiement de votre solution dans le bac à sable. Dans l’Assistant Personnalisation, sélectionnez Événements Web comme source d’événement et Un site est déplacé comme l’événement. Remplacez l’étendue de la fonctionnalité par Site.

Ajoutez le code suivant, qui annule l’événement affectant un nouveau nom et redirige l’utilisateur vers la page Paramètres du site.

public override void WebMoving(SPWebEventProperties properties)
{
    properties.Status = SPEventReceiverStatus.CancelWithRedirectUrl;
    properties.RedirectUrl = properties.Web.ServerRelativeUrl +
      "/_layouts/settings.aspx";
}

Générez la solution et démarrez le débogueur. Cela effectue toutes les opérations nécessaires pour créer la solution, la déployer sur la collection de sites SharePoint, puis lancer le navigateur sur la page d’accueil de votre collection de sites.

Ensuite, créez un sous-site et essayez de le renommer (nous devons créer un sous-site car il est impossible de renommer un site racine). Pour renommer le site, accédez à la page Paramètres du site. Dans la section Aspect, cliquez sur Titre, description et icône. Dans la zone Nom d’URL, entrez un nouveau nom de site. Cliquez sur OK.

La tentative de renommer le site échoue et vous êtes redirigé vers la page Paramètres du site.

Exemple 5 : Journalisation des événements

Cet exemple explore un scénario dans lequel du code de journalisation des événements capture chaque événement se produisant sur une collection de sites et l’enregistre en tant qu’élément dans une liste qui est maintenue sur le site.

Téléchargez l’exemple de code : SharePoint 2010 : Utilisation de récepteurs d’événements, exemple 5 : Journalisation des événements (éventuellement en anglais)

Conception

Le tableau 5 liste tous les événements SharePoint et identifie la liste dans laquelle chaque événement est consigné. Nous ne journalisons pas les événements SiteDeleting ou SiteDeleted car ils sont déclenchés lorsque la collection de sites est supprimée.

Tableau 5. Événements et journaux

Dans l’exemple, nous remplaçons toutes les méthodes d’événement de toutes les classes qui héritent de SPEventReceiverBase. Nous créons également une classe supplémentaire dans Common.cs, qui contient des méthodes d’assistance. Ensuite, nous lions les événements Après de façon synchrone afin que les listes correspondantes soient mises à jour avant que l’opération de l’utilisateur soit achevée. La fonctionnalité qui permet les liaisons d’événements est délimitée au niveau du site afin de gérer tous les événements déclenchés sur tous les sites de la collection de sites.

Implémentation

Créez un projet Visual Studio 2010 basé sur le modèle Projet SharePoint vide. Optez pour le déploiement de votre solution en bac à sable.

Pour chaque type d’événement du tableau 6, cliquez avec le bouton droit sur le projet, cliquez sur Ajouter, pointez sur Nouvel élément, puis cliquez sur Récepteur d’événements. Sélectionnez les propriétés d’événement listées dans le tableau, puis cliquez sur Terminer.

Tableau 6. Propriétés des nouveaux récepteurs d’événements

Pour gérer tous les événements d’éléments de liste, les événements de courrier électronique et les événements de flux de travail déclenchés sur toute liste (pas uniquement sur les listes personnalisées), supprimez les attributs ListTemplateId des éléments <Receivers> (remplacez <Receivers ListTemplateId="100"> simplement par <Receivers>).

Par défaut, les événements Après sont asynchrones. Tous vos événements Après doivent être synchrones, ajoutez donc l’élément <Synchronization> et attribuez-lui la valeur « Synchronous » sous chaque élément <Receiver> dans chaque fichier Elements.xml. Par exemple, l’événement WebDeleted doit ressembler à l’exemple suivant.

<Receiver>
  <Name>EventReceiver1WebDeleted</Name>
  <Type>WebDeleted</Type>
  <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
  <Class>PTCEventLogger.EventReceiver1.EventReceiver1</Class>
  <SequenceNumber>10000</SequenceNumber>
  <Synchronization>Synchronous</Synchronization>
</Receiver>

Remplacez l’étendue de la fonctionnalité par Site afin de gérer les événements déclenchés sur toute la collection de sites. Notez bien que la création d’un nouveau sous-site provoque le déclenchement des événements pour la création de site et tout ce qui doit être ajouté au site. Cela risquerait de consommer trop de ressources dans une solution en bac à sable (sandbox) et par conséquent pourrait faire échouer la création du site. Vous pouvez contourner ce problème potentiel en remplaçant Solution en mode bac à sable par False dans les propriétés du projet ou en remettant l’étendue de la fonctionnalité sur Web.

Ensuite, ajoutez une classe nommée common au projet et placez-la dans un fichier nommé Common.cs. Ajoutez les trois méthodes d’assistance suivantes à cette classe.

• IsBeforeEvent   Indique s’il s’agit d’un événement Avant ou Après.

  /// <summary>
  /// Indicates whether an event is a Before event or an After event.
  /// </summary>
  /// <param name="eventType"></param>
  /// <returns></returns>
  private static bool IsBeforeEvent(SPEventReceiverType eventType)
  {
      return (eventType < SPEventReceiverType.ItemAdded) ? true : false;
  }
  

• EnsureLogList   Détermine si une liste journal existe déjà ou non. Si elle existe, nous obtenons une référence à celle-ci. Sinon, nous créons la liste et retournons une référence à celle-ci.

  /// <summary>
  /// Ensures that the Logs list with the specified name is created.
  /// </summary>
  /// <param name="web"></param>
  /// <param name="listName"></param>
  /// <returns></returns>
  private static SPList EnsureLogList(SPWeb web, string listName)
  {
      SPList list = null;
      try
      {
          list = web.Lists[listName];
      }
      catch
      {
          // Create list.
          Guid listGuid = web.Lists.Add(listName, listName, SPListTemplateType.GenericList);
          list = web.Lists[listGuid];
          list.OnQuickLaunch = true;
  
          // Add the fields to the list.
          // No need to add "Title" because it is added by default.
          // We use it to set the event name.
          list.Fields.Add("Event", SPFieldType.Text, true);
          list.Fields.Add("Before", SPFieldType.Boolean, true);
          list.Fields.Add("Date", SPFieldType.DateTime, true);
          list.Fields.Add("Details", SPFieldType.Note, false);
  
          // Specify which fields to view.
          SPView view = list.DefaultView;
          view.ViewFields.Add("Event");
          view.ViewFields.Add("Before");
          view.ViewFields.Add("Date");
          view.ViewFields.Add("Details");
          view.Update();
  
          list.Update();
      }
  
      return list;
  }
  

• LogEvent   Crée un nouvel élément dans la liste spécifiée et consigne les détails de l’événement dans cet élément.

  /// <summary>
  /// Log the event to the specified list.
  /// </summary>
  /// <param name="web"></param>
  /// <param name="listName"></param>
  /// <param name="eventType"></param>
  /// <param name="details"></param>
  public static void LogEvent(SPWeb web, string listName, SPEventReceiverType eventType, 
    string details)
  {
      SPList logList = Common.EnsureLogList(web, listName);
      SPListItem logItem = logList.Items.Add();
      logItem["Title"] = string.Format("{0} triggered at {1}", eventType, DateTime.Now);
      logItem["Event"] = eventType.ToString();
      logItem["Before"] = Common.IsBeforeEvent(eventType);
      logItem["Date"] = DateTime.Now;
      logItem["Details"] = details;
      logItem.Update();
  }
  

Pour chaque classe qui hérite de SPWebEventReceiver, SPListEventReceiver, SPEmailEventReceiver, SPItemEventReceiver ou SPWorkflowEventReceiver, vous devez créer une méthode Log pour gérer la journalisation des propriétés de l’événement dans la liste correspondante. Vous devez également modifier toutes les méthodes substituées pour appeler ces méthodes Log. Les extraits de code suivants montrent comment effectuer cela pour chaque récepteur d’événements.

• SPWebEventReceiver   Changez tous les événements substitués. Voici un exemple qui montre comment changer l’un de ces événements.

  public override void WebProvisioned(SPWebEventProperties properties)
  {
      this.LogWebEventProperties(properties);
  }
  

  Ajoutez la méthode Log, comme indiqué dans le code suivant.

  private void LogWebEventProperties(SPWebEventProperties properties)
  {
      // Specify the log list name.
      string listName = "WebEventLogger";
  
      // Create string builder object.
      StringBuilder sb = new StringBuilder();
  
      // Add properties that do not throw exceptions.
      sb.AppendFormat("Cancel: {0}\n", properties.Cancel);
      sb.AppendFormat("ErrorMessage: {0}\n", properties.ErrorMessage);
      sb.AppendFormat("EventType: {0}\n", properties.EventType);
      sb.AppendFormat("FullUrl: {0}\n", properties.FullUrl);
      sb.AppendFormat("NewServerRelativeUrl: {0}\n", properties.NewServerRelativeUrl);
      sb.AppendFormat("ParentWebId: {0}\n", properties.ParentWebId);
      sb.AppendFormat("ReceiverData: {0}\n", properties.ReceiverData);
      sb.AppendFormat("RedirectUrl: {0}\n", properties.RedirectUrl);
      sb.AppendFormat("ServerRelativeUrl: {0}\n", properties.ServerRelativeUrl);
      sb.AppendFormat("SiteId: {0}\n", properties.SiteId);
      sb.AppendFormat("Status: {0}\n", properties.Status);
      sb.AppendFormat("UserDisplayName: {0}\n", properties.UserDisplayName);
      sb.AppendFormat("UserLoginName: {0}\n", properties.UserLoginName);
      sb.AppendFormat("WebId: {0}\n", properties.WebId);
      sb.AppendFormat("Web: {0}\n", properties.Web);
  
      // Log the event to the list.
      this.EventFiringEnabled = false;
      Common.LogEvent(properties.Web, listName, properties.EventType, sb.ToString());
      this.EventFiringEnabled = true;
  }
  

• SPListEventReceiver   Changez tous les événements substitués. Voici un exemple qui montre comment changer l’un de ces événements.

  public override void FieldAdded(SPListEventProperties properties)
  {
      this.LogListEventProperties(properties);
  }
  

  Ajoutez la méthode Log, comme indiqué dans le code suivant.

  private void LogListEventProperties(SPListEventProperties properties)
  {
      // Specify the log list name.
      string listName = "ListEventLogger";
  
      // Create the string builder object.
      StringBuilder sb = new StringBuilder();
  
      // Add properties that do not throw exceptions.
      sb.AppendFormat("Cancel: {0}\n", properties.Cancel);
      sb.AppendFormat("ErrorMessage: {0}\n", properties.ErrorMessage);
      sb.AppendFormat("EventType: {0}\n", properties.EventType);
      sb.AppendFormat("FeatureId: {0}\n", properties.FeatureId);
      sb.AppendFormat("FieldName: {0}\n", properties.FieldName);
      sb.AppendFormat("FieldXml: {0}\n", properties.FieldXml);
      sb.AppendFormat("ListId: {0}\n", properties.ListId);
      sb.AppendFormat("ListTitle: {0}\n", properties.ListTitle);
      sb.AppendFormat("ReceiverData: {0}\n", properties.ReceiverData);
      sb.AppendFormat("RedirectUrl: {0}\n", properties.RedirectUrl);
      sb.AppendFormat("SiteId: {0}\n", properties.SiteId);
      sb.AppendFormat("Status: {0}\n", properties.Status);
      sb.AppendFormat("TemplateId: {0}\n", properties.TemplateId);
      sb.AppendFormat("UserDisplayName: {0}\n", properties.UserDisplayName);
      sb.AppendFormat("UserLoginName: {0}\n", properties.UserLoginName);
      sb.AppendFormat("WebId: {0}\n", properties.WebId);
      sb.AppendFormat("WebUrl: {0}\n", properties.WebUrl);
      sb.AppendFormat("Web: {0}\n", properties.Web);
      sb.AppendFormat("List: {0}\n", properties.List);
  
      // Add properties that might throw exceptions.
      try
      {
          sb.AppendFormat("Field: {0}\n", properties.Field);
      }
      catch (Exception e)
      {
          sb.AppendFormat("\nError accessing properties.Field:\n\n {0}", e);
      }
  
      // Log the event to the list.
      this.EventFiringEnabled = false;
      Common.LogEvent(properties.Web, listName, properties.EventType, sb.ToString());
      this.EventFiringEnabled = true;
  }
  

• SPEmailEventReceiver   Changez l’événement EmailReceived de la manière suivante.

  public override void EmailReceived(SPList list, SPEmailMessage emailMessage, String receiverData)
  {
      // Specify the log list name.
      string listName = "ListEmailEventLogger";
  
      // Create the string builder object.
      StringBuilder sb = new StringBuilder();
  
      // Add the email message properties.
      sb.AppendFormat("From:\t {0}\n", emailMessage.Sender);
      sb.AppendFormat("To:\t {0}\n", emailMessage.Headers["To"]);
      sb.AppendFormat("Subject:\t {0}\n", emailMessage.Headers["Subject"]);
      sb.AppendFormat("Body:\t {0}\n", emailMessage.PlainTextBody);
  
      // Log the event to the list.
      Common.LogEvent(list.ParentWeb, listName, SPEventReceiverType.EmailReceived, sb.ToString());
  }
  

• SPItemEventReceiver   Changez tous les événements substitués. Voici un exemple qui montre comment changer l’un de ces événements.

  public override void ItemAttachmentAdded(SPItemEventProperties properties)
  {
      this.LogItemEventProperties(properties);
  }
  Add the log method.
  private void LogItemEventProperties(SPItemEventProperties properties)
  {
      // Specify the log list name.
      string listName = "ListItemEventLogger";
  
      // Create the string builder object.
      StringBuilder sb = new StringBuilder();
  
      // Add properties that do not throw exceptions.
      sb.AppendFormat("AfterUrl: {0}\n", properties.AfterUrl);
      sb.AppendFormat("BeforeUrl: {0}\n", properties.BeforeUrl);
      sb.AppendFormat("Cancel: {0}\n", properties.Cancel);
      sb.AppendFormat("CurrentUserId: {0}\n", properties.CurrentUserId);
      sb.AppendFormat("ErrorMessage: {0}\n", properties.ErrorMessage);
      sb.AppendFormat("EventType: {0}\n", properties.EventType);
      sb.AppendFormat("ListId: {0}\n", properties.ListId);
      sb.AppendFormat("ListItemId: {0}\n", properties.ListItemId);
      sb.AppendFormat("ListTitle: {0}\n", properties.ListTitle);
      sb.AppendFormat("ReceiverData: {0}\n", properties.ReceiverData);
      sb.AppendFormat("RedirectUrl: {0}\n", properties.RedirectUrl);
      sb.AppendFormat("RelativeWebUrl: {0}\n", properties.RelativeWebUrl);
      sb.AppendFormat("SiteId: {0}\n", properties.SiteId);
      sb.AppendFormat("Status: {0}\n", properties.Status);
      sb.AppendFormat("UserDisplayName: {0}\n", properties.UserDisplayName);
      sb.AppendFormat("UserLoginName: {0}\n", properties.UserLoginName);
      sb.AppendFormat("Versionless: {0}\n", properties.Versionless);
      sb.AppendFormat("WebUrl: {0}\n", properties.WebUrl);
      sb.AppendFormat("Web: {0}\n", properties.Web);
      sb.AppendFormat("Zone: {0}\n", properties.Zone);
      sb.AppendFormat("Context: {0}\n", properties.Context);
  
      // Add properties that might throw exceptions.
      try
      {
          sb.AppendFormat("ListItem: {0}\n", properties.ListItem);
      }
      catch (Exception e)
      {
          sb.AppendFormat("\nError accessing properties.ListItem:\n\n {0}", e);
      }
  
      // Add AfterProperties property bag.
      sb.AppendFormat("AfterProperties: {0}\n", properties.AfterProperties);
      IEnumerator afterProperties = properties.AfterProperties.GetEnumerator();
      int i = 0;
      while (afterProperties.MoveNext())
      {
          DictionaryEntry entry = (DictionaryEntry)afterProperties.Current;
          sb.AppendFormat("[{0}]: ({1}, {2})\n", i++, entry.Key, entry.Value);
      }
      sb.AppendFormat("AfterProperties.ChangedProperties: {0}\n", 
        properties.AfterProperties.ChangedProperties);
      IEnumerator changedAfterProperties = 
        properties.AfterProperties.ChangedProperties.GetEnumerator();
      i = 0;
      while (changedAfterProperties.MoveNext())
      {
          DictionaryEntry entry = (DictionaryEntry)changedAfterProperties.Current;
          sb.AppendFormat("[{0}]: ({1}, {2})\n", i++, entry.Key, entry.Value);
      }
  
      // Add BeforeProperties property bag.
      sb.AppendFormat("BeforeProperties: {0}\n", properties.BeforeProperties);
      IEnumerator beforeProperties = properties.BeforeProperties.GetEnumerator();
      i = 0;
      while (beforeProperties.MoveNext())
      {
          DictionaryEntry entry = (DictionaryEntry)beforeProperties.Current;
          sb.AppendFormat("[{0}]: ({1}, {2})\n", i++, entry.Key, entry.Value);
      }
      sb.AppendFormat("BeforeProperties.ChangedProperties: {0}\n", 
        properties.BeforeProperties.ChangedProperties);
      IEnumerator changedBeforeProperties = 
        properties.BeforeProperties.ChangedProperties.GetEnumerator();
      i = 0;
      while (changedBeforeProperties.MoveNext())
      {
          DictionaryEntry entry = (DictionaryEntry)changedBeforeProperties.Current;
          sb.AppendFormat("[{0}]: ({1}, {2})\n", i++, entry.Key, entry.Value);
      }
  
      // Log the event to the list.
      this.EventFiringEnabled = false;
      Common.LogEvent(properties.Web, listName, properties.EventType, sb.ToString());
      this.EventFiringEnabled = true;
  }
  

• SPWorkflowEventReceiver   Changez tous les événements substitués. Voici un exemple qui montre comment changer l’un de ces événements.

  public override void WorkflowStarting(SPWorkflowEventProperties properties)
  {
      this.LogWorkflowEventProperties(properties);
  }
  

  Ajoutez la méthode Log, comme indiqué dans le code suivant.

  private void LogWorkflowEventProperties(SPWorkflowEventProperties properties)
  {
      // Specify the log list name.
      string listName = "WorkflowEventLogger";
  
      // Create the string builder object.
      StringBuilder sb = new StringBuilder();
  
      // Add properties that do not throw exceptions.
      sb.AppendFormat("AssociationData: {0}\n", properties.AssociationData);
      sb.AppendFormat("Cancel: {0}\n", properties.Cancel);
      sb.AppendFormat("CompletionType: {0}\n", properties.CompletionType);
      sb.AppendFormat("ErrorMessage: {0}\n", properties.ErrorMessage);
      sb.AppendFormat("EventType: {0}\n", properties.EventType);
      sb.AppendFormat("InitiationData: {0}\n", properties.InitiationData);
      sb.AppendFormat("InstanceId: {0}\n", properties.InstanceId);
      sb.AppendFormat("PostponedEvent: {0}\n", properties.PostponedEvent);
      sb.AppendFormat("ReceiverData: {0}\n", properties.ReceiverData);
      sb.AppendFormat("RedirectUrl: {0}\n", properties.RedirectUrl);
      sb.AppendFormat("RelativeWebUrl: {0}\n", properties.RelativeWebUrl);
      sb.AppendFormat("SiteId: {0}\n", properties.SiteId);
      sb.AppendFormat("Status: {0}\n", properties.Status);
      sb.AppendFormat("TerminatedByUserId: {0}\n", properties.TerminatedByUserId);
      sb.AppendFormat("WebUrl: {0}\n", properties.WebUrl);
  
      // Get activation properties.
      SPWorkflowActivationProperties activationProperties = properties.ActivationProperties;
      if (activationProperties != null)
      {
          sb.AppendFormat("ActivationProperties.AssociationData: {0}\n", 
            activationProperties.AssociationData);
          sb.AppendFormat("ActivationProperties.HistoryListId: {0}\n", 
            activationProperties.HistoryListId);
          sb.AppendFormat("ActivationProperties.HistoryListUrl: {0}\n", 
            activationProperties.HistoryListUrl);
          sb.AppendFormat("ActivationProperties.InitiationData: {0}\n", 
            activationProperties.InitiationData);
          sb.AppendFormat("ActivationProperties.ItemId: {0}\n", 
            activationProperties.ItemId);
          sb.AppendFormat("ActivationProperties.ItemUrl: {0}\n", 
            activationProperties.ItemUrl);
          sb.AppendFormat("ActivationProperties.ListId: {0}\n", 
            activationProperties.ListId);
          sb.AppendFormat("ActivationProperties.ListUrl: {0}\n", 
            activationProperties.ListUrl);
          sb.AppendFormat("ActivationProperties.Originator: {0}\n", 
            activationProperties.Originator);
          sb.AppendFormat("ActivationProperties.OriginatorEmail: {0}\n", 
            activationProperties.OriginatorEmail);
          sb.AppendFormat("ActivationProperties.SiteId: {0}\n", 
            activationProperties.SiteId);
          sb.AppendFormat("ActivationProperties.SiteUrl: {0}\n", 
            activationProperties.SiteUrl);
          sb.AppendFormat("ActivationProperties.TaskListId: {0}\n", 
            activationProperties.TaskListId);
          sb.AppendFormat("ActivationProperties.TaskListUrl: {0}\n", 
            activationProperties.TaskListUrl);
          sb.AppendFormat("ActivationProperties.TemplateName: {0}\n", 
            activationProperties.TemplateName);
          sb.AppendFormat("ActivationProperties.WebId: {0}\n", 
            activationProperties.WebId);
          sb.AppendFormat("ActivationProperties.WebUrl: {0}\n", 
            activationProperties.WebUrl);
          sb.AppendFormat("ActivationProperties.WorkflowId: {0}\n", 
            activationProperties.WorkflowId);
  
          // Add properties that might throw exceptions.
          try
          {
              sb.AppendFormat("ActivationProperties.Context: {0}\n", 
                activationProperties.Context);
              sb.AppendFormat("ActivationProperties.HistoryList: {0}\n", 
                activationProperties.HistoryList);
              sb.AppendFormat("ActivationProperties.Item: {0}\n", 
                activationProperties.Item);
              sb.AppendFormat("ActivationProperties.List: {0}\n", 
                activationProperties.List);
              sb.AppendFormat("ActivationProperties.OriginatorUser: {0}\n", 
                activationProperties.OriginatorUser);
              sb.AppendFormat("ActivationProperties.Site: {0}\n", 
                activationProperties.Site);
              sb.AppendFormat("ActivationProperties.TaskList: {0}\n", 
                activationProperties.TaskList);
              sb.AppendFormat("ActivationProperties.Web: {0}\n", 
                activationProperties.Web);
              sb.AppendFormat("ActivationProperties.Workflow: {0}\n", 
                activationProperties.Workflow);
          }
          catch (Exception e)
          {
              sb.AppendFormat("\nError accessing ActivationProperties property:\n\n {0}", e);
          }
      }
      else
      {
          sb.AppendFormat("ActivationProperties is null\n");
      }
  
      // Log the event to the list.
      this.EventFiringEnabled = false;
      Common.LogEvent(properties.ActivationProperties.Web, listName, 
        properties.EventType, sb.ToString());
      this.EventFiringEnabled = true;
  }
  

Conclusion

Vous connaissez maintenant le modèle d’événement SharePoint 2010 complètement, savez créer des récepteurs d’événements et déployer des projets qui implémentent des récepteurs d’événements. Vous savez aussi l’économie de travail que représente l’utilisation du modèle de projet Récepteur d’événements dans Visual Studio 2010. Vous disposez également de quelques exemples pratiques que vous pouvez adapter à vos propres besoins. Si vous souhaitez plus de détails sur le modèle d’événement SharePoint, consultez le SDK SharePoint 2010, en commençant par Événements dans SharePoint Foundation 2010.

Ressources supplémentaires

Pour plus d’informations, voir les ressources suivantes :

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

• Utilisation de solutions

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

• Solutions en mode bac à sable

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

• Centre pour développeurs SharePoint