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 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.
Observação
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.
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.
Você pode criar um projeto do Visual Studio usando o Modelo de Solução do Power Platform e depois adicionar um projeto de pacote usando o modelo do Projeto de Implantação do Pacote do Power Platform ou criar um projeto diretamente usando o modelo do Projeto de Implantação de Pacote do Power Platform.
Observação
Não escolha o modelo de pacote da Power Platform. Esse modelo destina-se a pacotes de plug-in.
A solução e o projeto resultantes do Visual Studio contém as pastas e os arquivos mostrados abaixo. O nome da pasta "Deployment-package" foi usado aqui como exemplo. O conteúdo da pasta Conteúdo não é mostrado aqui por questões de brevidade.
No projeto criado, encontre o arquivo de configuração ImportConfig.xml na pasta PkgFolder e o arquivo PackageTemplate.cs. Você modificará esses arquivos conforme descrito posteriormente neste artigo.
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.
No painel do Explorador da solução, adicione as soluções do Dataverse e outros arquivos na pasta PkgFolder. Os arquivos HTML pertencem à pasta Conteúdo. Saiba mais sobre esse conteúdo HTML posteriormente.
Para cada arquivo adicionado, no painel Propriedades, defina o valor de Copiar para diretório de saída para Sempre copiar. A configuração desse valor garante que seus arquivos estejam disponíveis no pacote gerado.
Em seguida, atualize os arquivos específicos da linguagem HTML.
No painel Gerenciador de Soluções, expanda PkgFolder>Conteúdo>en-us. Localize duas pastas chamadas WelcomeHTML e EndHTML. Essas pastas contêm os arquivos HTML e os arquivos associados que permitem exibir (para o usuário) as informações no final e no início do processo de implantação do pacote. Edite os arquivos na pasta HTML dessas pastas para adicionar informações a serem exibidas para seu pacote.
Também é possível adicionar os arquivos HTML do pacote em outros idiomas, para que o conteúdo no HTML seja exibido no idioma com base nas configurações da localidade do computador do usuário. Para fazer isto:
Crie uma cópia da pasta en-us em PkgFolder>Conteúdo.
Renomeie a pasta copiada para o idioma adequado. Por exemplo, para o idioma espanhol, renomeie-a para es-ES.
Modifique o conteúdo dos arquivos HTML para adicionar o conteúdo em espanhol.
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:
Edite o arquivo PackageTemplate.cs (ou PackageImportExtension.cs) na pasta raiz do projeto.
No arquivo C#, é possível:
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");
}
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.
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.
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.
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.
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.
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";
}
}
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.
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.
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.
Além disso, as seguintes funções e variáveis estão disponíveis para o pacote:
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.
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.
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.
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.
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.
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.
Você também pode ver os detalhes do pacote criado.
> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
Para compilar o pacote, pressione F5 no Visual Studio ou selecione Compilar>Compilar Solução.
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.
Observação
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.
Para implantar um pacote em um ambiente de destino usando a CLI, você deve primeiro configurar um perfil de autenticação e selecionar uma organização. Mais informações: pac auth create, pac org select
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.