Controlar eventos en los complementos de SharePoint
El código personalizado puede controlar tres categorías de eventos en complementos hospedados por el proveedor:
- Eventos de lista, como agregar o eliminar una lista en un sitio web.
- Eventos de elementos de lista, como editar un elemento en una lista.
- Eventos de complemento, como la instalación de un complemento.
Los complementos de SharePoint hospedados en SharePoint no admiten el control de eventos, pero se puede convertir un flujo de trabajo en un tipo de lista o controlador de eventos de elemento de lista estableciendo un evento que desencadene el flujo de trabajo. Para obtener más información, vea Flujos de trabajo de SharePoint. Los flujos de trabajo no pueden desencadenarse mediante eventos de complemento, por lo que estos no pueden controlarse con un complemento hospedado por SharePoint.
Nota:
Los eventos de sitio web y de colección de sitios no son compatibles con complementos de SharePoint.
Existen dos tipos de eventos:
Los eventos previos se desencadenan antes de que la infraestructura de SharePoint ejecute alguno de sus propios controles del evento (como la validación de cambios en la base de datos de contenido). En SharePoint, los controladores de eventos previos personalizados siempre se ejecutan de forma sincrónica. Entre otros fines, pueden usarse para cancelar el evento. Por ejemplo, si un complemento tiene una función para eliminar una lista, un controlador para el evento de eliminación de lista puede cancelar la eliminación si no se cumplen determinadas condiciones. Si el evento forma parte de una secuencia de eventos, al cancelarlo se impide que se produzca alguno de los eventos posteriores. Por ejemplo, si el controlador del evento ItemAdding cancela el evento, el evento ItemAdded, que normalmente se produce más adelante, no se desencadena.
Los eventos posteriores se desencadenan después de que la infraestructura de SharePoint ejecute alguno de sus propios controles del evento. En SharePoint, los controladores de eventos posteriores remotos, para eventos de lista y de elemento de lista, siempre se ejecutan de forma asincrónica. (Los eventos de aplicación son una excepción). Entre otros fines, pueden usarse para registrar los eventos.
Controlar eventos de lista y de elemento de lista
Para controlar eventos de lista y elemento de lista, se deben crear receptores de eventos remotos (RER), que son servicios web que se ejecutan de forma externa a la granja de SharePoint o SharePoint Online. La dirección URL del servicio RER está registrada para los eventos que controla. Existen dos formas de registrar un controlador:
Los eventos en la web de host se registran mediante programación con el modelo de objetos del lado cliente (CSOM) o la API REST de SharePoint. Esta tarea suele realizarse con la lógica de "primera ejecución" en el complemento o en un controlador de un evento de complemento. (Para obtener información general sobre los eventos de complemento, vea Controlar eventos de complemento más adelante en este artículo). Como ejemplo de código que registra un evento de lista mediante programación, vea SharePoint/PnP/Samples/Core.EventReceivers.
Los eventos de la web de complemento suelen registrarse en una característica de la web de complemento con marcado XML simple. Puede encontrar detalles de cómo crear el marcado y el servicio en Crear un receptor de eventos remotos en complementos para SharePoint. También es posible registrar eventos de web de complemento mediante programación.
Nota:
Los RER tienen la misma finalidad que los receptores de eventos en las soluciones de granja, pero los receptores de eventos tienen código personalizado que se ejecuta en los servidores de SharePoint, por lo que no pueden usarse en complementos de SharePoint.
El complemento puede controlar los siguientes eventos de biblioteca de documentos y de lista. Los eventos que finalizan en "ing" son eventos previos (sincrónicos) y los que terminan en "ed" son eventos posteriores (asincrónicos).
| Previos (sincrónicos) | Posteriores (asincrónicos) |
|---|---|
| ListAdding | ListAdded |
| ListDeleting | ListDeleted |
| FieldAdding | FieldAdded |
| FieldDeleting | FieldDeleted |
| FieldUpdating | FieldUpdated |
Los eventos de actualización de campos están relacionados con el cambio de propiedades de un campo (columna) en una lista (p. ej., si se puede ordenar), no con el cambio de datos en un campo.
El complemento puede controlar los siguientes eventos de elemento de lista.
| Previos (sincrónicos) | Posteriores (asincrónicos) |
|---|---|
| ItemAdding | ItemAdded |
| ItemUpdating | ItemUpdated |
| ItemDeleting | ItemDeleted |
| ItemCheckingOut | ItemCheckedOut |
| ItemCheckingIn | ItemCheckedIn |
| ItemUncheckingOut | ItemUncheckedOut |
| ItemAttachmentAdding | ItemAttachmentAdded |
| ItemAttachmentDeleting | ItemAttachmentDeleted |
| ItemFileMoving | ItemFileMoved |
| ItemVersionDeleting* | ItemVersionDeleted* |
| ItemFileConverted |
Nota:
*Es posible que estos dos eventos nuevos no estén disponibles en la interfaz de usuario de Visual Studio. Si no están, seleccione ItemDeleting o ItemDeleted y modifique manualmente los nombres.
Cuando trabaja en Visual Studio y agrega un RER a un proyecto de Complemento de SharePoint, Office Developer Tools para Visual Studio hace lo siguiente:
Un archivo de servicio web, como RemoteEventReceiver1.svc, se agrega a la aplicación web para controlar los eventos que especificó cuando agregó el receptor de eventos remotos a la Complemento de SharePoint. El servicio web contiene un archivo de código para controlar los eventos remotos.
Después de crear el receptor de eventos remotos, puede agregar código al archivo de código para que el servicio de aplicaciones web controle los eventos. De manera predeterminada, el archivo de código contiene dos métodos a los que puede agregar el código de control:
ProcessEvent()controla eventos "antes" (como los de las columnas de la izquierda que aparecieron previamente en este artículo) y devuelve un objeto a SharePoint que informa si se debe cancelar el evento o dejar que continúe.ProcessOneWayEvent()controla eventos "después". Se ejecuta de forma asincrónica y no devuelve nada a SharePoint.
Cuando se produce un evento registrado, SharePoint llama al método adecuado en el servicio y pasa un objeto que proporciona información contextual del código. Por ejemplo, se identifica el tipo de evento (procedente de una de las dos tablas anteriores de este artículo), para que el código pueda bifurcarse a la lógica que sea adecuada para el evento.
Un elemento del proyecto para el receptor de eventos remotos se agrega al proyecto de la Complemento de SharePoint. El archivo Elements.xml para el receptor de eventos remotos hace referencia al servicio web en la aplicación web y a los eventos remotos que haya especificado. En el siguiente ejemplo se muestra un archivo Elements.xml que controla el agregado o la eliminación de un elemento de una lista.
<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <Receivers ListTemplateId="104"> <Receiver> <Name>RemoteEventReceiver1ItemAdding</Name> <Type>ItemAdding</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> <Receiver> <Name>RemoteEventReceiver1ItemDeleting</Name> <Type>ItemDeleting</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> </Receivers> </Elements>
Para cambiar los eventos que controla el receptor de eventos remotos, abra el Explorador de soluciones, abra la ventana Propiedades para el receptor de eventos remotos, expanda el nodo Eventos de SharePoint y luego especifique solo los eventos que desea controlar para True.
Nota:
Para obtener más información sobre los RER, incluida información para solucionar problemas, vea Preguntas más frecuentes sobre los receptores de eventos remotos.
Controlar eventos de complemento
Los eventos de complemento también se controlan mediante servicios web remotos, pero se configuran de forma distinta en el paquete de complemento de los RER de lista y de elementos de lista, por lo que se tratan como otra categoría de componente. En un evento de complemento, el servicio web remoto se registra en el manifiesto del complemento, no en una característica de web de complemento. El complemento ni siquiera ha de tener una web de complemento. Hay tres eventos de complemento, tal y como se describe en las siguientes secciones.
Evento AppInstalled
El evento AppInstalled se ejecuta inmediatamente después de que SharePoint haya terminado todo lo que tiene que hacer cuando se instala el complemento, pero antes de notificar al usuario que la instalación se ha completado. Aunque se trata de un evento posterior, SharePoint ejecuta el controlador de forma sincrónica. El complemento no está disponible para su uso hasta que el controlador se ha completado y el controlador puede cancelar la instalación (lo que hace que SharePoint revierta todo lo que ha hecho como parte de la instalación). De hecho, se trata de un procedimiento recomendado para detectar errores en el controlador e indicar a SharePoint que revierta la instalación. Para obtener más información, vea Incluir la lógica de reversión y la lógica de "acciones realizadas" en los controladores de eventos de complemento.
Nota:
Al instalar un complemento con ámbito Tenant, se instala en la colección de sitios del catálogo de complementos y, solo entonces, se ejecuta el evento AppInstalled. El complemento está visible en varios sitios web del espacio empresarial, pero el evento no se ejecuta por separado para cada uno de ellos.
Además de cancelar la instalación de un complemento, este evento se puede usar con muchos otros fines, como, por ejemplo:
Instalar componentes de SharePoint en la web de host que no se pueden instalar de forma declarativa con la característica de web de host, como listas o subwebs.
Registrar mediante programación los controladores de eventos de lista y de elemento de lista con la web de host o la web de complemento.
Establecer la configuración de inicialización relativa a la instancia de la aplicación. Por ejemplo, el complemento puede tener un contenedor de propiedades de web de complemento para almacenar valores que varían de una instancia del complemento a otra. El controlador AppInstalled puede escribir valores variables en el contenedor de propiedades, en función, por ejemplo, del tipo de sitio de web de host (como un sitio de grupo o un sitio de blog).
Nota:
Comprobar si la web de host es un sitio de AppCatalog es una buena forma de detectar si se ha instalado el complemento con ámbito de inquilino. Vea Arrendamientos y ámbitos de implementación de los complementos para SharePoint.
Realizar una configuración relativa a la instancia de la aplicación en la aplicación web remota del complemento, como agregar una tabla a una base de datos.
Importante
La implementación del evento AppInstalled debe completarse en menos de 30 segundos o la infraestructura de instalación de SharePoint considerará que no se ha realizado. La infraestructura vuelve a ejecutar el evento y repite el código desde el principio, hasta tres veces más. Tras agotarse cuatro veces el tiempo de espera, SharePoint revertirá toda la instalación del complemento. Todas las implicaciones de estos hechos se tratan en Incluir la lógica de reversión y la lógica de "acciones realizadas" en los controladores de eventos de complemento.
Evento AppUninstalling
El evento AppUninstalling no se ejecuta cuando el complemento se quita de la web host. La eliminación un complemento solo mueve el complemento a la Papelera de reciclaje del usuario. Se requieren dos pasos más para que el evento AppUninstalling se desencadene. Primero: un usuario debe quitar el complemento de la Papelera de reciclaje, lo que lo mueve a la Papelera de reciclaje de segundo nivel. En segundo lugar, un usuario debe quitar el complemento de la papelera de reciclaje de la segunda fase. Esta última tarea desencadena el evento AppUninstalling. El evento AppUninstalling es sincrónico y puede usarse para cancelar la desinstalación, lo que dejaría el complemento en la Papelera de reciclaje de segundo nivel.
La finalidad principal de un controlador para este evento es eliminar o reciclar elementos que se implementaron con un controlador AppInstalled (o AppUpdated). SharePoint no puede eliminar estos elementos ni moverlos a la Papelera de reciclaje, ya que no sabe nada de ellos, al menos no como componentes del complemento. Normalmente se recomienda quitar estos elementos. Pero no es conveniente eliminar elementos que todavía tengan utilidad cuando el complemento haya desaparecido: si una lista o un sitio web que este controlador haya creado va a seguir usándose, no lo elimine del controlador AppUninstalling.
Evento AppUpgraded
El evento AppUpgraded se ejecuta inmediatamente después de que SharePoint haya terminado todo lo que tiene que hacer cuando se actualiza el complemento, pero antes de notificar al usuario que la actualización se ha completado. Como el evento AppInstalled, se trata de un evento posterior, pero es básicamente sincrónico y es un procedimiento recomendado para detectar errores y notificar a SharePoint que revierta la actualización.
Estos son algunos ejemplos de lo que un controlador para este evento puede hacer:
Agregar, modificar o quitar componentes de complemento de la web de host.
Realizar acciones en la web de complemento que no son posibles con la semántica de actualización declarativa en una característica de web de complemento. Por ejemplo, no puede eliminar nada con el marcado declarativo de actualización, pero puede hacerlo mediante programación en un controlador AppUpgraded.
Realizar cambios en componentes relativos a la instancia de la aplicación en la base de datos remota o la aplicación web del complemento.
Para obtener instrucciones detalladas sobre cómo crear controladores de eventos de complemento, vea Crear un receptor de eventos de complemento en complementos de SharePoint.
Incluir la lógica de reversión y la lógica de "acciones realizadas" en los controladores de eventos de complemento
Si SharePoint encuentra un error al procesar cualquiera de los tres eventos de complemento, cancela el evento y revierte los cambios realizados en relación con el evento. Los controladores de eventos de complemento tienen que integrarse con este sistema porque, si se produce un error en la parte del evento que se va a implementar, se quiere revertir la totalidad del evento, en lugar de continuar y dejar elementos en un estado posiblemente dañado. Esto es lo que el controlador normalmente tiene que hacer:
Indicar a SharePoint que se ha producido un error. El mensaje SOAP que el evento de complemento que controla el servicio web devuelve a SharePoint incluye una propiedad Status que puede tener los valores de Continue, CancelWithError o CancelWithoutError. Cualquier estado Cancelar indica a SharePoint que revierta el evento.
Revertir lo que el controlador haya realizado antes de encontrar el error. SharePoint normalmente no puede realizar esto automáticamente porque desconoce lo que ha realizado el controlador. Esto no es una regla universal. Por ejemplo, si se cancela la instalación de un complemento, SharePoint eliminará toda la web de complemento, por lo que no tiene sentido que un controlador de eventos AppInstalled revierta nada que haya hecho en la web de complemento. Pero normalmente tiene que revertir acciones que realizó en la web de host o en componentes remotos del complemento.
Nota:
Los puntos anteriores se aplican tanto al evento AppUninstalling como a los otros dos eventos de complemento. Por ejemplo, si el controlador del evento de desinstalación elimina una fila de una base de datos remota y luego encuentra un error, hay que restaurar la fila. Dado que el servicio envía un mensaje de cancelación a SharePoint, el complemento no se quita de la Papelera de reciclaje. Si se restaura desde allí y se vuelve a usar, es posible que no funcione sin esa entrada de la base de datos. Pero el controlador AppUninstalling finaliza antes de que SharePoint quite el complemento de la Papelera de reciclaje. Por lo tanto, si SharePoint se encuentra un error y tiene que cancelar la eliminación, no hay forma de que el controlador deshaga lo que ha hecho.
Si SharePoint no recibe un mensaje de resultados desde el controlador en 30 segundos, llama de nuevo al controlador. Renuncia por completo y revierte el evento después de tres reintentos (cuatro reintentos en total). Cada vez que llama al controlador, el código vuelve a empezar desde el principio. Normalmente no es conveniente que el controlador rehaga acciones que ya haya hecho, como crear una lista en la web de host. Además, antes de que se agote el tiempo de espera del controlador, no puede saberse si la lógica de reversión se completó o incluso si se desencadenó. Por este motivo, la lógica del controlador no debería realizar ninguna acción sin comprobar primero si ya se ha realizado, a menos que repetirla no suponga ningún riesgo.
Los errores de instalación y actualización se pueden ver en la interfaz de usuario de SharePoint, tal y como se muestra en la ilustración siguiente.
Obtención de detalles de errores de instalación.
Estrategias de arquitectura del controlador de eventos de complemento
Expresado en seudocódigo, el controlador normalmente debe tener una estructura similar a la siguiente. Si se produce un error en la sección Try, se debe invocar la sección Catch y Rollback. (Esto puede ocurrir automáticamente según el idioma y el marco de trabajo).
Try
If X not already done,
Do X.
Catch
Send cancel message to SharePoint.
If X not already undone,
Undo X.
Pero la implementación de la lógica de reversión y de "acciones realizadas" en el servicio web puede ralentizar el controlador. La lógica de instalación y reversión suele realizar cambios en algo más o menos remoto desde el servicio web, como una base de datos back-end o la web de host de SharePoint. Si el código de instalación y reversión se divide entre las secciones Try y Catch, el servicio realiza llamadas independientes a los componentes remotos, a menudo varias llamadas en cada sección.
El procedimiento recomendado suele ser implementar la instalación y la lógica de reversión en el componente remoto mismo mediante un procedimiento que se puede llamar desde el controlador de la sección Try. El procedimiento debe devolver un mensaje de correcto o error, y si informa de un error, el código de la sección Try invoca a la sección Catch (por ejemplo, iniciando una excepción). Lo único que hace la sección Catch es notificar a SharePoint. A esto lo denominamos estrategia de delegación de controladores. El siguiente seudocódigo ilustra la estrategia:
Try
Call the "Do X" procedure on remote platform.
If remote platform reports failure, call Catch.
Catch
Send cancel message to SharePoint.
El procedimiento "Do X", que se ejecuta en el sistema remoto, contendría en sí mismo la lógica de reversión y la lógica de "acciones realizadas" de la siguiente manera.
Try
If X not already done,
Do X.
Set success flag to true.
Catch
If X was done before error,
Undo X.
Set success flag to false.
Send
Return success flag to the event handler.
Por ejemplo, si el controlador debe realizar acciones en una base de datos de SQL Server, se puede instalar un procedimiento almacenado en SQL Server que use un bloque TRY-CATCH para implementar la lógica de reversión de la instalación con bloques IF-ELSE para implementar la lógica de "acciones realizadas".
El modelo de Complemento de SharePoint no ofrece ninguna forma de almacenar un código del lado servidor personalizado en SharePoint e invocarlo desde el modelo de objetos del lado cliente (CSOM). Pero el CSOM ofrece una forma de agrupar la lógica try-catch y la lógica if-then-else, y enviarlas al servidor para su ejecución.
Para obtener un ejemplo detallado de un controlador de eventos de complemento que usa la estrategia de delegación de controladores para agregar una lista a una web de host, vea Crear un receptor de eventos de complemento en complementos de SharePoint. Como ejemplo de código, vea SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation.
No siempre puede usarse la estrategia de delegación de controladores. Por ejemplo, cuando el controlador llama a más de un componente, como una base de datos y la web de host de SharePoint, existe la posibilidad de que uno se complete correctamente y el otro no. En este escenario, la lógica de reversión del primer componente no se ejecuta si se ha diseñado con la estrategia de delegación de controladores. Por este motivo, si se llama a los componentes de forma sincrónica, solo el último componente que se llame puede usar la estrategia de delegación de controladores. Si se llaman de forma asincrónica, no se puede usar esa estrategia en ninguno de ellos.
Para obtener un ejemplo de un controlador de eventos de complemento que no usa la estrategia de delegación de controladores, vea SharePoint/PnP/Samples/Core.AppEvents.
Sugerencia
Si el evento de AppInstalled no se produce, SharePoint eliminará la web de complemento si hay alguna; y si el evento AppUpated no se produce, SharePoint restaurará la web de complemento a su estado anterior a la actualización. Por este motivo, los controladores no tienen que revertir nunca las acciones que realicen en la web de complemento. Si el controlador realiza acciones en la web de host y en la web de complemento, tiene que ocuparse primero de la web de complemento. Si lo hace, no hay riesgo en usar la estrategia de delegación de controladores para la web de host. Aunque las acciones de web de complemento se realicen correctamente y las acciones de web de host no, ninguna lógica de ejecución deja de ejecutarse.
Receptores de eventos remotos en complementos que admiten varias zonas de seguridad
Algunas restricciones sobre cómo diseñar un complemento que admita varias zonas de seguridad y tenga un receptor de eventos remotos.
Preguntas más frecuentes sobre los receptores de eventos remotos
Estas son algunas de las preguntas comunes que puede hacerse al usar receptores de eventos remotos.
¿En qué se diferencian los receptores de eventos remotos de los receptores de eventos en SharePoint 2010?
En SharePoint 2010, los receptores de eventos controlan eventos que se producen en las listas, los sitios y otros objetos de SharePoint al ejecutar el código en el servidor de SharePoint (con plena confianza o en un espacio aislado). Este tipo de receptor de eventos aún existe en SharePoint. Pero SharePoint también admite receptores de eventos remotos en los que el código que se ejecuta al desencadenar el evento se hospeda en un servicio web. Esto implica que si registra un receptor de eventos remoto, también tiene que indicar a SharePoint el servicio web que ha de invocar.
En los siguientes ejemplos de código, el primer ejemplo (Soluciones de SharePoint) implementa funcionalidad mediante un controlador de eventos. El segundo ejemplo (Complementos de SharePoint) implementa la misma funcionalidad mediante un receptor de eventos remotos.
Soluciones de SharePoint
// Trigger an event when an item is added to the SharePoint list.
Public class OnPlantUpdated : SPItemEventReceiver
{
Public override void ItemAdding (SPItemEventProperties properties)
{
Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties));
Properties.status =SPEventReceiverStatus.Continue;
}
/// When an item updates, run the following.
Public override void ItemUpdating(SPItemEventProperties properties)
{
Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties));
Properties.Status= SPEventReceiverStatus.Continue;
}
Complementos de SharePoint
/* Trigger an event when an item is added to the SharePoint list*/
Public class OnPlantUpdated : IRemoteEventService
{
public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties)
{
SPRemoteEventResult result =new SPRemoteEventResult();
If (properties.EventType == SPRemoteEventType.ItemAdding ||
properties.EventType == SPRemoteEventType.ItemUpdating)
{
// Add code that runs when an item is added or updated.
}
Para obtener el ejemplo de código completo, vea Agregar propiedades de elemento de lista con un receptor de eventos remotos.
Para obtener una demostración detallada del ejemplo de código, vea Migrar un receptor de eventos de SharePoint a un receptor de eventos remotos.
Para obtener más información, vea Enumeración SPRemoteEventType.
¿Cómo funcionan los receptores de eventos remotos?
En la siguiente ilustración se muestra cómo funcionan los receptores de eventos remotos:
El usuario realiza una acción en SharePoint (por ejemplo, edita un elemento de lista).
Después, SharePoint se comunica con el servicio web registrado. Se pueden realizar algunas operaciones (por ejemplo, actualizar una propiedad de elemento de lista o actualizar un sistema back-end).
El servicio web también puede conversar con el Servicio de control de acceso (ACS) para solicitar su propio token firmado para realizar una devolución de llamada a SharePoint. Con este token, puede realizar acciones remotas desde dentro del servicio web gracias a la operación anterior en el elemento de lista del sistema back-end.
Cómo funcionan los receptores de eventos de emote en SharePoint
¿Cómo se depuran los receptores de eventos remotos?
Vea Depurar y solucionar problemas de un receptor de eventos remotos en un complemento de SharePoint.
¿Se puede ejecutar código (JavaScript) del lado cliente en receptores de eventos remotos?
No, no se puede ejecutar código (JavaScript) del lado cliente en receptores de eventos remotos.
¿Hay restricciones sobre dónde se puede hospedar un receptor de eventos remotos o sobre su dirección URL?
El destinatario del evento remoto puede estar hospedado en la nube o en un servidor local que no se use también como servidor de SharePoint. La dirección URL de un receptor de producción no puede especificar un puerto en concreto. Esto significa que se debe usar el puerto 443 para HTTPS (recomendado) o el puerto 80 para HTTP. Si usa HTTPS y el servicio del receptor se hospeda en el entorno local, pero el complemento está en SharePoint Online, el servidor host debe tener un certificado de confianza pública de una entidad de certificación. (Un certificado autofirmado solo funciona si el complemento está en una granja de SharePoint local).
¿Funcionará un controlador de eventos de SharePoint 2010 en SharePoint después de la actualización?
Si un paquete de solución de SharePoint 2010 que contiene un controlador de eventos se actualiza a SharePoint, dependerá de sus personalizaciones que el paquete de solución funcione sin que se modifique. Esto también incluye el controlador de eventos. Si la solución de SharePoint 2010 se remodela como complemento de SharePoint en SharePoint, el controlador de eventos debería reescribirse como receptor de eventos remotos. Vea Migrar un receptor de eventos de SharePoint a un receptor de eventos remotos