Crear su primer paquete desbloqueado

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

• 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)? Comience el reto en un Trailhead Playground en español (LATAM) y utilice las traducciones entre paréntesis para navegar. Copie y pegue solo los valores en inglés, ya que las validaciones del reto dependen de los datos en ese idioma. Si no aprueba el reto en su organización en español (LATAM), recomendamos que (1) cambie la configuración local a Estados Unidos, (2) cambie el idioma a inglés (según estas instrucciones) y, luego, (3) haga clic en el botón “Check Challenge” (Comprobar el reto) nuevamente.

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

Por qué nos encanta el desarrollo de paquetes

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.

Ahora que tiene una idea de las ventajas de la implementación de paquetes, le mostraremos cómo crear un paquete desbloqueado.

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 la zona de pruebas a la izquierda del botón Launch (Iniciar).
   
   
2. Luego, seleccione Create Playground (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.
   
3. 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 Obtener su nombre de usuario y restablecer su contraseña.
   
4. 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.
   
5. Cree una cuenta de GitHub, si aún no tiene una.
   
6. 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/trailheadapps/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.

Configurar su paquete

1. Your Trailhead Playground is also your Dev Hub org. To create a package, we need to first authorize to your Dev Hub org, and log in to it.
   

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

2. In the command window, let’s double check that the Dev Hub org is connected.
   sf org listThe output of this command lists any org that you’re connected to, including Dev Hub, Trailhead Playgrounds, and scratch orgs. The (D) indicates your default Dev Hub org. 
   

   === 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 is an open-source project with many contributors. To ensure that you can successfully complete the challenge, replace the contents of the sfdx-project.json file with the following code.
   

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "61.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. Create an unlocked package without a namespace, and supply the alias or username for your Dev Hub org if it’s not already set as the default:
   

   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. Open sfdx-project.json. Boom! In packageDirectories, you can see the package name that you defined, with placeholders for the version name and version number. The command also creates a packageAliases section, which maps the package name (alias) to its corresponding package ID (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": "61.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. Change the versionName to Version 1.0, and the versionNumber to 1.0.0.NEXT. The force-app directory is the default (and only) package directory, so any source included in it becomes part of the package. Once updated, the sfdx-project.json file looks like this:
   

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

3. Guarde el archivo sfdx-project.json.
   
4. In the dreamhouse-lwc directory, create the package version, which associates the metadata with the package.
   The Apex code in unlocked packages must meet a minimum 75% code coverage requirement, before the package can be installed in a production org. We didn’t calculate code coverage in this example, because we know this sample Dreamhouse LWC repo doesn’t have enough Apex test coverage.
   

   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. It’s normal for the package version creation process to take several minutes. You see status messages that tell you what’s going on. When the package version creation is complete, you see this message.
   

   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. Notice that the packageAliases section in sfdx-project.json has a new entry.
   

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

7. Use the package version alias to install the package version in the scratch org that you created earlier.
   

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

   It can take several minutes for a newly created package version to be available in the scratch org. The installation begins once the package version is available. When the package install is complete, you see this message. Successfully installed package [04t3XXX]
8. After the package is installed, open the scratch org to view the package.
   

   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

Otra ventaja no menos importante, instale la versión de paquete en su organización. Recuerde, puede instalar las versiones de paquete beta en organizaciones borrador, entornos de sandbox y Trailhead playgrounds (organizaciones DE). Puede instalar una versión de paquete publicada en cualquier organización. Normalmente en esta fase instalará la versión de paquete en un sandbox, pero para este ejercicio vamos a instalar el paquete en su Trailhead Playground.

1. To install the package version in to your Trailhead playground, you must first add it to your list of authorized orgs.
   you must first add it to your list of authorized orgs.
   

   sf org login web --alias MyTP

   We suggest creating an alias for the Trailhead Playground, in this example, MyTP. Once you log in to an org, the CLI remembers your credentials. All you need to do is remember the org’s alias when issuing subsequent commands. If you don’t know the username and password for your Trailhead Playground, see Getting Your Username and Resetting Your Password.
   
2. Install the package version in the Trailhead playground.
   

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

3. Open your Trailhead playground.
   

   sf org open --target-org MyTP

4. En su Trailhead playground, desde Configuración, ingrese Paquetes instalados en el cuadro Búsqueda rápida, luego seleccione Paquetes instalados. Recibirá también un email que confirma que instaló el paquete desbloqueado con éxito.
   
5. Haga clic en dreamhouse, luego Ver componentes.
   
6. Desde Iniciador de aplicación, encuentre y seleccione la aplicación DreamHouse y consulte algunas de sus funciones.
   

Recursos

• Guía de configuración de Salesforce CLI
• Repositorio de DreamHouse LWC
• Salesforce DX Trailblazer Community