Crear paquetes para la herramienta Package Deployer

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.

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.

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.

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

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.

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

> 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

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.

• <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.

• Para implementar usando la herramienta Package Deployer, primero descargue la herramienta como se describe en herramientas de desarrollo de Dataverse. A continuación, siga la información detallada sobre la implementación de paquetes en el artículo Implementar paquetes usando Package Deployer o Windows PowerShell.

• Para implementar usando el CLI, use el comando pac package deploy.

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

  Nota

  Para implementar un paquete en un entorno de destino mediante la CLI, primero debe configurar un perfil de autenticación y seleccionar una organización. Más información: creación de autenticación pac, selección de organización de pac

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