Construisez votre premier package déverrouillé

• Vous familiariser avec les commandes CLI pour l’empaquetage.
• Décrire les cas d’utilisation de base d’empaquetage.
• Empaqueter l’exemple d’application Dreamhouse LWC et l’installer dans un Trailhead Playground

Remarque

Vous souhaitez apprendre en français ? Dans ce badge, les validations de défi pratique Trailhead se font en anglais. Les traductions sont fournies entre parenthèses à titre de référence. Dans votre Trailhead Playground, veillez (1) à définir les États-Unis comme région, (2) à sélectionner l’anglais comme langue, et (3) à copier et coller uniquement les valeurs en anglais. Suivez les instructions ici.

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

Nous pensons que l’empaquetage est l’une des fonctionnalités les plus intéressantes pour les développeurs de la plate-forme Salesforce. Il rivalise avec certaines innovations révolutionnaires bien connues, comme le pain de mie, le téléphone mobile et les services de streaming vidéo. Mais au cas où vous n’êtes pas encore convaincu, résumons les avantages clés que nous avons appris jusqu'à présent. Développement de package :

• Suit les meilleures pratiques concernant le cycle de vie du développement logiciel. Il est compatible avec les fonctionnalités de Salesforce DX : les projets, les commandes CLI et les organisations test ont été conçus spécialement pour l’empaquetage.
• Regroupe toutes les modifications que vous suivez entre les étapes du cycle de vie dans un artefact par version.
• Facilite le traitement des nouvelles demandes de fonctionnalités. Ajoutez, mettez à jour et supprimez en tout simplicité des composants dans votre package.
• Fournit un historique d'audit amélioré, ce qui vous permet de suivre et de comprendre plus facilement les modifications apportées à votre organisation de production.
• Organise la source. Il est beaucoup plus facile de savoir quels composants appartiennent à quelles applications et fonctionnalités.
• Favorise le développement itératif et modulaire.
• Prend en charge les interdépendances entre les packages déverrouillés. Un seul package déverrouillé peut dépendre de plusieurs packages déverrouillés et de packages gérés de première ou de deuxième génération.
• Prend en charge l'intégration continue et la livraison continue car les commandes de la CLI d'empaquetage permettent d'automatiser complètement chaque étape du pipeline de déploiement.

Cas d’utilisation d’empaquetage simple

Les packages déverrouillés sont parfaitement adaptés aux applications métier internes. Imaginons :

• Votre groupe d’entreprise Finance souhaite que votre équipe informatique crée une application permettant aux employés de présenter leurs notes de frais. L’équipe décide de la développer et de la livrer à l'aide des packages déverrouillés.
• Votre équipe RH souhaite que votre équipe informatique crée une application permettant aux employés de référer des recrues potentielles. Les employés utiliseront l’application de recommandation pour publier des offres d’emploi, référer leurs amis et obtenir des bonus de recommandation. L’équipe décide de la développer et de la livrer à l'aide des packages déverrouillés.

Pour chacun de ces cas, vous commencez un tout nouveau projet, et toutes vos sources sont contenues dans un projet Salesforce DX au format source (et consacrées à votre système de contrôle de version). Lorsque vous êtes prêt à livrer l'une de ces applications, vous créez un package déverrouillé que vous pouvez tester sur une organisation test ou une sandbox, et ensuite l'installer dans votre organisation de production. Et lorsque l’équipe a besoin d’une nouvelle fonctionnalité; vous pouvez l’ajouter et créer une nouvelle version de package. Facile. Un jeu d’enfant.

Configuration de votre environnement

Avant de plonger dans le vif du sujet, configurons un nouveau Trailhead Playground et activons-y le Dev Hub et les packages. 

Remarque : Si vous suivez les étapes de cette section, vous devrez créer un autre Trailhead Playground lorsque vous commencerez le défi pratique.

1. Pour créer un Trailhead Playground, repérez le défi pratique à la fin de cette unité. Cliquez sur les informations du Playground à gauche du bouton Lancer.
   Ensuite, sélectionnez Créer un Playground.
   
   Remarque : Bien qu’il soit possible de réutiliser un Trailhead Playground existant, un nouveau Playground garantit que vous travaillez dans un environnement propre.
2. Après avoir créé un Trailhead Playground, cliquez sur Launch (Lancer) pour l’ouvrir. Ensuite, veillez à connaître le nom d’utilisateur et le mot de passe du Playground. Vous aurez besoin de ces informations dans une prochaine étape.
   Voir Obtenir votre nom d’utilisateur et réinitialiser votre mot de passe.
3. Dans votre Trailhead Playground, dans Configuration, saisissez Dev Hub dans la zone Recherche rapide et sélectionnez Dev Hub. Cliquez sur Activer Dev Hub puis sur Activer les packages déverrouillés et les packages gérés de deuxième génération.
4. Créez un compte GitHub, si vous n’en avez pas déjà un.
5. Installez Salesforce CLI sur votre ordinateur.

Code source DreamHouse sur Git

À des fins de démonstration, supposons que vous construisez et fournissez l’application Dreamhouse LWC à l’une de vos équipes commerciales.

Si vous utilisez actuellement les fonctionnalités et les outils de Salesforce DX, vous connaissez peut-être déjà l’exemple de référentiel Dreamhouse LWC. Dreamhouse LWC est une application autonome qui intègre de nombreuses fonctionnalités disponibles dans la plate-forme Salesforce. Elle utilise des composants Web Lightning, Apex, etc. Elle permet aux utilisateurs de rechercher des propriétés et de contacter des courtiers immobiliers en ligne.

Pour pouvoir vous concentrer sur l’empaquetage, déroulez le code source de Dreamhouse LWC et les fichiers de projet Salesforce DX qui ont déjà été créés. Bien que cet exemple utilise un package, un projet Salesforce DX peut avoir plusieurs packages. Vous pouvez isoler différents packages en fonction de la structure du répertoire, tout en partageant des composants dans des cas appropriés.

En créant un package pour cette application, vous pouvez facilement l’installer dans des organisations test, des sandbox UAT et des organisations de production tout en itérant le cycle de vie du développement.

Nous vous guiderons tout au long du processus à l’aide des outils spécialement conçus pour le développement de packages.

Vous devez obtenir le code source de l’application DreamHouse Lightning Web Components (LWC).

Dans une fenêtre de commande, accédez au répertoire dans lequel vous souhaitez placer le code source, puis exécutez cette commande.

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

La commande git clone crée le dossier dreamhouse-lwc à l’aide de la structure de projet Salesforce DX et contient un fichier de projet DX et un fichier de définition d’organisation test. Ne vous inquiétez pas si votre version du projet semble un peu différente car le référentiel Dreamhouse LWC est continuellement mis à jour.

1. Votre Trailhead Playground est également votre organisation Dev Hub. Pour créer un package, nous devons d’abord accorder l’autorisation d’accès à votre organisation Dev Hub et nous y connecter.

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

2. Dans la fenêtre de commande, vérifions à nouveau que l’organisation Dev Hub est connectée.
   sf org list
   La sortie de cette commande répertorie toutes les organisations auxquelles vous êtes connecté, y compris Dev Hub, les Trailhead Playgrounds et les organisations test. Le (D) indique votre organisation Dev Hub par défaut. 

   === 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. Passez au répertoire dreamhouse-lwc de votre ordinateur.
4. Ouvrez sfdx-project.json dans l’éditeur de texte de votre choix et notez le numéro sourceApiVersion.
5. Dreamhouse LWC est un projet open source auquel beaucoup de personnes contribuent. Pour vous assurer que vous pouvez réussir le défi, remplacez le contenu de votre fichier sfdx-project.json par le code suivant.

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

6. Assurez-vous que le numéro sourceApiVersion dans l’extrait de code correspond au numéro de version que vous avez noté dans le fichier d’origine. Si ce n’est pas le cas, mettez à jour le numéro sourceApiVersion.

Pourquoi n’utilisons-nous pas un espace de nom dans cet exemple ?

Bien qu'un espace de nom de package soit facultatif pour les packages déverrouillés, en inclure un vous permet de garder les composants du package organisés. Toutefois, étant donné que les espaces de noms nécessitent une configuration et une prévoyance supplémentaires, nous allons les ignorer dans cette unité.

Si vous déplacez des métadonnées de votre soupe heureuse vers un package déverrouillé, créez vos packages déverrouillés sans espace de noms. Ainsi, lorsque les métadonnées sont déplacées d’un état non empaqueté à un package déverrouillé, le nom de l’API des éléments de métadonnées ne change pas.

Création du package

Lorsque vous avez cloné l’application DreamHouse à partir de GitHub, vous avez extrait tous les fichiers source dans votre répertoire de projet. Vous pouvez maintenant créer le package de base sans tambour ni trompette.

Cette section fournit le flux de travail pour la création d’un package à l’aide du référentiel d’exemples Dreamhouse LWC.

1. À partir d’un terminal ou d’une invite de commande, accédez au répertoire dreamhouse-lwc.
2. Créez un package déverrouillé sans espace de nom et indiquez l'alias ou le nom d'utilisateur de votre organisation Dev Hub s'il n'est pas déjà défini par défaut :

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

   • --name est le nom du package. Ce nom est un alias que vous pourrez utiliser par la suite pour exécuter des commandes d’empaquetage.
   • --path est le dossier dans lequel se trouve le contenu du package.
   • --packagetype indique le type de package que vous créez. Ici, il s’agit d’un package déverrouillé.
3. Ouvrez sfdx-project.json. Terminé ! Dans packageDirectories, vous voyez le nom du package que vous avez défini, dans lequel figurent des espaces réservés pour le nom et le numéro de la version. La commande crée également une section packageAliases qui mappe le nom du package (alias) à son ID de package correspondant (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 vous oubliez l’alias ou l’ID du package, vous pouvez lister tous les packages associés avec votre Dev Hub en exécutant la commande sf package list.

Création d'une organisation test pour tester votre version du package

Créons une organisation test dans laquelle installer le package déverrouillé, avec l'alias MyScratchOrg. Créer une organisation de test est une manière pratique d’effectuer la phase de test unitaire du cycle de développement de package.

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

Cette commande utilise le fichier de définition par défaut de l’organisation test et crée une organisation test Developer Edition, la même édition que celle de Trailhead Playground. Notez que la durée est fixée à 30 jours, ce qui vous laisse suffisamment de temps pour terminer votre travail dans un sprint de développement (ou compléter ce module Trailhead).

Création de la version de package et installation dans votre organisation test

Lorsque vous êtes prêt à publier le package, vous créez un instantané de celui-ci, appelé une version de package. L'installation de la version du package est similaire au déploiement de métadonnées. Souvenez-vous, une fois créée, une version du package sert d'artefact immuable contenant un ensemble spécifique de métadonnées.

1. Ouvrez sfdx-project.json avec votre éditeur de texte favori pour mettre à jour les options de version du package.
2. Modifiez le paramètre versionName en Version 1.0, et le paramètre versionNumber en 1.0.0.NEXT. Le répertoire force-app est le (seul) répertoire de packages par défaut, donc toute source incluse dans celui-ci devient partie intégrante du package. Une fois mis à jour, le fichier sfdx-project.json ressemble à ceci :

   {
      "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. Enregistrez le fichier sfdx-project.json.
4. Dans le répertoire dreamhouse-lwc, créez la version du package, ce qui associe les métadonnées.
   Le code Apex dans les packages déverrouillés doit satisfaire au moins 75 % des exigences de couverture de code avant que le package puisse être installé dans une organisation de production. Nous n’avons pas calculé la couverture de code dans cet exemple car nous savons que ce dépôt Dreamhouse LWC n’a pas une couverture de test Apex suffisante.
   

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

   • -p est l’alias du package, mappé à l’ID de celui-ci.
   • -d est le dossier dans lequel se trouve le contenu du package.
   • -k est la clé d’installation qui empêche que des personnes non autorisées n’installent votre package.
5. Il est normal que le processus de création de la version de package prenne plusieurs minutes. Des messages d’état vous indiquent ce qui se passe. Lorsque la création de la version du package est terminée, ce message s’affiche.

   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. Vous remarquerez la présence d’une nouvelle entrée dans la section packageAliases dans sfdx-project.json.

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

7. Utilisez l’alias de la version du package pour installer la version de package dans l'organisation test que vous avez créée précédemment.

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

   Cela peut prendre plusieurs minutes pour qu'une version de package nouvellement créée soit disponible dans l'organisation test. L'installation commence une fois que la version du package est disponible. Lorsque l’installation du package est terminée, ce message s’affiche. Successfully installed package [04t3XXX]
8. Une fois le package installé, ouvrez l'organisation test pour afficher le package.

   sf org open --target-org MyScratchOrg

9. Dans Configuration, saisissez Packages installés dans la zone Recherche rapide et sélectionnez Packages installés. Comme il s’agit d’un package déverrouillé, vous pouvez effectuer des modifications directement dans l’organisation test et transférer les métadonnées mises à jour, puis créer une nouvelle version du package. Mais pour l’instant, l’application DreamHouse LWC a déjà tout ce dont vous avez besoin, nous pouvons donc poursuivre et publier le package.

Publication de la version de package

Une fonctionnalité dont nous n'avons pas encore parlé est l'état du package. Les packages ont un statut bêta lorsque vous les créez initialement. Vous ne pouvez pas installer de packages bêta dans une organisation de production. C'est une garantie pour vous assurer que la version du package que vous publiez est prête pour la production. Lorsque vous savez qu’une version est prête pour la publication, vous pouvez définir la version de package comme publiée.

L’exemple de référentiel Dreamhouse LWC que nous utilisons dans cette unité évolue et n’a pas nécessairement toujours suffisamment de tests Apex pour satisfaire les 75 % d’exigence de couverture de code. Nous allons donc ignorer la promotion et continuer à utiliser le package bêta que vous avez créé.

Voici à quoi ressemble la commande de promotion de la version du package, mais si vous essayez d’exécuter cette commande maintenant, vous obtiendrez un message d’erreur.

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

Installation de la version de package dans une organisation