Crear su primer paquete desbloqueado

• Familiarizarse con comandos de CLI para el empaquetado.
• Describir los casos de uso de empaquetado básicos.
• Empaquetar la aplicación DreamHouse LWC de muestra e instalarla en un Trailhead Playground.

Nota

¿Es su idioma de aprendizaje español (LATAM)? En esta insignia, las validaciones de los retos prácticos de Trailhead funcionan en inglés. Entre paréntesis se incluyen las traducciones a modo de referencia. En su instancia de Trailhead Playground, asegúrese de (1) cambiar la configuración local a los Estados Unidos, (2) cambiar el idioma a inglés, y (3) copiar y pegar solo los valores en inglés. Siga las instrucciones que figuran aquí.

Consulte la insignia Trailhead en su idioma para obtener más información sobre cómo aprovechar la experiencia de Trailhead en otros idiomas.

Creemos que el empaquetado es una de las funciones más excitantes para desarrolladores de la plataforma Salesforce. Está a la par con algunas rompedoras innovaciones conocidas, como el pan rebanado, el teléfono celular y los servicios de transmisión de video. Pero solo en caso de que necesite convencerse más, sumemos las ventajas clave que conocimos hasta ahora. Desarrollo de paquetes:

• Sigue las mejores prácticas acerca del ciclo de vida del desarrollo de software. Es compatible con las funciones de Salesforce DX: los proyectos, los comandos de CLI y las organizaciones borrador se crearon específicamente pensando en el empaquetado.
• Encapsula todos los cambios que está siguiendo entre cambios de ciclo de vida en un artefacto versionado.
• Le facilita la tarea de acomodar nuevas solicitudes de función. Simplemente agregue, actualice y elimine componentes en su paquete.
• Proporciona un historial de auditoria mejorado, por lo que puede seguir de forma más sencilla y comprender los cambios realizados en su organización de producción.
• Organiza fuentes. Es mucho más fácil saber qué componentes pertenecen a qué aplicaciones y funciones.
• Promociona el desarrollo iterativo y modular.
• Admite interdependencias entre paquetes desbloqueados. Un solo paquete desbloqueado puede depender de múltiples paquetes desbloqueados y paquetes gestionados de primera y segunda generación.
• Admite la integración y entrega continuas porque los comandos de empaquetado de CLI permiten que se automatice cada paso en la canalización de implementación.

Casos de uso de empaquetado sencillo

Los paquetes desbloqueados está magníficamente adaptados para aplicaciones de negocio internas. Supongamos que:

• Su grupo de negocio Finanzas desea que su equipo de TI cree una aplicación que los empleados pueden utilizar para enviar gastos. Su equipo decide desarrollarla y entregarla utilizando paquetes desbloqueados.
• Su equipo de RR.HH. desea que su equipo de TI cree una aplicación que los empleados pueden utilizar para hacer referencia a posibles contrataciones. Los empleados utilizarán la aplicación Referencia para publicar publicaciones de trabajo, hacer referencia a sus colegas y obtener incentivos de referencia. Su equipo decide desarrollarla y entregarla utilizando paquetes desbloqueados.

Para cada uno de estos casos, inicia un proyecto completamente nuevo, y toda su fuente está incluida en el formato fuente de proyecto de Salesforce DX (y comprometida con su sistema de control de versión). Cuando esté listo para entregar una de estas aplicaciones, crea un paquete desbloqueado que puede probar en una organización borrador o sandbox, y luego instala en su organización de producción. Cuando el equipo necesite una nueva función, puede agregarla y crear una nueva versión de paquete. Fácil. Chupado.

Configurar su entorno

Antes de ponerse con lo bueno, configuremos un nuevo Trailhead Playground y activemos Dev Hub y el empaquetado en él. 

Nota: Si sigue los pasos de esta sección, deberá crear otro nuevo Trailhead Playground al iniciar el reto práctico.

1. Para crear un nuevo Trailhead Playground, localice el reto práctico al final de esta unidad. Haga clic en la información de playground a la izquierda del botón Iniciar.
   Luego, seleccione, Crear Playground.
   
   Nota: Aunque es posible reutilizar un Trailhead Playground existente, empezar con un playground completamente nuevo garantiza que está trabajando con un entorno limpio.
2. Después de crear un nuevo Trailhead Playground, haga clic en Launch (Iniciar) para abrir el playground. Luego asegúrese de que sabe el nombre de usuario y la contraseña para el playground. Necesitará esta información en un próximo paso.
   Consulte Obtención de su nombre de usuario y restablecimiento de su contraseña.
3. En Configuración en su Trailhead Playground, ingrese Dev Hub en el cuadro Búsqueda rápida y, a continuación, seleccione Dev Hub. Haga clic en Activar Dev Hub y luego haga clic en Activar paquetes desbloqueados y paquetes gestionados de segunda generación.
4. Cree una cuenta de GitHub, si aún no tiene una.
5. Instale Salesforce CLI en su equipo.

“Git” el código fuente de DreamHouse

Para fines de demostración, imaginemos que está creando y entregando la aplicación DreamHouse LWC a uno de sus equipos de negocio.

Si está utilizando en estos momentos las herramientas y funciones de Salesforce DX, es posible que esté familiarizado con el repositorio de muestra de DreamHouse LWC. DreamHouse LWC es una aplicación independiente que incorpora varias funciones disponibles en Salesforce Platform. Utiliza componentes web Lightning, Apex y mucho más. Permite a los usuarios examinar propiedades y hacer contacto con agentes inmobiliarios online.

Por lo que puede centrarse en el empaquetado, desglosará el código fuente de DreamHouse LWC y los archivos de proyecto de Salesforce DX que ya se crearon. Aunque este ejemplo utiliza un solo paquete, un proyecto de Salesforce DX puede tener múltiples paquetes. Puede aislar diferentes paquetes basándose en la estructura del directorio, pero compartir componentes donde tenga sentido.

Mediante la creación de un paquete para esta aplicación, puede instalarlo fácilmente en organizaciones borrador, entornos sandbox de pruebas de aceptación de usuario (UAT) y organizaciones de producción cuando itere por el ciclo de vida de desarrollo.

Le guiaremos por todo el proceso utilizando herramientas diseñadas para el desarrollo de paquetes.

Obtengamos el código fuente para la aplicación Componentes web Lightning de DreamHouse (LWC).

En una ventana de comando, cambie al directorio donde desea poner el código fuente, luego ejecute este comando.

git clone https://github.com/dreamhouseapp/dreamhouse-lwc.git

El comando git clone crea la carpeta dreamhouse-lwc empleando la estructura de proyectos de Salesforce DX, y contiene un archivo de proyecto DX y un archivo de definición de organización borrador. Como el repositorio de DreamHouse LWC está continuamente actualizado, no se alarme si su versión del proyecto tiene un aspecto algo diferente.

1. Su Trailhead Playground es también su organización de Dev Hub. Para crear un paquete, primero tenemos que autorizar su organización de Dev Hub, e iniciar sesión en ella.

   sf org login web --set-default-dev-hub --alias DevHub

2. En la ventana de comandos, volvamos a comprobar que la organización Dev Hub está conectada.
   sf org list
   El resultado de este comando indica cualquier organización a la que está conectado, incluyendo Dev Hub, Trailhead Playgrounds y organizaciones borrador. La (D) indica su organización Dev Hub predeterminada. 

   === Orgs
        ALIAS       USERNAME                             ORG ID              CONNECTED STATUS
   ───  ──────────  ───────────────────────────────      ──────────────────  ────────────────
   (D)  DevHub      myDevHub@example.com                 00DB0000000Ige5MAC  Connected
        MyTP        myName@mindful-raccoon-8184t4.com    00D6A000000fH8CUAU  Connected
        TestingOrg  name@example.com                     00D4x000006sFonEAE  Connected
   ALIAS            USERNAME                             ORG ID              EXPIRATION  DATE
   ────────         ───────────────────                  ──────────────────  ────────────────
   Scratch1         test@example.com                     00DZ000000N8ItoMAF  2021-02-24

3. Cambie al directorio dreamhouse-lwc en su equipo.
4. Abra el archivo sfdx-project.json en su editor de texto favorito y tome nota del número de sourceApiVersion.
5. DreamHouse LWC es un proyecto de código abierto con muchos colaboradores. Para garantizar que pueda completar correctamente el reto, sustituya el contenido del archivo sfdx-project.json por el siguiente código.

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "58.0"
   }

6. Asegúrese de que el número de sourceApiVersion en el fragmento de código coincida con el número de versión del archivo original que ya tiene anotado. Si no coincide, entonces actualice el número de sourceApiVersion.

¿Por qué no estamos utilizando un espacio de nombres en este ejemplo?

Aunque el espacio de nombres de un paquete es opcional para paquetes desbloqueados, incluyendo uno que le ayuda a mantener los componentes del paquete organizados. Sin embargo, como los espacios de nombres requieren configuración adicional y previsión, los omitiremos en esta unidad.

Si está migrando metadatos desde su sopa feliz a un paquete desbloqueado, cree sus paquetes desbloqueados sin un espacio de nombres. De esa manera, cuando los metadatos se trasladan desde un estado desempaquetado a un paquete desbloqueado, el nombre de API de los elementos de los metadatos no cambia.

Crear el paquete

Cuando duplicó la aplicación DreamHouse LWC desde GitHub, extrajo todos los archivos de origen en su directorio de proyecto. Ahora puede crear el paquete base sin más dilaciones.

Esta sección proporciona el flujo de trabajo para la creación de un paquete utilizando el repositorio de muestra de DreamHouse LWC.

1. Desde una solicitud de terminal o comandos, cambie al directorio dreamhouse-lwc.
2. Cree un paquete desbloqueado sin un espacio de nombres y proporcione el alias o el nombre de usuario para su organización Dev Hub si no está ya establecido como el valor predeterminado:

   sf package create --name dreamhouse --description "My Package" --package-type Unlocked --path force-app --no-namespace --target-dev-hub DevHub

   • --name es el nombre del paquete. Este nombre es un alias que puede utilizar cuando ejecute comandos de empaquetado posteriores.
   • --path es el directorio que contiene el contenido del paquete.
   • --packagetype indica qué tipo de paquete está creando, en este caso, desbloqueado.
3. Abra sfdx-project.json. ¡Bieeen! En packageDirectories, puede ver el nombre del paquete que definió, con marcadores de posición del nombre y el número de la versión. El comando también crea una sección packageAliases, que asigna el nombre del paquete (alias) con su Id. de paquete correspondiente (0Ho).

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true,
            "package": "dreamhouse",
            "versionName": "ver 0.1",
            "versionNumber": "0.1.0.NEXT"
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "58.0",
      "packageAliases": {
         "dreamhouse": "0Hoxxx"
      }
   }

Si olvida el alias del paquete o el Id. del paquete, puede enumerar todos los paquetes asociados con su Dev Hub ejecutando sf package list.

Crear una organización borrador para probar su versión de paquete

Creamos una organización borrador, en la que instalar el paquete desbloqueado, con el alias MyScratchOrg. La prueba en una organización borrador es una manera útil de realizar la fase de pruebas de unidades del ciclo de vida del desarrollo de empaquetado.

sf org create scratch --definition-file config/project-scratch-def.json --duration-days 30 --alias MyScratchOrg --target-dev-hub DevHub

Este comando utiliza la definición de organización borrador predeterminada, que crea una organización borrador de Developer Edition, la misma edición que su Trailhead Playground. Observe que la duración está establecida como 30 días, dándole tiempo suficiente para finalizar su trabajo en una carrera de desarrollo (o completar este módulo de Trailhead).

Crear la versión de paquete e instalarla en su organización borrador

Cuando está listo para publicar el paquete, crea una instantánea de él, denominada una versión de paquete. La instalación de la versión de paquete es similar a la implementación de metadatos. Recuerde, una vez creada, una versión de paquete sirve como un artefacto inalterable que contiene un conjunto específico de metadatos.

1. Abra el sfdx-project.json con su editor de texto favorito para actualizar las opciones de versión de paquete.
2. Cambie el versionName a Version 1.0 y el versionNumber a 1.0.0.NEXT. El directorio force-app es el directorio de paquetes predeterminado /y único), por lo que cualquier fuente incluida se convierte en parte del paquete. Una vez actualizado, el archivo sfdx-project.json tiene el siguiente aspecto:

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true,
            "package": "dreamhouse",
            "versionName": "Version 1.0",
            "versionNumber": "1.0.0.NEXT"
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "58.0",
      "packageAliases": {
         "dreamhouse": "0Hoxxx"
      }
   }

3. Guarde el archivo sfdx-project.json.
4. En el directorio dreamhouse-lwc, cree la versión de paquete, que asocia los metadatos con el paquete.
   El código de Apex en los paquetes desbloqueados debe cumplir un mínimo del 75% de requisitos de cobertura de código, antes de que pueda instalarse el paquete en una organización de producción. No calculamos la cobertura de código en este ejemplo porque sabemos que el repositorio de Dreamhouse LWC no tiene suficiente cobertura de pruebas de Apex.
   

   sf package version create --package dreamhouse --installation-key test1234 --wait 10 --target-dev-hub DevHub

   • -p es el alias de paquete que se asigna al Id. del paquete.
   • -d es el directorio que contiene el contenido del paquete.
   • -k es la clave de instalación que protege su paquete de ser instalado por personas no autorizadas.
5. Es normal que el proceso de creación de la versión de paquete tarde varios minutos. Verá mensajes de estados que le indican lo que está pasando. Cuando la creación de la versión de paquete esté completa, verá este mensaje.

   Successfully created the package version [08cxxx]. Subscriber Package Version Id: 04txxx.
   Package Installation URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04txxx
   As an alternative, you can use the "sf package install" command.

6. Observe que la sección packageAliases de sfdx-project.json tiene una nueva entrada.

   "packageAliases": {
      "dreamhouse": "0Hoxxx",
      "dreamhouse@1.0.0-1": "04txxx"
   }

7. Utilice el alias de versión del paquete para instalar la versión de paquete en la organización borrador que creó anteriormente.

   sf package install --wait 10 --publish-wait 10 --package dreamhouse@1.0.0-1 --installation-key test1234 --no-prompt --target-org MyScratchOrg 

   Una versión de paquete recién creada podría tardar varios minutos en estar disponible en la organización borrador. La instalación comienza una vez disponible la versión de paquete. Cuando la instalación del paquete esté completa, verá este mensaje. Successfully installed package [04t3XXX] (Se instaló correctamente el paquete [04t3XXX])
8. Una vez instalado el paquete, abra la organización borrador para ver el paquete.

   sf org open --target-org MyScratchOrg

9. En Configuración, ingrese Paquetes instalados en el cuadro Búsqueda rápida y, a continuación, seleccione Paquetes instalados. Como se trata de un paquete desbloqueado, puede realizar cambios directamente en la organización borrador y desplegar los metadatos actualizados, luego crear una nueva versión de paquete. Pero por ahora, la aplicación DreamHouse LWC ya tiene todo lo que necesita, por lo que podemos continuar y publicar el paquete.

Publicar la versión de paquete

Una función que no hemos tratado aún es estado de paquete. Los paquetes tienen un estado beta cuando los crea inicialmente. No puede instalar paquetes beta en una organización de producción. ésta es una medida de protección para asegurarse de que la versión de paquete que publica está lista para producción. Cuando sabe que una versión está lista para el mundo, puede promover la versión del paquete a publicada.

El repositorio de ejemplo de Dreamhouse LWC que estamos utilizando en esta unidad va cambiando y no siempre tiene suficientes pruebas de Apex para cumplir el requisito de cobertura de código del 75 %. Por lo tanto, omitiremos la promoción y seguiremos utilizando la versión beta del paquete que creó.

Este es el aspecto del comando de promoción de versión de paquete, pero si intenta este comando ahora mismo, recibirá un mensaje de error.

sf package version promote --package dreamhouse@1.0.0-1 --target-dev-hub DevHub

Instalar la versión de paquete en una organización