Compartir a través de

Crear paquetes para la herramienta Package Deployer

  • Artículo

Package Deployer permite a los administradores implementar paquetes en instancias de Microsoft Dataverse. Un paquete de Package Deployer puede estar compuesto por cualquiera de estos elementos o por todos ellos:

  • Uno o varios archivos de solución de Dataverse.
  • Archivos sin formato o archivo de datos de configuración exportado desde la herramienta de migración de la configuración. Para obtener más información sobre la herramienta, consulte Mover datos de configuración entre instancias y organizaciones con la herramienta de migración de la configuración.
  • El código personalizado que puede ejecutarse antes, durante o después del paquete se implementa en la instancia de Dataverse.
  • Contenido HTML específico del paquete que mostrarse al principio y al final del proceso de implementación. Este contenido resultar útil para proporcionar una descripción de las soluciones y los archivos que se implementan en el paquete.

Nota

Hay otro tipo de paquete llamado paquete de complemento. Ese tipo de paquete es para ensamblajes dependientes de complementos y no tiene relación con paquetes de Package Deployer.

Requisitos previos

  • Asegúrese de que tiene todas las soluciones y otros archivos listos que desea incluir en el paquete.
  • Visual Studio 2019 o posterior, o Visual Studio Code.

Vista general del proceso

Para crear un paquete de Package Deployer, realice los pasos siguientes.

  • Crear un proyecto de Visual Studio o MSBuild
  • Agregar soluciones y otros archivos al proyecto
  • Actualice los archivos HTML proporcionados (opcional)
  • Especifique los valores de configuración para el paquete
  • Defina código personalizado para el paquete
  • Compilar e implementar el paquete

Estos pasos se describen en detalle en este artículo.

Crear un proyecto de paquete

El primer paso es crear un proyecto de Visual Studio o MSBuild para el paquete. Para hacer eso, debe tener una de las dos extensiones de herramientas disponibles instaladas en su computadora de desarrollo. Si usa Visual Studio Code, instale Microsoft Power Platform CLI. De lo contrario, si utiliza Visual Studio 2019 o posterior, instale Power Platform Tools para Visual Studio.

Seleccione la pestaña correspondiente a continuación para descubrir cómo crear un proyecto utilizando la extensión de herramienta deseada. Ambas herramientas generan el proyecto en un formato similar.

Ejecute el comando pac package init para crear el paquete inicial. Más información: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

La salida CLI resultante contiene las carpetas y los archivos que se muestran a continuación. El nombre de la carpeta "DeploymentPackage" se usó aquí como ejemplo.

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

En el proyecto creado, busque el archivo de configuración ImportConfig.xml en la carpeta PkgAssets y el archivo PackageImportExtension.cs. Modificará estos archivos como se describe más adelante en este artículo.

Agregar archivos a un paquete

Una vez que haya creado un proyecto de paquete, puede comenzar a agregar soluciones y otros archivos a ese proyecto.

Al usar la CLI, puede agregar paquetes externos, soluciones y referencias a su proyecto de paquete usando uno de los subcomandos agregar. Introduzca pac package help para ver la lista de subcomandos. Agreguemos una solución a nuestro 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 el paquete

Defina la configuración del paquete agregando información sobre el paquete en el archivo ImportConfig.xml en el proyecto. Consulte Referencia de ImportConfig para obtener un ejemplo y descripciones de los elementos y atributos válidos que se utilizarán.

Agregar código personalizado

Puede agregar código personalizado que se ejecute antes, durante y después de que el paquete se importe a un entorno. Para ello, siga estas instrucciones.

  1. Edite el archivo PackageTemplate.cs (o PackageImportExtension.cs) en la carpeta raíz del proyecto.

  2. En el archivo C# puede hacer lo siguiente:

    1. Escriba código personalizado para ejecutar cuando el paquete se inicie en la definición del método de sustitución de InitializeCustomExtension.

      Este método se puede usar para permitir a los usuarios usar los parámetros de tiempo de ejecución mientras ejecutan un paquete. Como programador, puede agregar compatibilidad para cualquier parámetro de tiempo de ejecución al paquete mediante la propiedad RuntimeSettings siempre que haga que el código lo procese basándose en la entrada del usuario.

      Por ejemplo, el siguiente código de ejemplo habilita un parámetro de tiempo de ejecución llamado SkipChecks para el paquete que tiene dos valores posibles: true o false. El código de ejemplo comprueba si el usuario ha especificado cualquier parámetro de tiempo de ejecución al ejecutar Package Deployer (usando la línea de comandos o PowerShell) y, a continuación procesa convenientemente la información. Si el usuario no especifica ningún parámetro en tiempo de ejecución al ejecutar el paquete, el valor de la propiedad RuntimeSettings será cero.

      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 al administrador usar la línea de comandos o el cmdlet Import-CrmPackage para especificar si se omiten las pruebas de seguridad al ejecutar la herramienta Package Deployer para importar el paquete. Más información: Implementar paquetes mediante Package Deployer y Windows PowerShell

    2. Introduzca código personalizado antes de importar las soluciones en la definición del método de reemplazo de PreSolutionImport para especificar si mantener o sobrescribir personalizaciones mientras actualiza la solución especificada en una instancia de Dataverse de destino y si se activan automáticamente complementos y flujos de trabajo.

    3. Utilice la definición del método de sustitución de RunSolutionUpgradeMigrationStep para realizar la transformación de datos o actualizar entre dos versiones de una solución. Este método se llama solo si la solución que va a importar ya está presente en la instancia de Dataverse de destino.

      Esta característica espera los siguientes parámetros:

      Parámetro Descripción
      solutionName Nombre de la solución
      oldVersion Número de versión de la solución antigua
      newVersion Número de versión de la solución nueva
      oldSolutionId GUID de la solución antigua.
      newSolutionId GUID de la solución nueva.

    4. Escriba código personalizado para ejecutar antes de que la importación de la solución se complete en la definición de reemplazo del método BeforeImportStage. Los datos de ejemplo y algunos archivos sin formato para soluciones especificadas en el archivo ImportConfig.xml se importan antes de que la importación de la solución se complete.

    5. Reemplace el idioma seleccionado actualmente para la importación de datos de configuración mediante la definición del método de reemplazo de OverrideConfigurationDataFileLanguage. Si el Id. de configuración regional (LCID) especificado del idioma especificado no se encuentra en la lista de idiomas disponibles en el paquete, se importa el archivo de datos predeterminado.

      Especifique los idiomas disponibles para los datos de configuración en el nodo <cmtdatafiles> del archivo ImportConfig.xml. El archivo de importación de datos de configuración predeterminado se especifica en el atributo crmmigdataimportfile en el archivo ImportConfig.xml.

      Omitir las verificaciones de datos (OverrideDataImportSafetyChecks = true) puede ser efectivo aquí si está seguro de que la instancia de Dataverse de destino no contiene ningún dato.

    6. Escriba código personalizado para ejecutar después de que la importación de la solución se complete en la definición de reemplazo del método AfterPrimaryImport>. Los archivos sin formato restantes que no se importaron anteriormente, antes de que la importación de la solución se iniciara, ahora se importan.

    7. Cambie el nombre predeterminado de la carpeta del paquete al nombre del paquete que desee. Para ello, cambie el nombre de la carpeta PkgFolder (o PkgAssets) en el panel Explorador de soluciones y luego edite el valor de devolución en la propiedad 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. Cambie el nombre del paquete editando el valor de devolución en la propiedad de GetNameOfImport.

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

      Éste valor devuelto es el nombre del paquete que aparecerá en la página de selección del paquete en el asistente para el Package Deployer de Dynamics 365.

    9. Cambie la descripción del paquete editando el valor de devolución en la propiedad de GetImportPackageDescriptionText.

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

      Éste valor devuelto es la descripción del paquete que aparecerá junto al nombre del paquete en la página de selección del paquete del asistente de Package Deployer.

    10. Cambie el nombre largo del paquete editando el valor de devolución en la propiedad de GetLongNameOfImport.

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

      El nombre largo del paquete aparecerá en la página siguiente después de seleccionar el paquete para instalar.

  3. Además, la función y variables siguientes están disponibles para el paquete:

    Nombre Tipo Descripción
    CreateProgressItem(String) Función Usado para crear un nuevo artículo del progreso en la interfaz de usuario.
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Función Usado para actualizar el progreso creado por la llamada a CreateProgressItem(String).

    ProgressPanelItemStatus es un enumeración con los siguientes valores:

    En curso = 0
    Finalizado = 1
    Error = 2
    Advertencia = 3
    Desconocido = 4
    RaiseFailEvent(String, Exception) Función Usado para generar error en la importación de estado actual con un mensaje de la excepción.
    IsRoleAssoicatedWithTeam(Guid, Guid) Función Usado para determinar si un rol está asociado con un equipo especificado.
    IsWorkflowActive(Guid) Función Usado para determinar si un flujo de trabajo especificado está activo.
    PackageLog Puntero de clases Es un puntero a la interfaz de registro inicializada para el paquete. Esta interfaz la usa un paquete para registrar mensajes y excepciones al archivo de registro del paquete.
    RootControlDispatcher Property Es una interfaz de distribuidor usada para permitirle que el control genere su propia interfaz de usuario durante la implementación del paquete. Use esta interfaz para encapsular los elementos o comando de la interfaz de usuario. Es importante comprobar si en esta variable hay valores nulos antes de usarla, ya que podría o no establecerse como un valor.
    CrmSvc Propiedad Esto es un puntero a la clase CrmServiceClient que permite que un paquete direccione Dynamics 365 desde el paquete. Use este puntero para ejecutar métodos de SDK y otras acciones en los métodos sustituidos.
    DataImportBypass Property Especificar si el Package Deployer de Dynamics 365 omite todas las operaciones de importación de datos, como importar datos de ejemplo de Dataverse, datos de archivos sin formato y datos exportados desde la herramienta de migración de la configuración. Especifique verdadero o falso. El valor predeterminado es false.
    OverrideDataImportSafetyChecks Propiedad Especifica si el Package Deployer de Dynamics 365 omitirá algunas de las pruebas de seguridad, lo que ayuda a mejorar el rendimiento de la importación. Especifique true o false. El valor predeterminado es false.

    Debe configurar esta propiedad como true solo si la instancia de Dataverse de destino no contiene ningún dato.

  4. Guarda el proyecto. El siguiente paso para compilar el paquete.

Compilar e implementar

Las siguientes secciones describen cómo construir e implementar un paquete.

Compilación

La construcción de su paquete se describe a continuación dependiendo de la herramienta que esté utilizando.

Para compilar un paquete creado con la CLI, puede cargar el archivo .csproj en Visual Studio, pero en su lugar usaremos el comando dotnet y MSBuild. El siguiente ejemplo asume que el directorio de trabajo contiene el archivo *.csproj.

> dotnet publish

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

Opcionalmente, puede ver los detalles del paquete construido.

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

El paquete está constituido por los siguientes archivos de la carpeta <Project>\Bin\Debug.

  • <Nombre del paquete> carpeta :El nombre de la carpeta es el mismo que el que cambió para el nombre de la carpeta de su paquete en paso 2.g de esta sección Agregar código personalizado. Esta carpeta incluye todas las soluciones, datos de configuración, archivos planos y el contenido del paquete.

Nota

Es posible que vea una carpeta .NET (p. ej., net472) que contiene una carpeta pdpublish. Su DLL y otros archivos de proyecto están en esa carpeta pdpublish.

  • <Nombre del paquete> .DLL :El ensamblaje contiene el código personalizado para su paquete. De forma predeterminada, el nombre del ensamblado es el mismo que el nombre de su proyecto.

Implementar

Después de crear un paquete, puede implementarlo en la instancia de Dataverse mediante la herramienta Package Deployer, Windows PowerShell o un comando CLI.

Procedimientos recomendados

A continuación se enumeran algunos consejos de mejores prácticas a seguir cuando se trabaja con paquetes Package Deployer.

Creación de paquetes

Al crear paquetes, los desarrolladores deben:

  • Asegúrese de que los conjuntos de paquetes estén firmados.

Implementación de paquetes

Cuando implementa paquetes, los administradores de Dataverse deben:

  • Insistir en conjuntos de paquetes firmados para que puedas rastrear un ensamblaje hasta su origen.
  • Pruebe el paquete en una instancia de preproducción, preferiblemente una imagen reflejada del instancia de producción, antes de ejecutarlo en un instancia de producción.
  • Copia de seguridad de instancia de producción antes de implementar el paquete.

Vea también

Herramienta de empaquetado de soluciones