Criar seu primeiro pacote desbloqueado

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Conhecer os comandos CLI para o empacotamento.
  • Descrever os casos de uso básicos do empacotamento.
  • Empacotar o exemplo de aplicativo DreamHouse e instalá-lo em um Trailhead Playground.

Por que adoramos o desenvolvimento com pacotes

Para nós, o empacotamento é um dos recursos novos para desenvolvedores da Salesforce Platform mais empolgantes. Fica lado a lado com outras revoluções famosas, como o pão fatiado, o celular e o cinema em casa. No entanto, caso você ainda não esteja convencido, vamos resumir as principais vantagens que descobrimos até hoje. O desenvolvimento com pacotes:

  • Segue as melhores práticas referentes ao ciclo de vida do desenvolvimento de software. É compatível com os novos recursos do Salesforce DX: os projetos, os comandos de desenvolvimento de origem e as organizações temporárias foram criados pensando especificamente no empacotamento.
  • Encapsula todas as alterações controladas entre os estágios do ciclo de vida em um artefato com versões.
  • Torna mais fácil acomodar os futuros pedidos de novos recursos. Adiciona, atualiza e remove componentes de seu pacote de modo simples.
  • Proporciona um histórico de auditoria melhorado, facilitando o controle e a compreensão das alterações feitas em sua organização de produção.
  • Organiza a origem. Fica muito mais fácil saber qual componente pertence a cada aplicativo e recurso.
  • Promove o desenvolvimento iterativo e modular.
  • Aceita interdependências entre pacotes desbloqueados. Um único pacote desbloqueado pode depender de vários outros pacotes desbloqueados e pacotes clássicos.
  • Aceita a integração contínua e o envio contínuo porque os comandos de CLI para empacotamento permitem automatizar totalmente cada etapa no pipeline de implantação.

Agora que você já está a par das vantagens do desenvolvimento com pacotes, vamos mostrar como criar um pacote desbloqueado.

Casos de uso simples do empacotamento

Os pacotes desbloqueados são perfeitos para aplicativos empresariais internos. Por exemplo:

  • O grupo de negócios financeiros quer que a equipe de TI crie um aplicativo para os funcionários enviarem suas despesas. Sua equipe decide desenvolver e enviar esse aplicativo usando os pacotes desbloqueados.
  • A equipe de RH quer que a equipe de TI crie um aplicativo para os funcionários indicarem possíveis candidatos. Os funcionários usarão o aplicativo Recomendação para publicar vagas de emprego, indicar colegas e receber bônus por indicação. Sua equipe decide desenvolver e enviar esse aplicativo usando os pacotes desbloqueados.

Em cada um desses casos, você começa um projeto completamente novo e toda a origem fica contida no formato de projeto do Salesforce DX (e comprometida com seu sistema de controle de versão). Quando estiver pronto para enviar um desses aplicativos, você cria um pacote desbloqueado que pode ser testado em uma organização temporária ou um sandbox e, depois, instalado em sua organização de produção. E quando a equipe precisa de um recurso novo, é possível adicioná-lo e criar uma nova versão do pacote. Simples. Moleza!

Configure o ambiente

Antes de chegarmos à parte boa, vamos conferir se você já tem tudo o que é necessário para se dar bem nesse desafio.

  • Você já configurou o Hub do desenvolvedor (Dev Hub) e instalou a CLI do Salesforce? Siga para esta unidade do módulo Desenvolvimento de aplicativo com o Salesforce DX para saber mais.
  • Já tem uma conta do GitHub?
  • Já ativou o empacotamento em sua organização Dev Hub? Em Configuração, digite Dev Hub na caixa Busca rápida e selecione Dev Hub. Clique em Ativar pacotes desbloqueados e pacotes de segunda geração gerenciados.

Copie o código fonte do DreamHouse

Para fins de demonstração, vamos fingir que você está criando e apresentando o aplicativo DreamHouse para uma das equipes da sua empresa.

Se você usa atualmente os recursos e ferramentas do Salesforce DX, talvez já esteja à vontade com o exemplo de repositório DreamHouse. O DreamHouse é um aplicativo independente que incorpora muitos dos recursos disponíveis na Salesforce Platform. Ele usa componentes do Lightning, Apex, notificações, Einstein, Process Builder e muito mais. Nele, os usuários podem procurar imóveis e falar com corretores on-line.

Para que você possa se concentrar no empacotamento, vamos extrair o código fonte do DreamHouse e os respectivos arquivos de projeto do Salesforce DX, que já foram criados. Embora este exemplo use apenas um pacote, um projeto do Salesforce DX pode conter vários. Você pode isolar pacotes diferentes com base na estrutura de diretório e compartilhar componentes quando for o caso.

Criando um pacote para esse aplicativo, fica fácil instalá-lo em organizações temporárias, UAT, sandboxes e organizações de produção conforme você itera pelo ciclo de vida do desenvolvimento.

Vamos acompanhá-lo durante todo o processo usando as ferramentas especialmente criadas para o desenvolvimento com pacotes.

Vamos copiar o código fonte do aplicativo DreamHouse.

  1. Baixe o código do repositório do GitHub do DreamHouse.
  2. Clique em Clonar ou baixar.
  3. Copie o link HTTPS no repositório.
  4. Em uma janela de comando, mude para o diretório onde você quer colocar o código-fonte. Depois, execute o comando.
    git clone https://github.com/dreamhouseapp/dreamhouse-sfdx.git

Repare que a origem é a estrutura do projeto do Salesforce DX, que contém um arquivo de projeto do DX e uma definição de organização temporária. Não se assuste se a sua versão do projeto for um pouco diferente, pois o repositório DreamHouse é atualizado com frequência.

Mostra a estrutura completa do diretório dreamhouse-sfdx quando ele é aberto em um programa como o Finder ou o Windows Explorer.

Crie um pacote e uma versão do pacote

Se você está seguindo esta trilha há algum tempo, provavelmente já fez login em sua organização Dev Hub.

  1. Na janela de comando, vamos verificar se a organização Dev Hub está conectada.
    sfdx force:org:list
    A saída desse comando apresenta todas as organizações às quais você está conectado, incluindo organizações Dev Hub, Trailhead Playground e temporárias. O (D) indica sua organização Dev Hub padrão. Caso veja um (U), isso significa que todos os comandos da CLI são executados com relação a esse nome de usuário por padrão.
    === Orgs
         ALIAS       USERNAME                         ORG ID              CONNECTED STATUS
    ───  ──────────  ───────────────────────────────  ──────────────────  ────────────────
    (D)  DevHub      myDevHub@example.com             00DB0000000Ige5MAC  Connected
         MyTP        myName@cunning-bear-311000.com   00D6A000000fH8CUAU  Connected
         TestingOrg  name@example.com                 00DB0000000Im58MAC  Connected
    ALIAS     SCRATCH ORG NAME  USERNAME             ORG ID              EXPIRATION  DATE
    ────────  ────────────────  ───────────────────  ──────────────────  ────────────────
    Scratch1  myAcme            test@example.com     00DZ000000N8ItoMAF  2018-03-01
    Caso tenha concluído o módulo Desenvolvimento de aplicativo com o Salesforce DX, você provavelmente verá que está conectado a uma organização do Trailhead Playground. Também é possível ver uma ou mais organizações temporárias criadas por você para realizar o desafio prático. Caso seu Dev Hub não esteja conectado, faça login nele:
    sfdx auth:web:login -d -a DevHub
  2. Alterne para o diretório dreamhouse-sfdx.
  3. Abra sfdx-project.json em seu editor de texto favorito. O DreamHouse é um projeto de código aberto com muitos colaboradores. Para você poder completar o desafio com sucesso, vamos fazer com que seu arquivo de projeto se pareça com este no começo.
    {
       "packageDirectories": [
          {
             "path": "force-app",
             "default": true
          }
       ],
       "namespace": "",
       "sfdcLoginUrl": "https://login.salesforce.com",
       "sourceApiVersion": "44.0"
    }
  4. Se necessário, exclua alguns dos parâmetros existentes, tais como id, versionName e versionNumber. Atualize sourceApiVersion para corresponder à versão da CLI do Salesforce. Não esqueça de salvar!

Por que não usamos namespace neste exemplo?

Embora o namespace seja opcional nos pacotes desbloqueados, incluí-lo ajuda a manter os componentes do pacote organizados. No entanto, como os namespaces exigem mais configuração e antecipação, vamos deixá-los de lado nesta unidade.

Importante

Importante

Caso esteja migrando metadados da sua sopa da felicidade para o pacote desbloqueado, crie os pacotes desbloqueados sem namespace. Assim, quando os metadados saírem do estado sem pacote para entrar no pacote desbloqueado, o nome da API dos elementos de metadados permanecerá o mesmo.

Criar o pacote

Quando você baixou o aplicativo DreamHouse do GitHub, colocou todos os arquivos de dados no diretório do seu projeto. Agora você pode criar o pacote de base sem mais delongas.

Nota

Nota

Esta seção apresenta o fluxo de trabalho para criar um pacote usando o exemplo de repositório DreamHouse. Caso esteja pensando em enfrentar o desafio prático ao final da unidade, tenha calma e siga as instruções usando este fluxo de trabalho como referência, se necessário.

  1. Crie o pacote desbloqueado sem namespace e informe o alias ou nome de usuário de sua organização Dev Hub caso ele não esteja definido como o padrão:
    sfdx force:package:create --name dreamhouse --description "My Package" --packagetype Unlocked --path force-app --nonamespace --targetdevhubusername DevHub
    • --name é o nome do pacote. Esse nome é um alias que você pode usar ao executar comandos para empacotamento subsequentes.
    • --path é o diretório que apresenta o conteúdo do pacote.
    • --packagetype indica que tipo de pacote você está criando; neste caso, desbloqueado.
    O alias do pacote fica agora associado ao ID de pacote (0Ho). Não precisa mais se lembrar de IDs de empacotamento difíceis de entender! No entanto, quem entende de números pode continuar a usar IDs de empacotamento ao executar comandos.
    === Ids
    NAME                  VALUE
    ───────────────────── ──────────────────
    Package Id           0Hoxxx
  2. Abra sfdx-project.json. Bingo! Em packageDirectories, você pode ver o nome do pacote que definiu, com espaços reservados para o nome e o número da versão. O comando também cria uma seção packageAliases, que mapeia o nome do pacote (alias) para seu ID de pacote (0Ho) correspondente.
    {
       "packageDirectories": [
          {
             "path": "force-app",
             "default": true,
             "package": "dreamhouse",
             "versionName": "ver 0.1",
             "versionNumber": "0.1.0.NEXT"
          }
       ],
       "namespace": "",
       "sfdcLoginUrl": "https://login.salesforce.com",
       "sourceApiVersion": "44.0",
       "packageAliases": {
          "dreamhouse": "0Hoxxx"
       }
    }
    Dica Se você não lembrar do alias do pacote ou do ID de pacote, pode listar todos os pacotes que criou no Dev Hub executando sfdx force:package:list.

Criar uma organização temporária para testar sua versão do pacote

Vamos criar uma organização temporária na qual instalaremos o pacote desbloqueado com o alias MyScratchOrg. O teste em uma organização temporária é uma forma prática de realizar a fase de teste da unidade no ciclo de vida do desenvolvimento por empacotamento.

sfdx force:org:create --definitionfile config/project-scratch-def.json --durationdays 30 --setalias MyScratchOrg -v DevHub

Use a definição padrão de organização temporária, que cria uma organização temporária da Developer Edition, a mesma edição de seu Trailhead Playground. Repare que a duração é definida como 30 dias, dando muito tempo para que você termine o trabalho dentro de um sprint de desenvolvimento (ou conclua este módulo do Trailhead).

Criar a versão do pacote e instalá-la na organização temporária

Quando estiver pronto para liberar o pacote, crie um instantâneo dele, chamado de “versão do pacote”. A instalação da versão do pacote se assemelha à implantação de metadados. Lembre-se: depois de criada, a versão do pacote serve como artefato imutável que contém um conjunto específico de metadados.

  1. Abra sfdx-project.json com o editor de texto desejado para atualizar as opções da versão do pacote.
  2. Mude o versionName para Versão 1.0 e o versionNumber para 1.0.0.NEXT. O diretório force-app é o padrão (e o único) para os pacotes, ou seja, qualquer origem nele contida se torna parte do pacote. Depois de atualizado, o arquivo sfdx-project.json fica assim:
    {
       "packageDirectories": [
          {
             "path": "force-app",
             "default": true,
             "package": "dreamhouse",
             "versionName": "Version 1.0",
             "versionNumber": "1.0.0.NEXT"
          }
       ],
       "namespace": "",
       "sfdcLoginUrl": "https://login.salesforce.com",
       "sourceApiVersion": "44.0",
       "packageAliases": {
          "dreamhouse": "0Hoxxx"
       }
    }
  3. Salve o arquivo sfdx-project.json.
  4. No diretório dreamhouse-sfdx, crie a versão do pacote, que associa os metadados ao pacote.
    sfdx force:package:version:create -p dreamhouse -d force-app -k test1234 --wait 10 -v DevHub
    • -p é o alias do pacote que mapeia para o ID de pacote.
    • -d é o diretório que apresenta o conteúdo do pacote.
    • -k é a chave de instalação que impede que seu pacote seja instalado por pessoas não autorizadas.
    É comum que o processo para criar a versão do pacote leve alguns minutos.
    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 "sfdx force:package:install" command.
  5. Observe que a seção packageAliases em sfdx-project.json tem uma nova entrada.
    "packageAliases": {
       "dreamhouse": "0Hoxxx",
       "dreamhouse@1.0.0-1": "04txxx"
    }
  6. Use o alias da versão do pacote para instalar a versão do pacote na organização temporária que você criou.
    sfdx force:package:install --wait 10 --publishwait 10 --package dreamhouse@1.0.0-1 -k test1234 -r -u MyScratchOrg
    Pode demorar vários minutos para que a versão do pacote recém-criada fique disponível na organização temporária. A instalação começará assim que a versão do pacote estiver disponível.
  7. Depois que o pacote estiver instalado, abra a organização temporária para visualizá-lo.
    sfdx force:org:open -u MyScratchOrg
  8. Em Configuração, digite Pacotes instalados na caixa Busca rápida e selecione Pacotes instalados. Mostra o diálogo Pacotes instalados comComo se trata de um pacote desbloqueado, você pode fazer alterações diretamente na organização temporária, extrair os metadados atualizados e, depois, criar a nova versão do pacote. Por enquanto, o aplicativo DreamHouse já tem tudo o que é necessário, ou seja, podemos prosseguir e liberar o pacote.

Liberar a versão do pacote

Ainda não discutimos um recurso, o status do pacote. Quando os pacotes são criados, eles têm o status beta. Não é possível instalar pacotes beta em uma organização de produção. Trata-se de uma proteção para garantir que a versão do pacote lançada esteja pronta para a produção. Quando você souber que a versão está pronta para ganhar o mundo, basta promover o lançamento.

sfdx force:package:version:promote -p dreamhouse@1.0.0-1 -v DevHub

Instalar a versão do pacote na organização

Por último, mas não menos importante, instale a versão do pacote na organização. Lembre-se: é possível instalar versões do pacote em organizações temporárias, sandboxes e Trailhead Playgrounds (organizações DE). Você pode instalar uma versão do pacote liberada em qualquer organização.

  1. Para instalar a versão do pacote no Trailhead Playground, faça login.
    sfdx auth:web:login -a MyTP
    Sugerimos criar um alias para o Trailhead Playground, MyTP neste exemplo. Depois que você faz login na organização, o CLI se lembra das suas credenciais. Você só precisa se lembrar do alias da organização ao enviar os comandos seguintes. Caso não saiba o nome de usuário e a senha do Trailhead Playground, consulte Obter seu nome de usuário e redefinir sua senha.
  2. Instale a versão do pacote no Trailhead Playground.
    sfdx force:package:install --wait 10 --publishwait 10 --package dreamhouse@1.0.0-1 -k test1234 -r -u MyTP
  3. Abra o Trailhead Playground.
    sfdx force:org:open -u MyTP
  4. No Trailhead Playground, em Configuração, digite Pacotes instalados na caixa Busca rápida e selecione Pacotes instalados. Você também receberá um email que confirma a instalação do pacote desbloqueado com sucesso.
  5. Clique em dreamhouse e em Exibir componentes. Clicando em Exibir componentes de dreamhouse, você vê uma lista com todos os componentes do pacote.
  6. No Iniciador de aplicativos, encontre e selecione o aplicativo DreamHouse e confira alguns de seus recursos.
Mostra um exemplo da mensagem de e-mail recebida quando o pacote dreamhouse é devidamente instalado no Trailhead Playground.