Compartilhar via

Criar pacote para a ferramenta Package Deployer

  • Artigo

O Package Deployer permite que os administradores implantem pacotes nas instâncias do Microsoft Dataverse. Um pacote do Package Deployer pode consistir em todos ou qualquer um dos itens a seguir:

  • Um ou mais arquivos de solução do Dataverse.
  • Arquivos de dados simples ou de configuração exportados da ferramenta Migração de Configuração. Para obter mais informações sobre a ferramenta, consulte Mover dados de configuração em instâncias e organizações com a ferramenta Migração de Configuração.
  • Um código personalizado que pode ser executado antes, durante ou depois do pacote ser implantado na instância do Dataverse.
  • Um conteúdo HTML específico para o pacote que pode ser exibido no início e no final do processo de implantação. Esse conteúdo pode ser útil para fornecer uma descrição das soluções e dos arquivos que são implantados no pacote.

Nota

Existe outro tipo de pacote chamado pacote de plug-in. Esse tipo de pacote destina-se a assemblies dependentes de plug-in e não tem relação com pacotes do Package Deployer.

Pré-requisitos

  • Verifique se você tem toda a solução e outros arquivos prontos que deseja incluir no pacote.
  • Visual Studio 2019 ou posterior, ou Visual Studio Code.

Visão geral do processo

Para criar um pacote do Package Deployer, execute etapas a seguir.

  • Criar um projeto do Visual Studio ou MSBuild
  • Adicionar soluções e outros arquivos ao projeto
  • Atualizar arquivos HTML fornecidos (opcional)
  • Especificar os valores de configuração do pacote
  • Definir código personalizado para o pacote
  • Criar e implantar o pacote

Essas etapas estão descritas aqui neste artigo.

Criar um projeto de pacote

A primeira etapa é criar um projeto do Visual Studio ou MSBuild para o pacote. Para fazer isso, você deve ter uma das duas extensões de ferramenta disponíveis instaladas em seu computador de desenvolvimento. Se estiver usando o Visual Studio Code, instale o Microsoft Power Platform CLI. Caso contrário, se estiver usando o Visual Studio 2019 ou posterior, instale as Power Platform Tools para Visual Studio.

Selecione a guia apropriada abaixo para descobrir como criar um projeto usando a extensão de ferramenta desejada. Ambas as ferramentas produzem o projeto em um formato semelhante.

Execute o comando pac package init para criar o pacote inicial. Mais informações: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

A saída da CLI resultante contém as pastas e arquivos mostrados abaixo. O nome da pasta "DeploymentPackage" foi usado aqui como exemplo.

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

No projeto criado, encontre o arquivo de configuração ImportConfig.xml na pasta PkgAssets e o arquivo PackageImportExtension.cs. Você modificará esses arquivos conforme descrito posteriormente neste artigo.

Adicionar arquivos de pacote

Depois de criar um projeto de pacote, é possível começar a adicionar soluções e outros arquivos a esse projeto.

Ao usar a CLI, você pode adicionar pacotes, soluções e referências externas ao seu projeto de pacote usando um dos subcomandos adicionar. Digite pac package help para ver a lista de subcomandos. Vamos adicionar uma solução ao nosso pacote.

> 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 adicionando informações sobre o pacote no arquivo ImportConfig.xml disponível no projeto. Consulte a Referência ImportConfig para obter um exemplo e descrições dos elementos e atributos válidos a serem usados.

Adicionar código personalizado

É possível adicionar código personalizado que é executado antes, durante e depois que o pacote é importado para um ambiente. Para isso, siga estas instruções:

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

  2. No arquivo C#, é possível:

    1. Digite o código personalizado que será executado quando o pacote é inicializado na definição do método de substituição de InitializeCustomExtension.

      Esse método pode ser usado para permitir que os usuários usem os parâmetros em tempo de execução ao executar um pacote. Como desenvolvedor, você pode adicionar suporte a todos os parâmetros em tempo de execução a seu pacote usando a propriedade RuntimeSettings, desde que você tenha código para processá-los com base na entrada do usuário.

      Por exemplo, o código de exemplo a seguir permite um parâmetro em tempo de execução chamado SkipChecks para o pacote que contém dois valores possíveis: verdadeiro ou falso. O código de exemplo verifica se o usuário especificou os parâmetros em tempo de execução ao executar Package Deployer (usando a linha de comandos ou o PowerShell) e, em seguida, processa as informações de forma adequada. Se nenhum parâmetro de tempo de execução for especificado pelo usuário durante a execução do pacote, o valor da propriedade RuntimeSettings será nulo.

      public override void InitializeCustomExtension()  
{  
// Do nothing.  

// 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");  
}

      Esse código permite que o administrador use a linha de comandos ou o cmdlet Import-CrmPackage para especificar se ignora as verificações de segurança ao executar a ferramenta Package Deployer para importar o pacote. Mais informações: Implantar pacotes usando o Package Deployer e o Windows PowerShell

    2. Digite o código personalizado a ser executado antes de as soluções serem importadas na definição do método de substituição PreSolutionImport para especificar se as personalizações devem ser mantidas ou substituídas ao atualizar a solução especificada em uma instância de destino do Dataverse e se os plug-ins e os fluxos de trabalho devem ser ativados automaticamente.

    3. Use a definição do método de substituição de RunSolutionUpgradeMigrationStep para executar transformação ou atualização de dados entre duas versões de uma solução. Esse método é chamado apenas se a solução que você está importando já estiver presente na instância de destino do Dataverse.

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

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

    4. Digite o código personalizado a ser executado antes da conclusão da importação da solução na definição da substituição do método BeforeImportStage. Os dados de exemplo e alguns arquivos simples para soluções especificadas no arquivo ImportConfig.xml são importados antes da importação da solução ser concluída.

    5. Substitua o idioma atual selecionado para a importação dos dados de configuração usando a definição do método de substituição OverrideConfigurationDataFileLanguage. Se a LCID (identificação de localidade) do idioma especificado não for encontrada na lista de idiomas disponíveis no pacote, o arquivo de dados padrão será importado.

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

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

    6. Digite o código personalizado a ser executado depois da conclusão da importação na definição da substituição do método AfterPrimaryImport>. Os arquivos simples restantes que não foram importados anteriormente, antes do início da importação da solução, agora são importados.

    7. Altere o nome padrão da pasta do pacote para o nome de pacote desejado. Para fazer isso, renomeie a pasta PkgFolder (ou PkgAssets) no painel do Gerenciador de Soluções e edite o valor de retorno na propriedade GetImportPackageDataFolderName.

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

    8. Altere o nome do pacote editando o valor de retorno na propriedade GetNameOfImport.

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

      Este valor retornado é o nome do pacote que será exibido na página de seleção do pacote no assistente do Package Deployer do Dynamics 365.

    9. Altere a descrição do pacote editando o valor de retorno na propriedade GetImportPackageDescriptionText.

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

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

    10. Altere o nome longo do pacote editando o valor de retorno na propriedade GetLongNameOfImport.

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

      O nome longo do pacote é exibido na página seguinte, após a seleção do pacote que será instalado.

  3. Além disso, as seguintes funções e variáveis estão disponíveis para o pacote:

    Nome Tipo Descrição
    CreateProgressItem(String) Função Usada para criar um novo item de progresso na interface do usuário (IU).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Função Usada para atualizar o progresso criado pela chamada para CreateProgressItem(String).

    ProgressPanelItemStatus é um enumeração com os seguintes valores:

    Trabalho = 0
    Conclusão = 1
    Falha = 2
    Aviso = 3
    Desconhecido = 4
    RaiseFailEvent(String, Exception) Function Usada para causar uma falha na importação do status atual com uma mensagem de exceção.
    IsRoleAssoicatedWithTeam(Guid, Guid) Função Usada para determinar se uma função é associada a uma equipe especificada.
    IsWorkflowActive(Guid) Função Usada para determinar se um fluxo de trabalho especificado está ativo.
    PackageLog Ponteiro de classes Um ponteiro na interface de log inicializada do pacote. Esta interface é utilizada por um pacote para registrar em log as mensagens e exceções no arquivo de log do pacote.
    RootControlDispatcher Propriedade Uma interface de distribuidor utilizada para permitir que o controle renderize sua própria interface do usuário durante a implantação do pacote. Utilize esta interface para empacotar os elementos ou comandos da interface do usuário. É importante verificar esta variável para valores nulos antes de usá-lo como pode ou não pode ser definido para um valor.
    CrmSvc Propriedade Um ponteiro para a classe CrmServiceClient que permite que um pacote enderece o Dynamics 365 a partir do pacote. Use esse ponteiro para executar os 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, como a importação de dados de exemplo do Dataverse, dados de arquivos simples e dados exportados da ferramenta Migração de Configuração. Especifique true ou false. O padrão é false.
    OverrideDataImportSafetyChecks Propriedade Especifique se o Package Deployer do Dynamics 365 ignora algumas de suas verificações de segurança, o que ajuda a melhorar o desempenho da importação. Especifique true ou false. O padrão é false.

    Defina esta propriedade como true apenas se a instância de destino do Dataverse não contiver nenhum dado.

  4. Salve seus projetos. A próxima etapa é criar o pacote.

Criar e implantar

As seções a seguir descrevem como construir e implantar um pacote.

Compilar

A construção do seu pacote é descrita abaixo dependendo da ferramenta que você está usando.

Para criar um pacote criado com a CLI, você pode carregar o arquivo .csproj no Visual Studio, mas em vez disso usaremos o comando dotnet e o MSBuild. O exemplo abaixo assume que o diretório de trabalho contém o arquivo *.csproj.

> dotnet publish

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

Você também pode ver os detalhes do pacote criado.

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

Seu pacote é composto dos seguintes arquivos na pasta <Project>\Bin\Debug folder.

  • <Nome do pacote> pasta : O nome da pasta é o mesmo que você alterou para o nome da pasta do seu pacote em etapa 2.g desta seção Adicionar código personalizado. Essa pasta contém todas as soluções, os dados de configuração, os arquivos simples e o conteúdo de seu pacote.

Nota

Talvez você veja uma pasta .NET (por exemplo, net472) contendo uma pasta pdpublish. Sua DLL e outros arquivos de projeto estão nessa pasta pdpublish.

  • <Nome do pacote> .DLL : O assembly contém o código personalizado para seu pacote. Por padrão, o nome do assembly será igual ao nome do seu projeto.

Implantar

Depois de criar um pacote, é possível implantá-lo na instância do Dataverse usando a ferramenta Package Deployer, o Windows PowerShell ou um comando da CLI.

Práticas recomendadas

Abaixo estão listadas algumas dicas de práticas recomendadas a serem seguidas ao trabalhar com pacotes do Package Deployer.

Criação de pacotes

Ao criar pacotes, os desenvolvedores devem:

  • Garantir que os conjuntos de pacotes sejam assinados.

Implantação de pacotes

Ao implantar pacotes, os administradores do Dataverse devem:

  • Insista em montagens de pacotes assinadas para que você possa rastrear uma montagem até sua origem.
  • Teste o pacote em uma instância de pré-produção, de preferência uma imagem espelhada do instância de produção, antes de executá-lo em um instância de produção.
  • Faça backup do instância de produção antes de implantar o pacote.

Consulte também

Ferramenta Solution Packager