Rompimos ganchos de despliegue/recuperación ☁️

Esta es una traducción que desde EGA Futura ofrecemos como cortesía a toda la Ohana y comunidad de programadores , consultores , administradores y arquitectos de Salesforce para toda Iberoamérica .

El enlace a la publicación original, lo encontrarás al final de este artículo.

…

La CLI de Salesforce ha realizado, y seguirá realizando, algunos cambios importantes en el funcionamiento de los ganchos de implementación y recuperación . Si crea o usa complementos personalizados que utilizan ganchos predeploy , postdeploy , preretrieve , postretrieve o postsourceupdate , hay cambios tanto en la carga útil como en el comportamiento de esos ganchos que podrían afectarlo.

En esta publicación de blog, explicaremos por qué estamos haciendo estos cambios. También analizaremos los detalles de los cambios y brindaremos ejemplos de lo que se romperá y lo que no, junto con posibles soluciones alternativas y algunas declaraciones prospectivas.

Fondo de ganchos y caso de uso de ejemplo

Echemos un vistazo a cómo solían funcionar los ganchos. Antes de nuestros cambios recientes, los ganchos de implementación y recuperación proporcionaban una forma de interceptar metadatos (código, configuración, etc.) que iban desde su máquina local a una organización de Salesforce (o viceversa) y realizaban cambios en la operación de implementación/recuperación.

Por ejemplo, un gancho del mundo real que encontramos reemplazó los marcadores de posición en la fuente local con secretos. Para comprender cómo funcionó, consideremos el caso de uso de una fuente de datos externa de Salesforce Connect. Supongamos que desea implementar y ejecutar pruebas con una fuente de datos externa, pero no desea almacenar un campo de password en el control de fuente.

Su gancho podría reemplazar $xdsPassword

 < password>$xdsPassword</password>

con un valor del medio ambiente

 < password>myPwdFromTheEnv</password>

antes del despliegue.

Luego, la máquina de un desarrollador o un sistema de CI que tiene la variable de entorno puede implementar los metadatos de ExternalDataSource sin siquiera escribir la contraseña en los archivos de origen.

Cómo solían funcionar los ganchos durante una implementación

Hasta la versión 7.111 de CLI, un comando force:source:deploy funcionaba así:

En una implementación, la CLI convertiría todo el código con formato fuente al formato API de metadatos (leería cada archivo y lo escribiría en un directorio temporal).
Los mdapiFilePath predeploy apuntaría a cada archivo temporal junto con los metadatos sobre ese archivo.
El código de ganchos recibiría esa matriz de archivos y realizaría cualquier lógica
En nuestro ejemplo, el complemento personalizado buscaría tipos de ExternalDataSource y luego abriría ese archivo y modificaría el valor de la password con el valor del entorno.
El enlace saldría y la CLI continuaría comprimiendo los metadatos (ahora modificados) y enviándolos a la API de metadatos.

Como desarrollador de complementos, puede garantizar la ejecución constante de su código de enlace en cada implementación realizada desde la CLI o las extensiones de VSCode, ya que llamaban a la CLI.

force:source: retrieve y force:source:pull funcionaron casi igual, pero a la inversa. Ellos recuperarían el archivo zip, lo descomprimirían en un directorio temporal, activarían ganchos posteriores a la recuperación para permitirle modificar el resultado, y luego convertirlo y escribirlo en sus carpetas de origen.

Conozca la nueva biblioteca de implementación/recuperación de fuentes

Escuchamos de nuestros usuarios que querían implementaciones más rápidas y que las implementaciones grandes eran particularmente lentas. Además, los usuarios de la extensión VSCode que cambiaron un archivo querían implementarlo en su organización de Salesforce lo más rápido posible. Para abordar estas preocupaciones y aumentar la velocidad de implementación y recuperación, creamos la biblioteca Source Deploy/Retrieve (SDR).

El SDR acelera la implementación/recuperación al:

Reducción de las operaciones del sistema de archivos. En lugar de escribir cada archivo convertido en el directorio temporal, escribir esa carpeta en un archivo zip y cargar el zip, el SDR transmite archivos desde el código fuente a un archivo zip en memoria que va directamente a la API de metadatos. La única operación del sistema de archivos es leer los archivos que se implementarán. Las operaciones del sistema de archivos son lentas, especialmente en máquinas con Windows, y evitarlas significa implementaciones más rápidas. Los proyectos grandes pueden tener 10 000 archivos de metadatos en una implementación (¡y potencialmente muchos más una vez que todos esos elementos secundarios descompuestos de CustomObject se conviertan en archivos individuales!)

Dado que no todos usaban una versión reciente de CLI que incluye SDR, observamos las métricas de octubre y observamos una reducción del 36 % en el tiempo medio de implementación y una reducción del 57 % en el tiempo de recuperación (y una enorme reducción del 75 % en implementaciones en el percentil 90… las que estaban tardando bastante).

Permitiendo el uso directo por VSCode. Salesforce VSCode Extensions originalmente usaba la CLI para implementar y recuperar metadatos. Dado que la CLI se cargó como un proceso secundario, su uso agregó mucho tiempo de sobrecarga a los comandos de implementación/recuperación en VS Code. Llamar a la CLI directamente también significaba que estábamos analizando automáticamente los indicadores de entrada, haciendo validaciones, cargando mensajes de ayuda, etc., la mayoría de los cuales no son necesarios cada vez que "implementa al guardar", por ejemplo. Las extensiones de Salesforce ahora hacen llamadas directamente al SDR y ahorran mucho tiempo al no generar procesos secundarios ni realizar tareas innecesarias relacionadas con la CLI.

Además de estas ganancias de rendimiento, SDR es una biblioteca de código abierto que puede ser utilizada por cualquier otra persona que escriba herramientas de metadatos; no es trivial mantener la lógica de conversión para los cientos de tipos de metadatos y las docenas de tipos nuevos que aparecen en cada uno. Lanzamiento de la fuerza de ventas. Si su complemento personalizado trata con metadatos o la API de metadatos, esta es una gran mejora para usted.

Para lograr estas ganancias, estamos adoptando el SDR. Sin embargo, eso rompe algunos casos de uso para ganchos.

¿Qué está usando SDR?

A partir de la versión 7.135.0, la CLI actualmente usa SDR para:

source:deploy, source:retrieve , source:convert y source:delete (y sus variantes de report )
source:beta:pull, source:beta:push y source:beta:status que ofrecen ganancias de rendimiento similares a las que se muestran arriba
mdapi:beta deploy retrieve y deploy:report

En Salesforce VS Code Extensions, usamos SDR en las siguientes áreas:

Comandos del menú contextual y de la paleta de comandos: Deploy/Retrieve Source from Manifest , Deploy/Retrieve Source from Org
Navegador de la organización
Detección de conflictos
Funcionalidad de prueba de Apex

Cómo el SDR rompe anzuelos

En primer lugar, se eliminó postsourceupdate para los comandos de recuperación en 7.112.0, por lo que los ganchos que dependen de él no se ejecutarán. La conversión de fuente ocurre en la secuencia tan pronto como se descarga y descomprime el zip recuperado, por lo que postretrieve ahora ocurre en la misma etapa que la postsourceupdate (es decir, después de que se escriben los archivos de formato de fuente local).

En segundo lugar, no hay una ruta de directorio temporal para modificar el código. Si sus ganchos esperaban usar la ubicación temporal de la fuente con formato de metadatos, ya no existe.

En tercer lugar, las extensiones de VSCode ahora llaman directamente al SDR (en lugar de a la CLI) para implementar/recuperar. Los ganchos no se activarán en absoluto para las operaciones de implementación/recuperación iniciadas desde VSCode a menos que esté utilizando la CLI en la terminal de VSCode.

Ejemplos y soluciones

En nuestro ejemplo anterior (reemplazando un marcador de posición con secretos del entorno), el complemento puede ver lo que se va a implementar desde el predeploy a la implementación. Pero sin el directorio temporal, no puede realizar ningún cambio en el código fuente antes de implementarlo. En este caso, el desarrollador podría hacer una de las siguientes cosas:

Escriba un comando de deploy o push personalizado que incluya el paso de secretos. Es significativamente más fácil ahora que nuestros comandos son de código abierto y el SDR está disponible.
Escriba un script de shell que haga de manera efectiva lo que hizo el proceso original de ganchos:
1. Convierta los archivos de origen en una carpeta de metadatos temporal ( force:source:convert )
2. Revisa esa carpeta y modifica lo que quieras.
3. Implemente esa carpeta de metadatos temporales ( force:mdapi:deploy )
4. Eliminar la carpeta de metadatos temporales
Use un postdeploy a la implementación para recrear el proceso original como una pequeña segunda implementación:
1. Vea si se implementaron archivos de ExternalDataSource y si contienen el marcador de posición
2. Convierta esos archivos en una carpeta de metadatos temporal
3. Cambiar el marcador de posición/secreto
4. Implemente esa carpeta de metadatos temporales
5. Eliminar esa carpeta de metadatos temporales

Otro enlace que vimos elimina la propiedad UserPermissions de Profile y PermissionSet durante una recuperación. Si su complemento anteriormente usaba un gancho posterior a la recuperación, ya notó que force:source:retrieve tiene una carga útil de gancho diferente. Todavía contiene la ruta a los archivos recuperados, que su complemento podría usar para buscar cualquier Profile o conjunto de PermissionSet y reescribir esos archivos sin UserPermissions. En este caso, el desarrollador podría:

Vuelva a escribir el código de gancho para manejar las cargas útiles de gancho nuevas y antiguas
Una vez que todos los comandos estén usando SDR, elimine el controlador para el formato de gancho anterior a SDR

Otro complemento que encontramos usa ganchos para cambios destructivos en una implementación, una función que agregamos recientemente al comando stock source:deploy . No hay necesidad de continuar usando el complemento para cambios destructivos.

Una más: un desarrollador notó un error en el seguimiento de fuentes de Salesforce. Después de cambiar el nombre de un campo, CustomField aparecería en los cambios, pero no lo haría un informe que usara el campo (aunque su código fuente cambió para reflejar el cambio del campo). El complemento usó un preretrieve a la recuperación para examinar los archivos de código fuente locales e insertar cualquier informe que haga referencia al campo en el paquete.xml, de modo que el informe se incluya en la recuperación. En este caso, el desarrollador podría:

Ver los archivos recuperados (a través de un gancho postretrieve a la recuperación)
Haga que su gancho inicie otra recuperación ( force:source:retrieve -m Report:SomeReport ) para obtener el informe que falta en la fuente local

Aviso: `push` y `pull` se romperá a continuación

Reescribimos push and pull para usar el SDR, y esos cambios están actualmente en versión beta a partir de 7.25.0. Eventualmente cambiaremos la nueva versión para que sea la predeterminada, lo que hará que los ganchos cambien como se discutió anteriormente.

Advertencia: no se garantiza que VSCode use la CLI

Como parte del cambio a SDR, las extensiones de Salesforce cambiaron a una "estrategia de biblioteca" y ya no llaman a la CLI directamente a través de nuestro menú contextual y los comandos de la paleta de comandos. A partir de la última versión de Extensiones de Salesforce (53.1.0), la CLI solo se usa en segundo plano para algunas funciones básicas de configuración y autenticación del depurador. Cualquier complemento de ganchos (incluso en el nuevo estilo) no activará los mismos ganchos en VS Code en el futuro.

Soluciones transitorias

El push and pull existente se moverá bajo el subtema force:source:legacy , por lo que puede continuar usándolos tal como funcionan actualmente incluso después de que las nuevas versiones se conviertan en las predeterminadas.

Puede utilizar versiones anteriores de la CLI (le garantizamos que habrá al menos 40 versiones anteriores disponibles). Las versiones anteriores a la 7.112 no incluían el SDR para implementar/recuperar y usar las versiones anteriores de ganchos.

Del mismo modo, puede usar versiones anteriores de Salesforce Extensions: se pueden instalar alrededor de 200 versiones anteriores directamente desde VS Code. El SDR se introdujo en VS Code en la versión 48.5.0 , pero la capacidad de volver a la implementación de CLI y usar ganchos estaba disponible a través de la versión 53.1.0 . Para volver a la implementación de CLI desde una versión anterior, busque Experimental: Deploy Retrieve en la configuración de VS Code .

Nota: Realmente nos referimos a estos como soluciones transitorias. Además de perderse las ganancias de rendimiento de SDR, también se está abriendo a todos los errores y actualizaciones de seguridad que se han corregido en las versiones más recientes de la CLI y las extensiones de Salesforce para VS Code.

Conclusión

Romper los cambios siempre es difícil. Esperamos que esta publicación lo haya ayudado a comprender por qué hicimos estos cambios recientes, qué podría verse afectado y qué puede hacer para abordarlos. Para mantenerse al día con las actualizaciones de la CLI, como el próximo cambio en los comandos push y pull, siga las notas de la versión de SFDX o ejecute sfdx whatsnew . Si está creando complementos personalizados, explore los comandos source y mdapi de SDR y Salesforce que lo implementan.

Sobre el Autor

Shane McLaughlin es desarrollador en el equipo de CLI de Salesforce y ha estado construyendo en la plataforma de Salesforce desde 2011. Es @mshanemc tanto en Twitter como en GitHub.