Criar pacotes para a ferramenta Package Deployer

O Package Deployer permite aos administradores implementar pacotes em instâncias do Microsoft Dataverse. Um pacote do Package Deployer pode ser composto por qualquer um ou todos os seguintes:

• Um ou mais ficheiros de solução do Dataverse.
• Ficheiros simples ou ficheiros de dados de configuração exportados pela Ferramenta de Migração da Configuração. Para mais informações sobre a ferramenta, consulte Mover dados de configuração entre instâncias e organizações com a Ferramenta de Migração da Configuração.
• Código personalizado que pode ser executado antes, durante ou após o pacote ser implementado na instância do Dataverse.
• O conteúdo HTML específico do pacote que pode ser apresentado no início e no fim do processo de implementação. Este conteúdo pode ser útil fornecer uma descrição de soluções e dos ficheiros que são implementados no pacote.

Pré-requisitos

• Certifique-se de que tem todos os ficheiros de solução e outros prontos que pretende incluir no pacote.
• Visual Studio 2019 ou posterior, ou o Visual Studio Code.

Descrição geral do processo

Para criar um pacote do Package Deployer, efetue os passos que se seguem.

Estes passos são descritos detalhadamente neste artigo.

Criar um projeto de pacote

O primeiro passo é criar um projeto do Visual Studio ou do MSBuild para o pacote. Para tal, tem de ter uma de duas extensões de ferramenta disponíveis instaladas no seu computador de desenvolvimento. Se estiver a utilizar o Visual Studio Code, instale a Microsoft Power Platform CLI. Caso contrário, se estiver a utilizar o Visual Studio 2019 ou posterior, instale o Power Platform Tools para o Visual Studio.

Selecione o separador apropriado abaixo para saber como criar um projeto utilizando a extensão de ferramenta pretendida. Ambas as ferramentas resultam num projeto de formato semelhante.

pac package init help
pac package init --outputDirectory DeploymentPackage

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

Adicionar ficheiros de pacote

Depois de criar um projeto de pacote, pode começar a adicionar soluções e outros ficheiros a esse projeto.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Configurar o pacote

Defina a configuração do pacote ao adicionar informações sobre o seu pacote no ficheiro ImportConfig.xml no projeto. Consulte a Referência ImportConfig para obter um exemplo e descrições dos elementos e atributos válidos a serem utilizados.

Adicionar código personalizado

Pode adicionar código personalizado que seja executado antes, durante e depois de o pacote ser importado para um ambiente. Para tal, siga estas instruções.

1. Edite o ficheiro PackageTemplate.cs (ou PackageImportExtension.cs) na pasta raiz do projeto.

2. No ficheiro C#, pode:

   1. Introduzir o código personalizado a executar quando o pacote é inicializado na definição do método de substituição de InitializeCustomExtension.

      Este método pode ser utilizado para permitir que os utilizadores utilizem os parâmetros de runtime durante a execução de um pacote. Como programador, pode adicionar suporte para qualquer parâmetro de runtime ao seu pacote, através da propriedade RuntimeSettings, desde que tenha código para o processar com base na entrada do utilizador.

      Por exemplo, o código de exemplo seguinte ativa um parâmetro de runtime chamado SkipChecks para o pacote que tem dois valores possíveis: true ou false. O código de exemplo verifica se o utilizador especificou quaisquer parâmetros de runtime durante a execução do Package Deployer (quer utilizando a linha de comando, quer o PowerShell), e, em seguida, processa as informações em conformidade. Se não forem especificados parâmetros de runtime pelo utilizador durante a execução do pacote, o valor da propriedade RuntimeSettings será nulo.

      public override void InitializeCustomExtension()  
      {
        // Validate the state of the runtime settings object.  
        if (RuntimeSettings != null)  
        {  
            PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}",
                RuntimeSettings.Count));  
            foreach (var setting in RuntimeSettings)  
            {  
                PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, 
                    setting.Value.ToString()));  
            }  
      
            // Check to see if skip checks is present.  
            if ( RuntimeSettings.ContainsKey("SkipChecks") )  
            {  
                bool bSkipChecks = false;  
                if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
                    OverrideDataImportSafetyChecks = bSkipChecks;  
            }  
        }  
        else
        {
            PackageLog.Log("Runtime Settings not populated");
        }  
      } 
      

      Este código permite que o administrador utilize a linha de comando ou o cmdlet Import-CrmPackage para especificar se as verificações de segurança devem ser ignoradas durante a execução da ferramenta Package Deployer para importar o pacote. Mais informações: Implementar pacotes utilizando o Package Deployer e o Windows PowerShell

   2. Introduzir código personalizado a executar antes de as soluções serem importadas na definição do método de substituição de PreSolutionImport para especificar se as personalizações são mantidas ou substituídas durante a atualização da solução especificada numa instância do Dataverse de destino, e se os plug-ins e os fluxos de trabalho são ativados automaticamente.

   3. Utilizar a definição do método de substituição de RunSolutionUpgradeMigrationStep para efetuar a transformação dos dados ou atualizar entre duas versões de uma solução. Este método é chamado apenas se a solução que está a importar já estiver presente na instância do Dataverse.

      Esta função espera os seguintes parâmetros:

      Parâmetro	Descrição
      solutionName	Nome da solução
      oldVersion	Número da versão da solução antiga
      newVersion	Número da versão da nova solução
      oldSolutionId	GUID da solução antiga.
      newSolutionId	GUID da nova solução.

   4. Substitua o método OverrideSolutionImportDecision para retornar um enum UserRequestedImportAction que controla se a importação de uma solução será ignorada, atualizada ou melhorada (o padrão).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
        string solutionUniqueName, Version organizationVersion,
        Version packageSolutionVersion, Version inboundSolutionVersion,
        Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
      {
        return systemSelectedImportAction == 
            ImportAction.Import ? UserRequestedImportAction.ForceUpdate
            : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
            packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
            systemSelectedImportAction);
      }
      

   5. Introduzir o código personalizado a executar antes da conclusão da importação da solução na definição de substituição do método BeforeImportStage. Os dados de exemplo e alguns ficheiros simples para soluções especificados no ficheiro ImportConfig.xml são importados antes da conclusão da importação da solução.

   6. Substituir o idioma selecionado atualmente para a importação de dados de configuração através da definição do método de substituição de OverrideConfigurationDataFileLanguage. Se o ID de região (LCID) especificado do idioma especificado não for encontrado na lista de idiomas disponíveis no pacote, é importado o ficheiro de dados predefinido.

      Especifique os idiomas disponíveis para os dados de configuração no nó <cmtdatafiles> no ficheiro ImportConfig.xml. O ficheiro de importação de dados de configuração predefinido é especificado no atributo crmmigdataimportfile no ficheiro ImportConfig.xml.

      Ignorar verificações de dados (OverrideDataImportSafetyChecks = true) pode ser eficaz aqui se tiver a certeza de que a instância do Dataverse de destino não contém quaisquer dados.

   7. Introduzir o código personalizado a executar depois da conclusão da importação na definição de substituição do método AfterPrimaryImport>. Os restantes ficheiros simples que não foram importados anteriormente, antes de iniciada a importação da solução, são importados agora.

   8. Altere o nome predefinido da sua pasta do pacote para o nome do pacote que pretende. Para tal, mude o nome da pasta PkgFolder (ou PkgAssets) no painel Explorador de Soluções e, em seguida, edite o valor devolvido na propriedade GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
      {  
          get  
          {  
              // WARNING this value directly correlates to the folder name in Solution 
              // Explorer where the ImportConfig.xml and sub content is located.  
              // Changing this name requires that you also change the correlating name
              // in Solution Explorer.
              return "PkgFolder";  
          }  
      }  
      

   9. Alterar o nome do pacote ao editar o valor devolvido sob a propriedade GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
      {  
          return "Package Short Name";  
      }  
      

      Este valor devolvido é o nome do seu pacote que aparece na página de seleção do pacote no assistente do Dynamics 365 Package Deployer.

   10. Alterar a descrição do pacote ao editar o valor devolvido sob a propriedade GetImportPackageDescriptionText.

       public override string GetImportPackageDescriptionText  
       {  
           get { return "Package Description"; }  
       }  
       

       Este valor devolvido é a descrição do pacote que aparece junto ao nome do pacote na página de seleção de pacotes no assistente do Package Deployer.

   11. Alterar o nome longo do pacote ao editar o valor devolvido sob a propriedade GetLongNameOfImport.

       public override string GetLongNameOfImport  
       {  
           get { return "Package Long Name"; }  
       }  
       

       O nome longo da embalagem aparece na página seguinte depois de selecionar o pacote a instalar.

3. Adicionalmente, estão disponíveis para o pacote a seguinte função e variáveis:

   Nome	Tipo	Descrição
   CreateProgressItem(String)	Function	Utilizado para criar um novo item do progresso na interface do utilizador (IU).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Utilizado para atualizar o progresso criado pela chamada para CreateProgressItem(String). ProgressPanelItemStatus é um enum com os seguintes valores: Em curso = 0 Concluído = 1 Com falhas = 2 Aviso = 3 Desconhecido = 4
   RaiseFailEvent(String, Exception)	Function	Utilizado para causar a falha da importação do estado atual com uma mensagem de exceção.
   <xref:Microsoft.Xrm.Tooling.PackageDeployment.CrmPackageExtentionBase.ImportExtension.IsRoleAssociatedWithTeam(System.Guid,System.Guid)>	Function	Utilizado para determinar se uma função está associada a uma equipa especificada.
   IsWorkflowActive(Guid)	Function	Utilizado para determinar se um fluxo de trabalho especificado está ativo.
   PackageLog	Ponteiro de Classes	Um ponteiro para a interface de registo inicializada para o pacote. Esta interface é utilizada por um pacote para registar mensagens e exceções no ficheiro de registo de pacotes.
   RootControlDispatcher	Propriedade	Uma interface de distribuidor utilizada para permitir que o controlo componha a sua própria IU durante a implementação do pacote. Utilize esta interface para encapsular quaisquer comandos ou elementos da IU. É importante verificar se esta variável tem valores nulos antes de a utilizar, uma vez que pode não ter sido definida com um valor.
   CrmSvc	Propriedade	Um ponteiro para a classe CrmServiceClient que permite que um pacote direcione o Dynamics 365 a partir do pacote. Utilize este ponteiro para executar métodos SDK e outras ações nos métodos substituídos.
   DataImportBypass	Propriedade	Especifique se o Package Deployer do Dynamics 365 ignora todas as operações de importação de dados, tal como importar dados de amostra, dados de ficheiros simples e dados exportados do Dataverse a partir da Ferramenta de Migração da Configuração. Especifique true ou false. A predefinição é false.
   OverrideDataImportSafetyChecks	Propriedade	Especifique se o Dynamics 365 Package Deployer ignora algumas das respetivas verificações de segurança, o que ajuda na melhoria do desempenho de importação. Especifique true ou false. A predefinição é false. Deve definir esta propriedade como true apenas se a instância do Dataverse de destino não contiver quaisquer dados.

4. Guarde o seu projeto. O passo seguinte é compilar o pacote.

Compilar e implementar

As secções que se seguem descrevem como criar e implementar um pacote.

Compilar

A criação do seu pacote é descrita abaixo dependendo da ferramenta que está a usar.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

O seu pacote é composto pelos seguintes ficheiros na pasta <Project>\Bin\Debug.

• <Pasta> PackageName: O nome da pasta é o mesmo que você alterou para o nome da pasta do pacote na etapa 2.g desta secção Adicionar código personalizado. Esta pasta contém todas as soluções, dados de configuração, ficheiros simples e os conteúdos para o pacote.

• <PackageName>.dll: O assembly contém o código personalizado para seu pacote. Por predefinição, o nome da assemblagem é igual ao nome do projeto.

Implementar

Depois de criar um pacote, pode implementá-lo na instância do Dataverse utilizando a ferramenta Package Deployer ou o Windows PowerShell ou um comando da CLI.

• Para implementar a utilização da ferramenta do Package Deployer, primeiro transfira a ferramenta conforme descrito em ferramentas de programação do Dataverse. Depois, siga as informações detalhadas sobre implementação de pacotes no artigo Implementar pacotes com o Package Deployer ou o Windows PowerShell.

• Para implementar a CLI, utilize o comando pac package deploy.

  > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
  

  Nota

  Para implementar um pacote para um ambiente de destino utilizando a CLI, tem primeiro de configurar um perfil de autenticação e selecione uma organização. Mais informações: pac auth create, pac org select

Melhores práticas

Em seguida, seguem-se algumas sugestões de melhores práticas quando trabalha com pacotes do Package Deployer.

Criar pacotes

Quando criar pacotes, os programadores têm de:

• Certifique-se de que os assemblies de pacote estejam assinados.

Implementar pacotes

Ao implementar pacotes, os administradores do Dataverse têm de:

• Insista em assemblies de pacote assinados para que você possa rastrear um assembly de volta à sua origem.
• Teste o pacote em uma instância de pré-produção, de preferência uma imagem espelhada da instância de produção, antes de executá-lo em uma instância de produção.
• Faça backup da instância de produção antes de implantar o pacote.

Consulte também

Ferramenta Empacotador de Soluções