Des événements externes et les alertes dans SharePoint
Découvrez les concepts qui sous-tendent la création de récepteurs d’événements distants dans SharePoint qui peuvent être attachés à des listes externes et qui s’exécutent lorsque les données externes que la liste représente sont mises à jour.
Que sont les récepteurs d’événements ?
Un récepteur d’événements est un élément de code managé qui répond aux événements déclencheurs SharePoint tels que l’ajout, le déplacement, la suppression, l’archivage et l’extraction. Lorsque ces événements se produisent et que les critères du récepteur d’événements sont remplis, le code que vous écrivez pour fournir des fonctionnalités supplémentaires est exécuté. Lorsque des objets SharePoint, tels que des listes, des flux de travail et des fonctionnalités, sont configurés pour attendre que ces événements se produisent, ils sont appelés hôtes d’événements.
Récepteurs d'événements vous permettent d'effectuer une logique métier lorsque cet événement se produit un événement spécifique. Pour l'essentiel, il s'agit du hooks où vous pouvez créer le code pour gérer certaines conditions, émettre des notifications, mettre à jour les autres systèmes et ainsi de suite. Lorsque vous créez des récepteurs d'événements, une DLL est générée. Vous pouvez placer cette DLL dans le global assembly cache, de sorte que les récepteurs d'événements sont appelés en réponse à des modifications dans un système externe.
L'exemple suivant contient un récepteur d'événements d'externe simple en c# qui s'exécute lorsqu'un nouvel élément est ajouté à la liste.
public class EntryContentEventReceiver : SPItemEventReceiver
{
public override void ItemAdded(SPItemEventProperties properties)
{
base.ItemAdded(properties);
// properties.ExternalNotificationMessage holds the message sent by the external system
}
}
Les récepteurs d’événements externes peuvent également être étendus pour fonctionner sur un récepteur d’événements d’entité et en tant que récepteurs d’événements distants déployés en tant que service local ou dans Microsoft Azure.
Quelles sont les récepteurs d'événements distants ?
Les récepteurs d’événements distants sont des nouveautés pour SharePoint. Dans une solution SharePoint traditionnelle, vous utilisez un récepteur d'événements pour gérer des événements tels que les utilisateurs de créer ou supprimer des listes ou des éléments dans des listes. Dans un Complément SharePoint, vous utilisez un récepteur d'événements distants pour gérer les événements similaires. Récepteurs d'événements distants fonctionnent de la même manière pour les récepteurs d'événements régulière, sauf que les récepteurs d'événements distants gérer les événements qui se produisent lorsqu'un Complément SharePoint se trouve sur un autre système à partir de son application du web hôte.
Business Connectivity Services (BCS) utilise les récepteurs d'événements distants associés à des listes externes et les entités afin que vous puissiez écrire du code qui peut réagissent aux modifications des données hébergées dans le système externe.
Pour ce faire, deux stéréotypes ont été ajoutés au schéma du modèle BDC: EventSubscriber et EventUnsubscriber.
Remarque
[!REMARQUE] Récepteurs d'événements ne sont pas pris en charge dans les solutions en bac à sable.
Les fonctionnalités et les fonctionnalités de la nouvelle infrastructure de récepteur d'événements externes apporte-t-il ?
En utilisant et en étendant les fonctionnalités de récepteur d’événements SharePoint, BCS est en mesure d’ajouter des alertes, des récepteurs d’événements de liste externe et des récepteurs d’entités pour fournir des fonctionnalités étendues.
- Alertes: Les alertes font partie intégrante de SharePoint pour plusieurs versions, mais jusqu’à ce qu’elles soientPoint, elles ne fonctionnent pas avec les listes externes. Désormais un utilisateur peut créer des alertes sur une liste externe qui ont le même comportement en tant qu'alerte sur une liste SharePoint standard.
- Récepteurs d'événements de liste externe : Récepteurs d'événements peuvent maintenant être associés à des listes externes comme ils peuvent des listes standard. Cela fournit un mécanisme d’extensibilité qui vous permet d’écrire de qui est exécuté à des moments spécifiques.
- Récepteurs d'événements d'entité : Récepteurs d'événements d'entité flexibles en vous permettant d'écrire du code plus robuste qui permet d'autres opérations telles que la fourniture de contexte utilisateur pour le filtrage des données. Ceci peut permettre une meilleure personnalisation et sécurité personnalisée.
Les événements à distance dans SharePoint rendent possibles plusieurs scénarios intéressants. Par exemple, vous devrez peut-être une application « Sales Lead Tracking » qui permet à une équipe commerciale à être averti lorsque de nouveaux clients potentiels sont entrés dans une application externe responsable. Lorsqu'un nouveau prospect est entré, SharePoint est informé via le système de notification qui fait partie de l'application du responsable. SharePoint reçoit la notification, puis crée les nouvelles tâches pour les vendeurs spécifiés au sujet de chaque nouveau prospect. En configurant l'application de saisie de prospect sur le système externe pour envoyer une notification à SharePoint sur la création de chaque nouveau prospect, SharePoint est conservée à jour.
Conditions préalables à l'aide de récepteurs d'événements pour les listes externes
Pour utiliser des récepteurs d'événements pour les listes externes, vous devez les éléments suivants :
- SharePoint
- Visual Studio 2012
Pour plus d’informations sur la configuration d’un environnement de développement SharePoint, voir Configurer un environnement de développement général pour SharePoint.
Configurer le système externe pour informer SharePoint d'événements externes
Pour les événements externes fonctionner, un certain nombre de composants ont soit installé et configuré sur l'ordinateur hôte SharePoint et le système externe.
Vous devez configurer le système externe afin que cela peut être le suivant :
- Déterminer lorsque les modifications de données d'origine. Pour le système externe à connaître lorsque des modifications ont été apportées, vous devez créer un mécanisme d'interrogation de modifications spécifiques. Pour cela, à l'aide d'un service chronométré qui interroge la source de données à des intervalles spécifiques.
- Réception et enregistrer les demandes pour les abonnements aux notifications de modifications. Le système externe doit implémenter un magasin d'abonnement afin qu'il puisse stocker qui doit recevoir les notifications de modification. La solution la plus simple est probablement une table de base de données. La table (ou tout autre anisme que vous choisissez) doit enregistrer SubscriptionID, Adresse de livraison, Type d’événement et Nom de l’entité.
- Publier des notifications aux points de terminaison Representational State Transfer (REST). Pour informer les abonnés SharePoint qu’une modification s’est produite, l’application système externe doit envoyer une requête HTTPWebRequest à l’adresse de remise enregistrée dans le magasin d’abonnements. Cette adresse de remise est un point de terminaison RESTful généré par SharePoint pendant le processus d’abonnement
Configurer SharePoint pour autoriser la communication avec des systèmes externes
Pour permettre la communication avec le système externe, SharePoint doit être configuré avec les éléments suivants :
- Un modèle BDC avec EventSubscriber et EventUnsubscriber stéréotypes configuré
- Récepteurs d'événements
Comment les événements externes sont activé ?
Vous pouvez activer les événements externes dans SharePoint via les paramètres du site ou en ajoutant l’ID de fonctionnalité personnalisé suivant à votre projet
<ActivationDependency FeatureTitle="BCSEvents" FeatureId="60c8481d-4b54-4853-ab9f-ed7e1c21d7e4" />
Gestion des événements pour un système externe sont activée lorsque SharePoint crée l'adresse du destinataire et envoie au système externe au cours du processus de s'abonner.
Flux global d'événements externes entre SharePoint et des systèmes externes
Dans la Figure 1, notez qu'il existe trois étapes nécessaires lors de l'utilisation de récepteurs d'événements externes : s'abonner, notification et annuler l'abonnement.
Flux de données complète de la figure 1 pour les notifications externes
Flux de données pour les notifications d'événements externes
EventSubscriber : s'abonner aux notifications
Pour un utilisateur (objet SharePoint) recevoir des notifications lorsque les données sous-jacentes a été modifiée, l'utilisateur doit s'abonner aux notifications pour une entité. Pour cela, le schéma de modèle BDC a été étendu pour inclure le stéréotype Subscribe. Le stéréotype Subscribe est utilisé par SharePoint pour informer le système externe que l'expéditeur demande à être avertis des modifications apportées aux données sous-jacentes.
La figure 2 illustre le flux d'informations entre SharePoint et le système externe au cours du processus de s'abonner.
Figure 2. Flux de processus d’abonnement
Le tableau suivant décrit le flux général du processus d'abonnement :
Utilisateur demande un abonnement à des notifications. À l'aide d'une interface utilisateur personnalisée (un bouton sur une page ou un ruban), SharePoint lance une demande à l'application de système externe pour les notifications.
SharePoint génère une adresse de livraison. Dans le cadre du processus de s'abonner, SharePoint crée un point de terminaison REST où les notifications seront remises.
Demande d'abonnement est envoyée au système externe. SharePoint puis encapsule les informations du demandeur ainsi que l'URL de REST générée de manière dynamique et envoie une requête web au système externe.
Système externe reçoit la demande. Il existe différentes possibilités pour l'implémentation d'un magasin d'abonnement. Dans cet exemple, vous allez utiliser une table de base de données SQL Server.
Système externe génère un subscriptionId. Un nouveau subscriptionId est généré à l'aide de code dans l'application de métier (LOB). Le subscriptionId doit être un GUID.
Système externe enregistre l'abonnement. L'application de système externe enregistre la subscriptionId, adresse du destinataire, type d'événement et autres informations envoyées à partir de SharePoint dans le magasin de l'abonnement.
Système externe renvoie l'ID d'abonnement à SharePoint. Pour SharePoint router correctement les mises à jour qui sont envoyés par le système externe, le subscriptionId est renvoyé à SharePoint et SharePoint enregistre ces informations dans sa base de données.
Le modèle BDC fonctionne par rapport à une importation de fonction Subscribe. Les métadonnées pour l'importation de la fonction sont indiquée dans cet exemple.
<EntityType Name="EntitySubscribe">
<Key>
<PropertyRef Name="SubscriptionId" />
</Key>
<Property xmlns:p6="http://schemas.microsoft.com/ado/2009/02/edm/annotation"
Name="SubscriptionId"
Type="Edm.Int32"
Nullable="false"
p6:StoreGeneratedPattern="Identity" />
<Property Name="EntityName"
Type="Edm.String"
MaxLength="250"
FixedLength="false"
Unicode="true" />
<Property Name="DeliveryURL"
Type="Edm.String"
MaxLength="250"
FixedLength="false"
Unicode="true" />
<Property Name="EventType" Type="Edm.Int32" />
<Property Name="UserId"
Type="Edm.String"
MaxLength="50"
FixedLength="false"
Unicode="true" />
<Property xmlns:p6="http://schemas.microsoft.com/ado/2009/02/edm/annotation"
Name="SubscribeTime"
Type="Edm.Binary"
MaxLength="8"
FixedLength="true"
p6:StoreGeneratedPattern="Computed" />
<Property Name="SelectColumns"
Type="Edm.String"
MaxLength="10"
FixedLength="false"
Unicode="true" />
</EntityType>
Exemple de code : s'abonner le modèle BDC
Voici un exemple d'un modèle BDC avec la méthode Subscribe ajoutée.
<Method Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe" IsStatic="true">
<Properties>
<Property Name="ODataEntityUrl" Type="System.String">/EntitySubscribes</Property>
<Property Name="ODataHttpMethod" Type="System.String">POST</Property>
<Property Name="ODataPayloadKind" Type="System.String">Entry</Property>
<Property Name="ODataFormat" Type="System.String">application/atom+xml</Property>
<Property Name="ODataServiceOperation" Type="System.Boolean">false</Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal="NT Authority\\Authenticated Users">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
<Parameters>
<Parameter Direction="In" Name="@DeliveryURL">
<TypeDescriptor TypeName="System.String" Name="DeliveryURL" >
<Properties>
<Property Name="IsDeliveryAddress" Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@EventType">
<TypeDescriptor TypeName="System.Int32" Name="EventType" >
<Properties>
<Property Name="IsEventType" Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@EntityName">
<TypeDescriptor TypeName="System.String" Name="EntityName" >
<DefaultValues>
<DefaultValue MethodInstanceName="SubscribeCustomer"
Type="System.String">Customers</DefaultValue>
</DefaultValues>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@SelectColumns">
<TypeDescriptor TypeName="System.String" Name="SelectColumns" >
<DefaultValues>
<DefaultValue MethodInstanceName="SubscribeCustomer" Type="System.String">*</DefaultValue>
</DefaultValues>
</TypeDescriptor>
</Parameter>
<Parameter Direction="Return" Name="SubscribeReturn">
<TypeDescriptor Name="SubscribeReturnRootTd" TypeName="Microsoft.BusinessData.Runtime.DynamicType">
<TypeDescriptors>
<TypeDescriptor Name="SubscriptionId" TypeName="System.String" >
<Properties>
<Property Name="SubscriptionIdName" Type="System.String">Default</Property>
</Properties>
<Interpretation>
<ConvertType LOBType="System.Int32" BDCType="System.String"/>
</Interpretation>
</TypeDescriptor>
<TypeDescriptor Name="DeliveryURL" TypeName="System.String" />
<TypeDescriptor Name="SelectColumns" TypeName="System.String" >
</TypeDescriptor>
<TypeDescriptor Name="EntityName" TypeName="System.String" />
<TypeDescriptor Name="EventType" TypeName="System.Int32" />
<TypeDescriptor Name="UserId" TypeName="System.String" />
<!--TypeDescriptor Name="SubscribeTime" TypeName="System." /-->
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Type="EventSubscriber" ReturnParameterName="SubscribeReturn" ReturnTypeDescriptorPath="SubscribeReturnRootTd" Default="true" Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe">
<AccessControlList>
<AccessControlEntry Principal="NT Authority\\Authenticated Users">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
</MethodInstance>
</MethodInstances>
</Method>
Le tableau 1 répertorie les attributs importants du modèle BDC qui sont nécessaires pour que le stéréotype Subscribe puisse fonctionner.
Tableau 1. Attributs du modèle BDC
Attribut | Description |
---|---|
IsDeliveryAddress | Indicateur Boolean utilisé sur un TypeDescriptor pour indiquer si l'adresse de livraison fournie doit être utilisée pour fournir des notifications. |
IsEventType | Indicateur Boolean utilisé sur un TypeDescriptor pour indiquer si le type d'événement fourni doit être utilisée en tant que le type d'événement. Types d'événements valides sont ItemAdded, ItemUpdated, ItemDeletedet ainsi de suite. |
SubscriptionIdName | Chaîne utilisée sur un TypeDescriptor qui représente le nom d'un composant subscriptionId. |
Notifications
Dans SharePoint, l’infrastructure de gestion des événements a été améliorée pour permettre aux sources de données externes de notifier SharePoint lorsque des informations dans le système externe ont été modifiées. Puis, lorsque SharePoint reçoit une notification, des récepteurs d'événements qui sont associées à la liste externe SharePoint ou l'entité peuvent exécuter du code pour effectuer les actions spécifiées.
Lors de la création d'un abonnement, le système externe doit indiquer à SharePoint sur les modifications qui se sont produites sur une entité particulière. Le système externe est prévu pour fournir des notifications à l'adresse du destinataire prévu par SharePoint au système externe au cours du processus de s'abonner à l'aide d'une charge utile au format Atom d'OData.
La figure 3 illustre le flux de communication entre le système externe et SharePoint lorsqu'un nouvel enregistrement est ajouté aux données dans le système externe.
Processus de Notification de la figure 3
- Nouvel enregistrement est ajouté au système externe. Dans cet exemple, un nouvel enregistrement est ajouté au système externe à l'aide de l'interface utilisateur de l'application ou directement à la base de données.
- Application système externe est informée de la modification. L'application de système externe doit être informés des modifications qui sont produisent sur les données sous-jacentes. Il existe plusieurs façons d'effectuer cette opération. Vous pouvez utiliser des déclencheurs SQL qui se déclenchent lors de la modification des données dans des tables spécifiques, ou vous pouvez créer un mécanisme d'interrogation pour interroger le magasin de données pour que les modifications. Il existe d'autres méthodes pour y parvenir, mais chacun doivent être évaluées avec des performances à l'esprit.
- Système externe envoie la demande de notification à SharePoint à l'adresse du destinataire. Pour communiquer les modifications, une demande au format Atom doit être envoyé à l'adresse du destinataire qui est stocké dans le magasin d'abonnement de l'application métier.
Charge utile de notification
Dans l'élaboration de que la notification, le système LOB a pour créer une charge utile HTTP qui inclut deux tous les détails de l'élément qui a été modifié, ou simplement l'identité de l'élément qui a été modifié.
- Identité : Lorsque la charge utile est envoyée comme identité, la charge utile est supposée avoir uniquement des informations sur l'identité de l'élément modifié. Par exemple, pour un client dans une entité clients, la charge utile contient uniquement l'ID du client qui a été modifié.
- Complète item : Dans ce cas, la charge utile est un enregistrement complet qui a changé dans le système externe. Dans l'exemple de client, l'enregistrement modifié entière est inclus.
Remarque
[!REMARQUE] L'élément complet prend en charge uniquement lorsque vous utilisez le connecteur OData.
Le type de charge utile qui est envoyé par le système externe doit être indiqué pendant le processus d'abonnement.
Voici un exemple de la propriété de modèle BDC utilisé pour les notifications.
<Property Name="NotificationParserType" Type="System.String">
ODataEntryContentNotificationParser
</Property>
S'il n'est pas spécifié, la charge utile par défaut est une charge utile d'identité.
Adresse de livraison de notification (adresse virtuelle)
Le processus d'abonnement initié à partir de SharePoint entraîne une adresse virtuelle créé par SharePoint, ce qui permet d'un point d'entrée pour le système externe publier des notifications. L'adresse du destinataire est utilisée par le système externe pour valider ces notifications. L'adresse du destinataire est également transmis au système externe lors de la demande d'abonnement.
EventUnsubscriber : supprimez l'abonnement à partir de la liste de notifications
L'opération Unsubscribe supprime un abonnement à partir de la liste de notifications.
La figure 4 montre que la méthode UnSubscribe est beaucoup plus simple. Étant donné que l'ID d'abonnement a été envoyé dans SharePoint, et SharePoint enregistré, tout ce qui est nécessaire consiste à envoyer la demande de désabonnement avec l'ID d'abonnement correctes.
La figure 4 flux de Code pour la méthode de désabonnement
Modèle BDC pour annuler l'abonnement
L'exemple de code XML suivant montre comment vous pouvez créer un modèle BDC qui annule son abonnement à partir des notifications d'événements système externe.
<Method Name="UnSubscribeExpenseReport" DefaultDisplayName="ExpenseReport
Unsubscribe">
<Properties>
<Property Name="ODataEntityUrl" Type="System.String">
/Subscriptions(@ID)</Property>
<Property Name="ODataHttpMethod" Type="System.String">DELETE</Property>
<Property Name="ODataPayloadKind" Type="System.String">Property</Property>
<Property Name="ODataServiceOperation" Type="System.Boolean">false</Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal="NT Authority\\Authenticated Users">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
<Parameters>
<Parameter Name="@ID" Direction="In">
<TypeDescriptor Name="ID" TypeName="System.Int32">
<Properties>
<Property Name="SubscriptionIdName" Type="System.String">ID</Property>
</Properties>
<Interpretation>
<ConvertType LOBType="System.Int32" BDCType="System.String" />
</Interpretation>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Name="UnSubscribeExpenseReport" DefaultDisplayName="ExpenseReport
Unsubscribe" Type="EventUnsubscriber" Default="true">
<AccessControlList>
<AccessControlEntry Principal="NT Authority\\Authenticated Users">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
</MethodInstance>
</MethodInstances>
</Method>
<Method IsStatic="false" Name="Unsubscribe">
<AccessControlList>
<AccessControlEntry Principal="NT AUTHORITY\\Authenticated Users">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
<Parameters>
<Parameter Direction="In" Name="subscriptionId">
<TypeDescriptor TypeName="System.String" Name="subscriptionId"
IsSubscriptionId="true" />
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Type="EventUnsubscriber" Default="true" Name="Unsubscribe"
DefaultDisplayName="UnSubscriber">
<Properties>
<Property Name="LastDesignedOfficeItemType" Type="System.String">None</Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal=" NT AUTHORITY\\Authenticated Users ">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
</MethodInstance>
</MethodInstances>
</Method>
Exemple de code : attacher un récepteur d'événements à une liste externe
Le code suivant fournit un exemple illustrant comment attacher un récepteur d'événements à une liste externe. Une fois qu'il est connecté, le récepteur d'événements est à l'écoute des notifications à partir du système externe sur les mises à jour, les ajouts et suppressions effectuées sur les données natives.
private static void AddEventReceiver(string siteUrl, string listTitle)
{
string assembly = "SampleEventReceiver, Culture=neutral, Version=1.0.0.0,PublicKeyToken=1bfafa687d2e46a7";
string className = "SampleEventReceiver.EntryContentEventReceiver";
try
{
using (SPSite site = new SPSite(siteUrl))
{
using (SPWeb web = site.OpenWeb())
{
SPList list = web.Lists[listTitle];
list.EventReceivers.Add(SPEventReceiverType.ItemAdded, assembly, className);
}
}
}
catch (Exception e)
{
Console.WriteLine(e);
}
}
Aller : en savoir plus sur l'utilisation de récepteurs d'événements externes
Pour plus d'informations sur les événements et alertes externes, consultez les éléments suivants.
Tableau 2. Concepts avancés pour l’utilisation de récepteurs d’événements externes
Article | Description |
---|---|
Comment : créer un service de données OData pour une utilisation comme un système externe BCS | Découvrez comment créer un service Windows Communication Foundation (WCF) adressable sur Internet qui utilise OData pour envoyer des notifications à SharePoint lorsque les données sous-jacentes changent. Ces notifications sont utilisées pour décaper les événements qui sont attachés à des listes externes. |