Construisez votre premier package déverrouillé

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

• 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 ? Commencez le défi dans un Trailhead Playground en français et utilisez les traductions fournies entre crochets pour naviguer. Copiez et collez uniquement les valeurs en anglais, car les validations de défi reposent sur les données en anglais. Si vous ne réussissez pas le défi dans votre organisation en français, nous vous recommandons (1) de définir le paramètre régional sur les États-Unis, (2) de définir la langue sur l’anglais en suivant les instructions ici, puis (3) de cliquer à nouveau sur le bouton « Vérifier le défi ».

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

Pourquoi nous adorons le développement de packages

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 les sources. 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.

Maintenant que vous êtes mis au fait des avantages du développement de packages, nous allons vous montrer comment créer un package déverrouillé.

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 relatives au Playground à gauche du bouton Launch (Lancer).
   
   
2. Sélectionnez ensuite Create Playground (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.
   
3. 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 lors d’une étape ultérieure.
   Consultez l’article Obtention de votre nom d’utilisateur et réinitialisation de votre mot de passe.
   
4. 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.
   
5. Créez un compte GitHub, si vous n’en avez pas déjà un.
   
6. 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/trailheadapps/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.

Configuration de votre package

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. 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 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. 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. 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 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. 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 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. 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. Enregistrez le fichier 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 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. 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. 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 dérouler les métadonnées mises à jour, puis créer une nouvelle version de 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

Enfin, installez la version de package dans votre organisation. Souvenez-vous que vous pouvez installer des versions de package bêta dans des organisations test, des sandbox et des Trailhead playgrounds (organisations DE). Vous pouvez installer une version de package publiée dans n'importe quelle organisation. En règle générale, à ce stade, vous installez la version du package dans une sandbox, mais pour cet exercice, nous allons installer le package dans votre 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. Dans votre Trailhead Playground, dans Configuration, saisissez Packages installés dans la zone Recherche rapide, puis sélectionnez Packages installés. Vous recevrez également un e-mail confirmant que vous avez correctement installé le package déverrouillé.
   
5. Cliquez sur dreamhouse, puis sur Afficher les composants.
   
6. Depuis le lanceur d’application, ouvrez l’application DreamHouse et explorez certaines de ses fonctionnalités.
   

Ressources

• Guide de configuration Salesforce CLI
• Référentiel DreamHouse LWC
• Salesforce DX Trailblazer Community