Usar receptores de eventos remotos en SharePoint

Artículo
04/08/2023

Usar receptores de eventos remotos para controlar eventos en el modelo de complementos de SharePoint. Use los eventos AppInstalled y AppUninstalling para configurar o quitar objetos de SharePoint y otros receptores de eventos que necesite su complemento.

Se aplica a: Complementos de SharePoint | SharePoint 2013 | SharePoint Online

Importante A partir de enero de 2017 SharePoint Online admite webhooks de lista, que se pueden usar en lugar de receptores de eventos remotos "-ed". Para obtener más información sobre los webhooks, consulte Información general sobre los webhooks de SharePoint. Tenga en cuenta que existen varios ejemplos de webhooks en el repositorio de GitHub sp-dev-samples.

En el ejemplo Core.EventReceivers se muestra cómo usar un complemento hospedado por el proveedor con un receptor de eventos remoto para controlar los eventos AppInstalled y AppUninstalling. Los eventos AppInstalled y AppUninstalling configuran y quitan objetos de SharePoint que el complemento usa cuando se ejecuta. Además, el controlador de eventos AppInstalled agrega el controlador de eventos ItemAdded a una lista. Use esta solución si quiere:

Configurar el complemento en la primera ejecución usando el evento AppInstalled para configurar varios objetos de SharePoint o receptores de eventos adicionales con los que funciona el complemento.
Reemplazar receptores de eventos implementados con las soluciones de código de plena confianza. En las soluciones de código de plena confianza, puede ejecutar receptores de eventos en el servidor de SharePoint. En el nuevo modelo de complementos de SharePoint, puesto que no puede ejecutar el receptor de eventos en el servidor de SharePoint, deberá implementar un receptor de eventos remoto en un servidor web.
Recibir notificaciones de cambios que se producen en SharePoint. Por ejemplo, cuando se agrega un nuevo elemento a una lista, quiere realizar una tarea.
Complementar su solución de registro de cambios. Cuando se usa el patrón de registro de cambios con un patrón de receptor de eventos remotos, se obtiene una arquitectura más confiable para controlar todos los cambios realizados en las bases de datos de contenido, las colecciones de sitios, los sitios o las listas de SharePoint. Los receptores de eventos remotos se ejecutan inmediatamente pero, como lo hacen en un servidor remoto, se podría producir un error de comunicación. El patrón de registro de cambios garantiza que todos los cambios van a estar disponibles para su procesamiento, pero la aplicación encargada de procesarlos suele ejecutarse según una programación (por ejemplo, un trabajo del temporizador). Esto significa que los cambios no se procesan de inmediato. Si usa ambos patrones conjuntamente, procure usar un mecanismo que evite que el mismo cambio se procese dos veces. Para obtener más información, vea Consultar el registro de cambios de SharePoint con ChangeQuery y ChangeToken.

Nota:

Los complementos hospedados en SharePoint no admiten receptores de eventos remotos. Para usar receptores de eventos remotos, debe usar un complemento hospedado por el proveedor. No use receptores de eventos remotos para escenarios de sincronización o en procesos de larga duración. Para obtener más información, vea Cómo: Crear un receptor de eventos de complemento.

Antes de empezar

Para empezar, descargue el complemento de ejemplo Core.EventReceivers del proyecto Office 365 Patrones y prácticas para desarrolladores en GitHub.

Antes de ejecutar este complemento, siga estos pasos:

En las propiedades del proyecto Core.EventReceivers, compruebe que Handle App Installed and Handle App Uninstalling está establecido en True. Al establecer Controlar aplicación instalada y Administrar desinstalación de aplicaciones en True , se crea un servicio WCF que define el controlador de eventos para el evento AppInstalled y AppUninstalling . En Core.EventReceivers, abra el menú contextual (clic derecho) en AppManifest.xml y elija Propiedades. InstalledEventEndpoint y UninstallingEventEndpoint apuntan al receptor de eventos remoto que controla los eventos AppInstalled y AppUninstalling.
La asociación de un receptor de eventos remotos a un objeto en la web host normalmente requiere el permiso Administrar solo para ese objeto. Por ejemplo, al adjuntar un receptor de eventos a una lista existente, el complemento requiere tener permiso para Administrar solo en la Lista. Este ejemplo de código requiere permisos para Administrar en la Web ya que agrega una lista y activa una característica en la web del host. Para establecer permisos para administrar en la web:
1. Haga doble clic en Core.EventReceivers\AppManifest.xml.
2. Elija Permisos.
3. Compruebe que Ámbito está establecido en Web y Permiso establecido en Administrar.
Para ejecutar este ejemplo de código, necesita una suscripción de Azure. Para suscribirse a una prueba, vea Prueba gratuita de un mes.
Crear un espacio de nombres de Azure Service Bus
1. Siga las instrucciones que se ofrecen en el artículo sobre cómo Crear un espacio de nombres de Service Bus.
2. Copie Cadena de conexión principal desde el espacio de nombres de Service Bus recién creado
3. Vuelva a Visual Studio.
4. Haga clic con el botón derecho en Propiedades> Core.EventReceivers >de SharePoint.
5. Seleccione Habilitar depuración a través de Microsoft Azure Service Bus.
6. En Microsoft Azure Service Bus cadena de conexión, pegue la cadena de conexión.
7. Seleccione Guardar.
Ejecute el código de ejemplo y realice los siguientes pasos adicionales:
- Haga clic en Confiar en él en la ventana Conceder permisos a la aplicación .
- Cierre la ventana Conceder permisos a la aplicación .
- Cuando se complete la instalación del complemento y el servicio WCF, se abrirá el explorador.
- Inicie sesión en la cuenta de Office 365. Se muestra la página de inicio del complemento Core.EventReceivers.

Usar el complemento Core.EventReceivers

Para ver una demostración del ejemplo de código Core.EventReceivers:

Ejecute el ejemplo y, en la página de inicio, elija Volver al sitio.
Elija Contenidos del sitio.
Elija Trabajos del receptor de eventos remotos.
Elija Elemento nuevo.
En Título, escriba Contoso y, en Descripción , escriba Contoso test.
Vuelva a la lista y actualice la página.
Compruebe que la descripción del elemento recién agregado se actualizó a la prueba de Contoso Actualizada por ReR 192336, donde 192336 es una marca de tiempo.

En Services/AppEventReceiver.cs, AppEventReceiver implementa la interfaz IRemoteEventService . Este ejemplo de código proporciona una implementación para el método ProcessEvent ya que utiliza eventos sincrónicos. Si usa eventos asincrónicos, deberá proporcionar una implementación para el método ProcessOneWayEvent.

ProcessEvent controla los siguientes eventos remotos SPRemoteEventType:

Eventos AppInstalled al instalar el complemento. Cuando se produce un evento AppInstalled, ProcessEvent llama a HandleAppInstalled.
Eventos AppUninstalling al desinstalar el complemento. Cuando se produce un evento AppUninstalling, ProcessEvent llama a HandleAppUninstalling. El evento AppUninstalling solo se ejecuta cuando un usuario quita completamente el complemento mediante la eliminación del complemento de la papelera de reciclaje del sitio (para los usuarios finales) o quitando el complemento de la lista Aplicaciones en pruebas (para desarrolladores).
Eventos ItemAdded cuando se agrega un elemento a una lista. Cuando se produce un evento ItemAdded, ProcessEvent llama a HandleItemAdded.

Nota:

En las propiedades del proyecto Core.EventReceiver, solo están disponibles las propiedades Controlar aplicación instalada y Administrar desinstalación de aplicaciones. Este ejemplo de código muestra cómo agregar el controlador de eventos ItemAdded a una lista en la web del host utilizando el evento AppInstalled durante la instalación del complemento.

Nota:

El código de este artículo se proporciona tal cual, sin garantía de ningún tipo, expresa o implícita, incluidas las garantías implícitas de aptitud para un propósito particular, comerciabilidad o ausencia de infracción.

public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {

            SPRemoteEventResult result = new SPRemoteEventResult();

            switch (properties.EventType)
            {
                case SPRemoteEventType.AppInstalled:
                    HandleAppInstalled(properties);
                    break;
                case SPRemoteEventType.AppUninstalling:
                    HandleAppUninstalling(properties);
                    break;
                case SPRemoteEventType.ItemAdded:
                    HandleItemAdded(properties);
                    break;
            }


            return result;
        }

HandleAppInstalled llama a RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb en RemoteEventReceiverManager.cs.

 private void HandleAppInstalled(SPRemoteEventProperties properties)
        {
            using (ClientContext clientContext =
                TokenHelper.CreateAppEventClientContext(properties, false))
            {
                if (clientContext != null)
                {
                    new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
                }
            }
        }

AssociateRemoteEventsToHostWeb crea o habilita varios objetos de SharePoint que el complemento Core.EventReceivers usa. Los requisitos pueden ser distintos. AssociateRemoteEventsToHostWeb hace lo siguiente:

Habilita la característica de notificación push mediante Web.Features.Add.
Usa el objeto clientContext para buscar una lista. Si la lista no existe, CreateJobsList crea la lista. Si la lista existe, se usa List.EventReceivers para buscar un receptor de eventos existente cuyo nombre sea ItemAddedEvent.
Si el receptor de eventos ItemAddedEvent no existe:
- Crea una instancia de un nuevo objeto EventReceiverDefinitionCreationInformation para crear el nuevo receptor de eventos remotos. El tipo receptor de eventos ItemAdded se agrega a EventReceiverDefinitionCreationInformation.EventType.
- Establece EventReceiverDefinitionCreationInformation.ReceiverURL en la dirección URL del receptor de eventos remotos AppInstalled .
- Agrega un nuevo receptor de eventos a la lista mediante List.EventReceivers.Add.

public void AssociateRemoteEventsToHostWeb(ClientContext clientContext)
        {
            // Add Push Notification feature to host web.
            // Not required but it is included here to show you
            // how to activate features.
            clientContext.Web.Features.Add(
                     new Guid("41e1d4bf-b1a2-47f7-ab80-d5d6cbba3092"),
                     true, FeatureDefinitionScope.None);


            // Get the Title and EventReceivers lists.
            clientContext.Load(clientContext.Web.Lists,
                lists => lists.Include(
                    list => list.Title,
                    list => list.EventReceivers).Where
                        (list => list.Title == LIST_TITLE));

            clientContext.ExecuteQuery();

            List jobsList = clientContext.Web.Lists.FirstOrDefault();

            bool rerExists = false;
            if (null == jobsList)
            {
                // List does not exist, create it.
                jobsList = CreateJobsList(clientContext);

            }
            else
            {
                foreach (var rer in jobsList.EventReceivers)
                {
                    if (rer.ReceiverName == RECEIVER_NAME)
                    {
                        rerExists = true;
                        System.Diagnostics.Trace.WriteLine("Found existing ItemAdded receiver at "
                            + rer.ReceiverUrl);
                    }
                }
            }

            if (!rerExists)
            {
                EventReceiverDefinitionCreationInformation receiver =
                    new EventReceiverDefinitionCreationInformation();
                receiver.EventType = EventReceiverType.ItemAdded;

                // Get WCF URL where this message was handled.
                OperationContext op = OperationContext.Current;
                Message msg = op.RequestContext.RequestMessage;
                receiver.ReceiverUrl = msg.Headers.To.ToString();

                receiver.ReceiverName = RECEIVER_NAME;
                receiver.Synchronization = EventReceiverSynchronization.Synchronous;

                // Add the new event receiver to a list in the host web.
                jobsList.EventReceivers.Add(receiver);
                clientContext.ExecuteQuery();

                System.Diagnostics.Trace.WriteLine("Added ItemAdded receiver at " + receiver.ReceiverUrl);
            }
        }

Cuando se agrega un elemento a la lista Trabajos del receptor de eventos remotos , ProcessEvent en AppEventReceiver.svc.cs controla el evento ItemAdded y, a continuación, llama a HandleItemAdded. HandleItemAdded llama a RemoteEventReceiverManager.ItemAddedToListEventHandler. ItemAddedToListEventHandler recupera el elemento de lista que se agregó y agrega la cadena Actualiza por ReR a la descripción del elemento de lista.

 public void ItemAddedToListEventHandler(ClientContext clientContext, Guid listId, int listItemId)
        {
            try
            {
                List photos = clientContext.Web.Lists.GetById(listId);
                ListItem item = photos.GetItemById(listItemId);
                clientContext.Load(item);
                clientContext.ExecuteQuery();

                item["Description"] += "\nUpdated by RER " +
                    System.DateTime.Now.ToLongTimeString();
                item.Update();
                clientContext.ExecuteQuery();
            }
            catch (Exception oops)
            {
                System.Diagnostics.Trace.WriteLine(oops.Message);
            }

        }

Compartir a través de

Usar receptores de eventos remotos en SharePoint

Antes de empezar

Usar el complemento Core.EventReceivers

Vea también

Recursos adicionales