Crear un controlador para el evento de actualización de complementos de SharePoint

Artículo
04/08/2023

Antes de empezar, vea Control de eventos de complemento y Actualizar complementos de SharePoint y familiarícese con los requisitos previos y los conceptos básicos indicados.

Nota:

Sistema de numeración de versiones: por coherencia, en este tema se supone que los números de versión del complemento son 1.0.0.0, 2.0.0.0, 3.0.0.0 y así sucesivamente. Sin embargo, la lógica y la orientación se aplican independientemente de cuál sea su sistema de numeración.

Crear un receptor de UpgradedEventEndpoint

Para la lógica de actualización personalizada, puede crear un receptor de eventos remotos de SharePoint que controle el evento actualizado del complemento. Debe ser prudente en relación con el uso de esta técnica. Úsela exclusivamente para los pasos de actualización que no pueden realizarse de ninguna otra forma. Además, las instrucciones que se encuentran en Control de eventos de complemento se aplican para el evento actualizado del complemento tanto como los eventos de complemento instalado y desinstalación del complemento. Esto incluye:

El controlador debe completar y devolver un estado de cancelar o continuar a SharePoint en 30 segundos. Si no lo hace, SharePoint llama al controlador de nuevo, un máximo de tres veces.
Si el controlador devuelve un estado de cancelación, SharePoint lo reintentará hasta tres veces más.
Normalmente, es necesario incluir la lógica de reversión y "de acciones realizadas" en el controlador.

Un escenario en el que resulta útil un controlador UpgradedEventEndpoint es cuando se agrega un campo calculado a una base de datos remota. Suponga que se agrega una columna Ciudad y su valor se calcula a partir de una columna existente Código Postal. El código de un controlador UpgradedEventEndpoint podría repetirse a través de elementos existentes de la base de datos y rellenar el valor del nuevo campo Ciudad en función del valor del campo Código postal y algún origen de datos externo que asigne códigos postales a ciudades. El cambio al propio esquema de la base de datos se realiza mejor fuera del controlador UpgradedEventEndpoint mediante los procedimientos recomendados de la plataforma de base de datos.

Para obtener más información sobre cómo crear un controlador para el evento de complemento, vea Controlar eventos en los complementos de SharePoint y Crear un receptor de eventos del complemento en complementos de SharePoint.

El procedimiento siguiente asume que ha agregado el elemento receptor de eventos del complemento al proyecto de complemento de SharePoint en Visual Studio.

Para controlar el evento de actualización del complemento la primera vez

Abra el archivo AppEventReceiver.svc.cs y agregue una estructura condicional al método ProcessEvent que compruebe si el evento que ha invocado el controlador es el evento actualizado. El código de actualización va dentro de esta estructura. Si el código necesita acceder a SharePoint, puede usar el modelo de objetos de cliente de código administrado de SharePoint (CSOM) o la interfaz de transferencia de estado representacional (REST).

El lugar en el que se ubique la estructura condicional en el método dependerá de cómo haya estructurado el resto de código en el método. Normalmente, es un par de estructuras condicionales similares que prueban los eventos del complemento instalado y los eventos de desinstalación de complementos. Puede estar dentro de una estructura condicional que prueba determinadas propiedades o subpropiedades del objeto SPRemoteEventProperties que se pasa a ProcessEvent en busca de valores null u otros valores no válidos. También puede estar dentro de un bloque try.

A continuación se muestra un ejemplo de la estructura. El objeto properties es un objeto SPRemoteEventProperties .
```
   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
 }
```
Para usar CSOM en el controlador, agregue (dentro del bloque condicional) un bloque using que obtiene un objeto ClientContext mediante llamando al método TokenHelper.CreateAppEventClientContext. Especifique true para el segundo parámetro para poder acceder a la web del complemento. Especifique false para obtener acceso a la web del host. Si necesita obtener acceso a ambos elementos, necesitará dos objetos de contexto de cliente distintos.

Si el controlador necesita tener acceso a componentes que no son de SharePoint, ponga ese código fuera de cualquier bloque de contexto de cliente. El código debería tener una estructura similar a esta:

   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, true))
     {
         // CSOM code that accesses the add-in web
     }
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, false))
     {
         // CSOM code that accesses the host web
     }
     // Other update code
 }

Para usar la interfaz REST, el código usa otros métodos en la clase TokenHelper para obtener un token de acceso que, a continuación, se incluye en las solicitudes que realiza a SharePoint. Para más información, consulte Procedimiento para realizar operaciones básicas con extremos REST de SharePoint. El código debería tener una estructura similar a la siguiente.

   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
     if (contextTokenString != null)
     {
         contextToken = TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                                                                                                                   Request.Url.Authority);
         accessToken = TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                                    .AccessToken;

        // REST code that accesses SharePoint
     }  
     // Other update code
 }

Para obtener acceso a SharePoint, el código de REST también debe conocer la dirección URL de la web del complemento, de la web del host o de ambas. Estas direcciones URL son dos subpropiedades del objeto SPRemoteEventProperties que se pasa al método ProcessEvent. El siguiente código muestra cómo obtenerlas.
```
   Uri hostWebURL = properties.AppEventProperties.HostWebFullUrl;
   Uri appWebURL = properties.AppEventProperties.AppWebFullUrl;
```

Al actualizar un complemento por segunda (o tercera, etc.) vez, es posible que deba asegurarse de que determinada lógica de actualización no se ejecute varias veces en la misma instancia del complemento. El siguiente procedimiento le muestra cómo.

Controlar el evento de complemento actualizado en actualizaciones posteriores

Abra el archivo AppEventReceiver.svc.cs y busque el código que implementó acciones de actualización en la primera actualización (de 1.0.0.0 a 2.0.0.0). Lo llamaremos el código de actualización anterior. (Este código se encuentra generalmente después del código de autorización que obtiene el contexto de cliente o los tokens de acceso). Ahora que está actualizando de nuevo (de 2.0.0.0 a 3.0.0.0), normalmente habrá acciones en el código de actualización anterior aquí que no desea volver a ejecutar en la misma instancia del complemento, pero quiere que se ejecute en una instancia de complemento que nunca se actualizó a 2.0.0.0 (en cuyo caso, la instancia se está actualizando ahora de 1.0.0.0 a 3.0.0.0).
Rodee el código de actualización anterior de una estructura condicional que pruebe la versión anterior de la instancia de complemento y que solo se ejecute si el código de la estructura no se ha ejecutado anteriormente en esta instancia del complemento. La versión anterior de la instancia se almacena en la subpropiedad PreviousVersion del objeto SPRemoteEventProperties.

Agregue su lógica de actualización nueva (para la actualización de la versión 2.0.0.0 a la 3.0.0.0) en esta estructura. Este es un ejemplo.

   Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 (previous update code) is here.
 }
 // Code to update from 2.0.0.0 to 3.0.0.0 is here.

Para cada subsiguiente actualización, repita estos pasos. Para la actualización de la versión 3.0.0.0 a la 4.0.0.0, el código debería tener la siguiente estructura.

 Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 is here.
 }

 Version ver3OOO = new Version("3.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver3OOO)
 {
     // Code to update from 2.0.0.0 to 3.0.0.0 (previous update code) is here.
 }
 // Code to update from 3.0.0.0 to 4.0.0.0 is here.

Importante

Si agrega un componente a un complemento en un controlador UpgradedEventEndpoint, asegúrese de agregar el mismo código a un controlador InstalledEventEndpoint, porque también desea que el componente esté incluido en el complemento en una instalación nueva. Además, debe agregar un UninstallingEventEndpoint (o revisarlo) para que el complemento elimine el componente.

En la mayoría de casos, todo aquello que el controlador InstalledEventEndpoint agregue o cambie se debería revertir o eliminar con el controlador UninstallingEventEndpoint. Una excepción es que los datos que seguirán siendo de utilidad después de quitar el complemento de la papelera de reciclaje de la segunda etapa no se deberían eliminar. (Los sitios web, que no sean las web de complementos, que haya creado el complemento se deben considerar como datos).

Agregar una lógica de reversión al controlador

Si se produce un error cuando se actualiza el complemento, la infraestructura de SharePoint detiene el proceso de actualización y revierte la instancia del complemento y todos sus componentes a la versión anterior de la instancia del complemento. Pero la infraestructura no tiene forma de saber lo que la lógica del controlador UpgradedEventEndpoint hace, por lo que no siempre no puede revertirla. Una excepción no controlada iniciada mientras se ejecuta el controlador UpgradedEventEndpoint seguramente indica que debe revertirse todo el proceso de actualización del complemento, pero esta acción no se llevará a cabo porque la infraestructura no sabe cómo deshacer algunas acciones que el código UpgradedEventEndpoint puede haber llevado a cabo. Por este motivo, el código UpgradedEventEndpoint debe:

Capturar todas las excepciones.
Crear una ramificación al código de reversión personalizado para deshacer todo lo que se haya hecho hasta ese punto.
Señalizar a la infraestructura de SharePoint a la que se debería revertir toda la actualización del complemento.
Pasar un mensaje de error a la infraestructura.

No todo lo que UpgradedEventEndpoint hace se debe revertir explícitamente dentro del controlador. La infraestructura va a revertir la web del complemento, por lo que no es necesario que el código deshaga los cambios en la web del complemento. Pero el controlador UpgradedEventEndpoint normalmente tiene que revertir los cambios que ha realizado en la web del host u otros componentes que sean externos al complemento de SharePoint.

En la segunda (o tercera, etc.) actualización, la lógica de control de excepciones debe tener en cuenta el hecho de que la instancia del complemento que se está actualizando no es necesariamente la versión inmediatamente anterior. Si no lo es, es posible que haya dos o más bloques de código de actualización que se deban revertir. Por este motivo, se necesita lógica condicional basada en el número de la versión anterior. A continuación se muestra un ejemplo de la lógica de reversión de una actualización a la versión 4.0.0.0.

catch (Exception e)
{ 
    // Rollback of the 3.0.0.0 to 4.0.0.0 update logic goes here.

    Version ver3OOO = new Version("3.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver3OOO)
    {
        // Rollback of the 2.0.0.0 to 3.0.0.0 update logic goes here.
    }

    Version ver2OOO = new Version("2.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver2OOO)
    {
        // Rollback of the 1.0.0.0 to 2.0.0.0 update logic goes here.
    }
}

Las últimas acciones que debe llevar a cabo el controlador de errores es asignar un mensaje de error y un estado de cancelación al objeto SPRemoteEventResult que el método ProcessEvent devuelve a la infraestructura de actualización de SharePoint. Este es un ejemplo. En este código, result es un objeto SPRemoteEventResult que se declaró con anterioridad en el método ProcessEvent.

catch (Exception e)
{     
    result.ErrorMessage = "custom message " + e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;

     // Rollback logic from the preceding code snippet  is here. 

}

Importante

La asignación de SPRemoteEventServiceStatus.CancelWithError (o SPRemoteEventServiceStatus.CancelNoError) a la propiedad Status es crucial. Esta propiedad es lo que indica a la infraestructura que revierta la actualización. Sin embargo, SharePoint volverá a probar el controlador tres veces antes de revertir la actualización.

Usar la estrategia de delegación del controlador

La estrategia de delegación del controlador que se describe en Control de eventos de complemento puede usarse también en un UpdatedEventHandler. No solo la reversión y la lógica "ya realizada" están empaquetadas y se ejecutan en el componente remoto, esto también se aplica a la lógica de control de versiones. Las limitaciones de la estrategia también se aplican aquí; normalmente no puede utilizarse para actualizar más de un sistema remoto.

Pasos siguientes

Vuelva a Pasos principales en la actualización de un complemento o visite directamente uno de los siguientes artículos para saber cómo actualizar el siguiente componente principal del complemento de SharePoint.

Compartir vía