Compartir por

Crear paquetes para a ferramenta Package Deployer

  • Artigo

Package Deployer permite que os administradores apliquen paquetes en instancias de Microsoft Dataverse. Un paquete de Package Deployer pode consistir en calquera ou todos os elementos seguintes:

  • Un ou máis ficheiros de solución de Dataverse.
  • Ficheiros sen formato ou ficheiros de datos de configuración exportados desde a ferramenta Migración de configuración. Para obter máis información acerca da ferramenta, consulte Mover datos de configuración entre instancias e organizacións con Configuration Migration Tool.
  • Código personalizado que pode executarse antes, durante ou despois de que se aplique o paquete na instancia de Dataverse.
  • Contido HTML específico para o paquete que pode mostrarse ao inicio e ao fin do proceso de despregamento. Este contido pode ser útil para fornecer unha descrición das solucións e ficheiros que se despregan no paquete.

Nota

Hai outro tipo de paquete chamado paquete de complementos. Este tipo de paquete é para conxuntos dependentes de complementos e non ten ningunha relación cos paquetes de Package Deployer.

Requisitos previos

  • Asegúrese de ter preparados todos os ficheiros de solucións e outros ficheiros que quere incluír no paquete.
  • Visual Studio Código 2019 ou posterior, ou Visual Studio .

Visión xeral do proceso

Para crear un paquete Package Deployer , realice os seguintes pasos.

  • Crear un proxecto de Visual Studio ou MSBuild
  • Engadir solucións e outros ficheiros ao proxecto
  • Actualizar os ficheiros HTML proporcionados (opcional)
  • Especificar os valores de configuración do paquete
  • Definir o código personalizado do paquete
  • Construír e despregar o paquete

Estes pasos descríbense en detalle neste artigo.

Crear un proxecto de paquete

O primeiro paso é crear un proxecto de Visual Studio ou MSBuild para o paquete. Para facelo, debe ter instalada unha das dúas extensións de ferramentas dispoñibles no seu ordenador de desenvolvemento. Se usa Visual Studio Code, instale a CLI de Microsoft Power Platform. Se non, se usa Visual Studio 2019 ou posterior, instale Power Platform ferramentas para Visual Studio.

Seleccione o separador adecuado a continuación para descubrir como crear un proxecto usando a extensión de ferramenta desexada. Ambas as ferramentas emiten o proxecto nun formato similar.

Execute o comando pac package init para crear o paquete inicial. Máis información: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

A saída da CLI resultante contén os cartafoles e ficheiros que se mostran a continuación. O nome do cartafol "DeploymentPackage" utilizouse aquí como exemplo.

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

No proxecto creado, atopa o ficheiro de configuración importConfig.xml no cartafol PKGassets e o ficheiro PackageImportExtension.cs. Modificarás estes ficheiros como se describe máis adiante neste artigo.

Engadir ficheiros ao paquete

Despois de crear un proxecto de paquete, pode comezar a engadir solucións e outros ficheiros a ese proxecto.

Ao usar a CLI, pode engadir paquetes externos, solucións e referencias ao proxecto de paquete mediante un dos subcomandos add. Introduza pac package help para ver a lista de subcomandos. Imos engadir unha solución ao noso paquete.

> 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 paquete

Defina a configuración do paquete engadindo información acerca do paquete no ficheiro ImportConfig.xml no proxecto. Consulte ImportConfig Referencia para un exemplo e descricións dos elementos e atributos válidos para usar.

Engadir código personalizado

Pode engadir código personalizado que se executa antes, durante e despois de importar o paquete a un ambiente. Para facelo, siga estas instrucións.

  1. Edite o ficheiro PackageTemplate.cs (ou PackageImportExtension.cs) no cartafol raíz do proxecto.

  2. No ficheiro C#, pode:

    1. Insira o código personalizado para executar cando o paquete se inicie na definición de método de substitución de InitializeCustomExtension.

      Este método pode empregarse para que os usuarios usen os parámetros de tempo de execución ao executar un paquete. Como programador, pode engadir compatibilidade para calquera parámetro de tempo de execución no seu paquete mediante a propiedade RuntimeSettings sempre que teña o código para procesalo en función da entrada do usuario.

      Por exemplo, o seguinte código de exemplo activa un parámetro de tempo de execución denominado SkipChecks para o paquete que ten dous valores posibles: true ou false. O código de exemplo verifica se o usuario especificou algún parámetro de tempo de execución durante a execución de Package Deployer (mediante a liña de comandos ou PowerShell) e, en función diso, procesa a información. Se o usuario non especifica ningún parámetro de tempo de execución mentres executa o paquete, o valor da propiedade 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");  
}

      Este código permite que o administrador use a liña de comandos ou o cmdlet Import-CrmPackage para especificar se pode saltar as verificacións de seguranza durante a execución da ferramenta Package Deployer para importar o paquete. Máis información: Aplicar paquetes mediante Package Deployer e Windows PowerShell

    2. Insira o código personalizado para executar antes de que importen as solucións na definición de método de substitución de PreSolutionImport para especificar se quere manter ou substituír as personalizacións mentres se actualiza a solución especificada nunha instancia de Dataverse de destino e se quere activar automaticamente complementos e fluxos de traballo.

    3. Use a definición do método de anulación de RunSolutionUpgradeMigrationStep para realizar a transformación de datos ou a actualización entre dúas versións dunha solución deste método chámase só se a solución que estás importando xa está presente no obxectivo Dataverse instancia.

      Esta función espera os seguintes parámetros:

      Parámetro Descripción
      solutionName Nome da solución
      oldVersion Número de versión da solución antiga
      newVersion Número de versión da solución nova
      oldSolutionId GUID da solución antiga.
      newSolutionId GUID da solución nova.

    4. Insira o código personalizado para executar antes de que conclúa a importación da solución na definición de substitución do método BeforeImportStage. Os datos de exemplo e algúns ficheiros sen formato para as solucións especificadas no ficheiro ImportConfig.xml impórtanse antes de que se complete a importación da solución.

    5. Anular o idioma seleccionado actualmente para a importación de datos de configuración mediante a definición do método de anulación de OverrideConfigurationDataFileLanguage. Se o ID de localización local (LCID) do idioma especificado non se atopa na lista de idiomas dispoñibles no paquete, o ficheiro de datos predeterminado é importado.

      Especifique os idiomas dispoñibles para os datos de configuración no nó <cmtdatafiles> do ficheiro ImportConfig.xml. O ficheiro de importación de datos de configuración predefinido está especificado no atributo crmmigdataimportfile do ficheiro ImportConfig.xml.

      Saltar comprobacións de datos (OverrideDataImportSafetyChecks = true) pode ser efectiva aquí se estás seguro de que o obxectivo Dataverse a instancia non contén datos.

    6. Insira o código personalizado para executar despois de que conclúa a importación da solución na definición de substitución do método AfterPrimaryImport>. Os ficheiros planos restantes que non se importaron anteriormente, antes de que comezasen a importación de solucións, agora importan.

    7. Modifique o nome predefinido do cartafol do paquete ao nome do paquete que queira. Para iso, renomee o cartafol PkgFolder (ou PkgAssets) no panel Explorador de solucións e despois edite o valor de devolución na propiedade 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. Modifique o nome do paquete editando o valor de devolución na propiedade GetNameOfImport.

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

      Este valor devolto é o nome do seu paquete que aparece na páxina de selección de paquetes no asistente de Dynamics 365 Package Deployer .

    9. Modifique o nome da descrición editando o valor de devolución na propiedade GetImportPackageDescriptionText.

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

      Este valor devolto é a descrición do paquete que aparece xunto ao nome do paquete na páxina de selección de paquetes no asistente Package Deployer .

    10. Modifique o nome longo do paquete editando o valor de devolución na propiedade GetLongNameOfImport.

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

      O nome longo do paquete aparece na páxina seguinte despois de seleccionar o paquete que se vai instalar.

  3. Ademais, as seguintes funcións e variables están dispoñibles para o paquete:

    Nome Tipo Descripción
    CreateProgressItem(String) Function Utilízase para crear un novo elemento de progreso na interface de usuario (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Úsase para actualizar o progreso creado pola chamada a CreateProgressItem(String).

    ProgressPanelItemStatus é unha enumeración cos seguintes valores:

    Traballando = 0
    Completo = 1
    Erro = 2
    Aviso = 3
    Descoñecido = 4
    RaiseFailEvent(String, Exception) Function Úsase para suspender a importación de estado actual cunha mensaxe de excepción.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Utilízase para determinar se un rol está asociado a un equipo especificado.
    IsWorkflowActive(Guid) Function Utilízase para determinar se un fluxo de traballo especificado está activo.
    PackageLog Punteiro de clase Un punteiro para a interface de rexistro iniciada do paquete. Esta interface úsaa un paquete para rexistrar mensaxes e excepcións para o ficheiro de rexistro de paquetes.
    RootControlDispatcher Propiedade Unha interface do distribuidor usada para permitirlle controlar o procesamento da súa propia interface de usuario durante o despregamento de paquetes. Utilice esta interface para axustar os elementos ou comandos da interface de usuario. É importante comprobar esta variable por valores nulos antes de usala, xa que pode que non se axuste a un valor.
    CrmSvc Propiedade Un punteiro para a clase CrmServiceClient que permite que un paquete se dirixa a Dynamics 365 desde o paquete. Utilice este punteiro para executar métodos SDK e outras accións nos métodos anulados.
    DataImportBypass Propiedade Especifique se Package Deployer de Dynamics 365 omite todas as operacións de importación de datos, como a importación de datos de exemplo, datos de ficheiros sen formato e datos exportados de Dataverse desde Configuration Migration Tool. Especifique se é true ou false. O valor predefinido é false.
    OverrideDataImportSafetyChecks Propiedade Especifique se Dynamics 365 Package Deployer desvía algúns dos seus controis de seguridade, o que axuda a mellorar o rendemento da importación. Especifique true ou false. O valor predefinido é false.

    Debe configurar esta propiedade en true só se a instancia de destino Dataverse non contén datos.

  4. Garde o seu proxecto. O seguinte paso é para construír o paquete.

Construír de despregar

As seguintes seccións describen como construír e implementar un paquete.

Compilar

A construción do seu paquete descríbese a continuación segundo a ferramenta que estea a usar.

Para construír un paquete creado co CLI, podes cargar o ficheiro .csproj en Visual Studio, pero en cambio imos usar o comando dotnet e msbuild. O seguinte exemplo asume que o directorio de traballo contén o ficheiro *.csproj.

> dotnet publish

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

Opcionalmente, pode ver os detalles do paquete construído.

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

O seu paquete está formado polos seguintes ficheiros no cartafol <Project>\Bin\Debug.

  • <Packagename > cartafol : o nome do cartafol é o mesmo que o que cambiou para o nome do cartafol do paquete en paso 2.g desta sección Engadir Código personalizado. Este cartafol contén todas as solucións, datos de configuración, ficheiros sen formato e contido do paquete.

Nota

Pode ver un cartafol .NET (por exemplo, net472) que contén un cartafol pdpublish. O seu DLL e outros ficheiros do proxecto están nese cartafol pdpublish.

  • <PackageName>.dll: o ensamblado contén o código personalizado para o paquete.. Por defecto, o nome da ensamblaxe é igual ao nome do seu proxecto.

Aplicar

Despois de crear un paquete, pode aplicalo na instancia de Dataverse mediante a ferramenta Package Deployer, Windows PowerShell ou un comando de CLI.

Recomendacións

A continuación móstranse algúns consellos de prácticas recomendadas que debe seguir ao traballar con paquetes de Package Deployer.

Creación de paquetes

Ao crear paquetes, os programadores deben:

  • Asegurarse de que os conxuntos de paquetes estean asinados.

Despregamento de paquetes

Ao despregar paquetes, os administradores de Dataverse deben:

  • Insistir en ensamblados de paquetes asinados para poder rastrexar un ensamblado até a súa orixe.
  • Proba o paquete nunha instancia de preproducción , preferiblemente unha imaxe espello do instancia de produción, antes de executalo nun instancia de produción.
  • Realizar unha copia de seguranza da instancia de produción antes de despregar o paquete.

Consulte tamén

Ferramenta Empaquetador de solucións