Compartir a través de

Herramienta SolutionPackager

SolutionPackager es una herramienta que puede descomponer de forma reversible un archivo de solución comprimido Microsoft Dataverse en varios archivos XML y otros archivos. Luego puede administrar estos archivos con facilidad con un sistema de control de origen. Las secciones siguientes muestran cómo ejecutar la herramienta y cómo usar la herramienta con soluciones administradas y no administradas.

Importante

La herramienta SolutionPackager ya no es la forma recomendada de desempaquetar y empaquetar soluciones. Las funcionalidades de la herramienta SolutionPackager se incorporan a la CLI de Power Platform. El pac solution comando tiene muchos verbos, como unpack, packclone, y sync que incorporan las mismas funcionalidades subyacentes de la herramienta SolutionPackager.

Dónde encontrar la herramienta de SolutionPackager

La herramienta SolutionPackager se distribuye como parte del Microsoft. CrmSdk.CoreTools paquete NuGet. Siga estos pasos para instalar el programa.

  1. Descargue el paquete NuGet.
  2. Cambie el nombre de la extensión del nombre de archivo del paquete de .nupkg a .zip.
  3. Extraiga el contenido del archivo comprimido (zip).

Busque el ejecutable SolutionPackager.exe en la carpeta <nombre-carpeta-extraída>/contents/bin/coretools. Ejecute el programa desde la carpeta coretools o agregue esa carpeta a su RUTA.

Argumentos de la línea de comandos para SolutionPackager

SolutionPackager es una herramienta de línea de comandos que se puede invocar con los parámetros identificados en la tabla siguiente.

Argumento Descripción
/Acción: {Extraer|Empaquetar} Obligatorio. La acción para realizar. Una acción puede ser extraer un archivo .zip de solución en una carpeta, o comprimir una carpeta en un archivo .zip.
/zipfile: <ruta del archivo> Obligatorio. La ruta y el nombre de un archivo .zip de solución. Para extraer, el archivo debe existir y ser de lectura. Al comprimir, se reemplaza el archivo.
/folder: <ruta de carpeta> Obligatorio. La ruta a una carpeta. Al extraer, esta carpeta se crea y se rellena con los archivos componentes. Al comprimir, esta carpeta debe existir y contener los archivos componentes extraídos anteriormente.
/packagetype: {No administrado|Gestionado|Ambos} Opcional. Tipo de paquete para procesar. El valor predeterminado es Unmanaged. Este argumento se puede omitir en la mayoría de las ocasiones porque el tipo de paquete se puede leer desde dentro del archivo .zip o de los archivos componentes. Cuando se extrae y se especifica Both, los archivos .zip de solución administrada y no administrada deben estar presentes y procesarse en una sola carpeta. Cuando se comprime y se especifica Both, los archivos .zip de solución administrada y no administrada se crean desde una carpeta. Para obtener más información, vea la sección sobre cómo trabajar con soluciones administradas y no administradas más adelante en este artículo.
/allowWrite:{Yes|No} Opcional. El valor predeterminado es Sí. Este argumento solo se usa durante una extracción. Cuando se especifica /allowWrite:No, la herramienta realiza todas las operaciones pero se evita que escriba o elimine cualquier archivo. La operación de extracción se puede evaluar con seguridad sin sobrescribir o eliminar ningún archivo existente.
/allowDelete:{Yes|No|Prompt} Opcional. El valor predeterminado es Prompt. Este argumento solo se usa durante una extracción. Cuando se especifica /allowDelete:Yes, los archivos presentes en la carpeta especificados por el parámetro /folder y que no se esperan, se eliminan de forma automática. Cuando se especifica /allowDelete:No, no se produce ninguna eliminación. Cuando se especifica /allowDelete:Prompt, se pide al usuario, a través de la consola, que permita o deniegue todas las operaciones de eliminación. Si se especifica /allowWrite:No, no se producen eliminaciones incluso si también se especifica /allowDelete:Yes.
/clobber Opcional. Este argumento solo se usa durante una extracción. Cuando se especifica /clobber, los archivos que tienen el atributo de solo lectura establecido se sobrescriben o eliminan. Cuando no se especifica, los archivos con el atributo de solo lectura no se sobrescriben ni eliminan.
/errorlevel: {Off|Error|Warning|Info|Verbose} Opcional. El valor predeterminado es Info. Este argumento indica el nivel de información del registro para el resultado.
/map: <ruta de archivo> Opcional. La ruta y el nombre de un archivo .xml que contiene directivas de asignación de archivos. Cuando se usa durante una extracción, los archivos suelen leer desde dentro de la carpeta especificada por el parámetro /folder y se leen desde ubicaciones alternativas tal como se especifica en el archivo de asignación. Durante la operación de compresión, los archivos que coinciden con las directivas no se escriben.
/nologo Opcional. Suprimir pancartas en tiempo de ejecución.
/log: <ruta de archivo> Opcional. Una ruta y un nombre a un archivo de registro. Si ya existe el archivo, se agrega nueva información de registro al archivo.
@ <ruta del archivo> Opcional. Una ruta y un nombre de archivo que contiene los argumentos de la línea de comandos de la herramienta.
/sourceLoc: <cadena> Opcional. Este argumento genera un archivo de recursos de la plantilla, y solo es válido en el extracto.

Los valores posibles son auto o código de LCID/ISO para el idioma que desea exportar. Cuando se usa este argumento, se extraen los recursos de la cadena de configuración regional determinada como archivo de .resx neutro. Si auto o la forma larga o corta del cambio se especifica, se utilizan el local base o la solución. Puede usar la forma corta de comando: /src.
/localize Opcional. Extraiga o combine todos los recursos de cadena en los archivos de .resx. Puede usar la forma corta del comando: /loc. La opción de localización admite componentes compartidos para archivos .resx. Más información: Usar recursos web RESX
/SolutionName: <name> Opcional. Nombre único de la solución que se va a empaquetar o extraer cuando la carpeta de origen contiene varias soluciones en solutions/*/solution.yml. Se requiere cuando se detecta más de una solución. Solo se aplica al formato de control de código fuente de YAML. Puede usar la forma abreviada del comando: /sn.
/remapPluginTypeNames Opcional. Cuando se especifica, los nombres de tipo completos del complemento, se reasignan en función de los ensamblados incluidos en la solución. Habilitado de forma predeterminada en el formato de control de código fuente de YAML. Puede usar la forma abreviada del comando: /fp.

Formatos de archivo de control de código fuente

SolutionPackager admite dos diseños de carpeta al extraer y empaquetar soluciones.

Formato XML (heredado)

Formato original. Los metadatos de la solución se almacenan en Other\Solution.xml y Other\Customizations.xml, y todos los archivos de componentes se extraen en una jerarquía de carpetas planas junto con esos archivos. Este formato es el formato predeterminado al extraer un .zip archivo sin más configuración.

Formato de control de código fuente DE YAML

Introducido junto con la integración de Git de Dataverse, este formato almacena los metadatos de la solución como archivos YAML distribuidos en una jerarquía de carpetas estructuradas. Es el formato utilizado al registrar soluciones mediante la integración nativa de Git en Power Apps.

Ventajas sobre el formato XML

  • Genera diferencias más limpias y más legibles por componente en el control de código fuente.
  • Admite varias soluciones en una sola carpeta de repositorio
  • Los archivos de la aplicación de Canvas .msapp y los 'flujos modernos' solo se admiten en este formato.
  • La reasignación de nombres de tipo de complemento está activada de forma predeterminada

Estructura de carpetas requerida

<rootFolder>/
├── solutions/
│   └── <SolutionUniqueName>/
│       ├── solution.yml              (solution metadata)
│       ├── solutioncomponents.yml    (paths to all component files)
│       ├── rootcomponents.yml        (root-level components)
│       └── missingdependencies.yml   (dependency info)
├── publishers/
│   └── <PublisherUniqueName>/
│       └── publisher.yml             (publisher definition)
├── entities/                         (entity components, if present)
├── workflows/                        (classic workflows, if present)
├── modernflows/                      (Power Automate cloud flows, if present)
├── canvasapps/                       (canvas app .msapp files, if present)
└── [other component folders]/

Importante

El formato YAML se detecta automáticamente por la presencia de una solutions/ subcarpeta que contiene *solution.yml archivos. Si los archivos de manifiesto de YAML (solution.yml, solutioncomponents.yml, etc.) se colocan en la raíz de la carpeta en lugar de en solutions/<SolutionUniqueName>/, la herramienta no detecta el formato YAML. La herramienta vuelve a utilizar la ruta de acceso XML e informa de un error engañoso sobre la falta de Customizations.xml. Consulte Solución de problemas para obtener información sobre cómo corregir este problema.

Más información: Referencia del formato de control de código fuente para YAML de la solución

Reglas de auto-detección de formato

Condición Formato usado
solutions/*/solution.yml encontrado: exactamente una solución Formato YAML, donde el nombre de la solución se deduce de la carpeta
solutions/*/solution.yml encontrado: varias soluciones Formato YAML, donde se requiere el /SolutionName argumento
No hay un solutions/ subdirectorio presente Formato XML (heredado)

Empaquetado de una carpeta de formato YAML

El siguiente comando empaqueta una carpeta de formato YAML.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Empaquetado desde una carpeta de múltiples soluciones

El siguiente comando empaqueta una solución especificada en una carpeta de varias soluciones.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

Use el argumento del comando de /map

La siguiente discusión detalla el uso del argumento /map a la herramienta SolutionPackager.

Los archivos que están integrados en un sistema automatizado de compilación, como archivos .xap de Silverlight y ensamblados de complementos, no se comprueban normalmente en el control de origen. Los recursos web pueden estar presentes en control de origen en ubicaciones que no son directamente compatibles con la herramienta SolutionPackager. Al incluir el parámetro /map, se puede hacer que la herramienta SolutionPackager lea y comprima dichos archivos de ubicaciones alternativas y no desde la carpeta Extract como se haría habitualmente. El parámetro /map debe especificar el nombre y la ruta a un archivo XML que contiene directivas de mapeo. Esas directivas indican al SolutionPackager que haga coincidir los archivos por su nombre y ruta, e indican la ubicación alternativa para encontrar el archivo coincidente. La siguiente información se aplica a todas las directivas de igual forma.

  • Se pueden enumerar varias directivas incluyendo las que coinciden con archivos idénticos. Las directivas que se enumeran al principio del archivo tienen prioridad sobre las que se enumeran después.

  • Si un archivo se hace coincidir con una directiva, se debe encontrar en al menos una ubicación alternativa. Si no se encuentran alternativas que coincidan, el SolutionPackager emite un error.

  • Las rutas de la carpeta y el archivo pueden ser absolutas o relativas. Las rutas relativas se evalúan siempre desde la carpeta especificada por el parámetro /folder.

  • Las variables de entorno se pueden especificar utilizando una sintaxis %variable%.

  • Se puede utilizar el comodín de carpeta "**" para indicar "en cualquier subcarpeta". Solo se puede usar como parte final de una ruta de acceso, por ejemplo: "c:\folderA\**".

  • Los caracteres comodín de nombre de archivo solo se pueden usar en las formas "*.ext" o "*.*". No se admite ningún otro patrón.

    Aquí se describen los tres tipos de asignaciones de las directivas, junto con un ejemplo que muestra cómo puede usarlos.

Asignación de carpeta

La siguiente información proporciona datos detallados sobre la asignación de carpetas.

Formato XML

<Folder map="folderA" to="folderB" />

Descripción

Las rutas de acceso de archivo que coinciden con "folderA" se cambian a "folderB".

  • La jerarquía de subcarpetas bajo cada una debe coincidir exactamente.

  • No se admiten los comodines de carpeta.

  • No se pueden especificar nombres de archivos.

    Ejemplos

    <Folder map="folderA" to="folderB" />  
<Folder map="folderA\folderB" to="..\..\folderC\" />  
<Folder map="WebResources\subFolder" to="%base%\WebResources" />

Asignación de archivo a archivo

A continuación se muestra más información detallada sobre asignación de archivo a archivo.

Formato XML

<FileToFile map="path\filename.ext" to="path\filename.ext" />

Descripción

Cualquier archivo que coincida con el parámetro de map se lee desde el nombre y la ruta especificados en el parámetro de to.

Para el parámetro de map:

  • Se debe especificar un archivo. La ruta es opcional. Si no se especifica una ruta, deben hacerse coincidir los archivos de cualquier carpeta.

  • No se admiten los comodines de nombre de archivo.

  • Se admite el comodín de la carpeta.

    Para el parámetro de to:

  • Se debe especificar un nombre de archivo y una ruta.

  • El nombre de archivo puede ser distinto del nombre del parámetro de map.

  • No se admiten los comodines de nombre de archivo.

  • Se admite el comodín de la carpeta.

Ejemplos

  <FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />  
  <FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />  
  <FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />  

  <FileToFile
    map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
    to="myplg\bin\Debug\myplg.1.0.0.nupkg" />

En el ejemplo de paquete NuGet anterior, cr886_PluginPackageTest.nupkg no se sobrescribe si el archivo ya existe en la ubicación especificada.

Asignación de archivo a ruta

A continuación se muestra información detallada sobre asignación de archivo a ruta.

Formato XML

<FileToPath map="path\filename.ext" to="path" />

Descripción

Cualquier archivo que coincida con el parámetro de map se leerá desde la ruta especificada en el parámetro de to.

Para el parámetro de map:

  • Se debe especificar un archivo. La ruta es opcional. Si no se especifica una ruta, deben hacerse coincidir los archivos de cualquier carpeta.

  • Se admiten los comodines de nombre de archivo.

  • Se admite el comodín de la carpeta.

Para el parámetro de to:

  • Se debe especificar una ruta.

  • Se admite el comodín de la carpeta.

  • No se debe especificar un nombre de archivo.

    Ejemplos

  <FileToPath map="assembly.dll" to="c:\path\folder" />  
  <FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />  
  <FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />  
  <FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />

Asignación de ejemplo

El siguiente ejemplo de código XML muestra un archivo de asignación completo lo que permite que la herramienta SolutionPackager lea cualquier recurso web y los dos ensamblados generados predeterminados desde un proyecto de Developer Toolkit denominado CRMDevTookitSample.

<?xml version="1.0" encoding="utf-8"?>  
<Mapping>  
       <!-- Match specific named files to an alternate folder -->  
       <FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />  
       <FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />  
       <!-- Match any file in and under WebResources to an alternate set of subfolders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>

Soluciones administradas y no administradas

Un archivo comprimido de solución de aplicaciones (.zip) de Dataverse puede exportar en uno de entre dos tipos, como se indica a continuación.

Solución administrada
Una solución completada lista para importarse en una organización. Una vez importados, los componentes no se pueden agregar ni quitar, aunque opcionalmente pueden permitir una mayor personalización. Esto se recomienda cuando el desarrollo de la solución esté completo.

Solución no administrada
Una solución abierta sin restricciones sobre qué se puede agregar, quitar o modificar. Esto se recomienda durante el desarrollo de una solución.

El formato de un archivo comprimido de solución será diferente en función del tipo, ya sea administrado o no administrado. El SolutionPackager puede procesar archivos de solución comprimidos de cualquier tipo. Sin embargo, la herramienta no puede convertir un tipo a otro. La única forma de convertir los archivos de solución a un tipo diferente, por ejemplo de no administrada a administrada, es importando el archivo de solución no administrada .zip a un servidor de Dataverse y después exportando la solución como una solución administrada.

SolutionPackager puede procesar archivos .zip de soluciones administradas y no administradas como un conjunto combinado mediante el parámetro /PackageType:Both. Para realizar esta operación, es necesario exportar la solución dos veces en cada tipo, nombrando los archivos .zip de la forma siguiente.

Archivo de .zip no administrado: AnyName.zip

Archivo de .zip administrado: AnyName_managed.zip

La herramienta asumirá la presencia del archivo .zip administrado en la misma carpeta que el archivo no administrado y extraerá ambos archivos en una sola carpeta que mantiene las diferencias en caso de componentes administrados y no administrados.

Una vez que una solución se ha extraído como no administrada y administrada, es posible comprimir ambas desde esa única carpeta o cada tipo de forma individual, utilizando el parámetro /PackageType para especificar qué tipo crear. Al especificar ambos archivos, se crearán dos archivos .zip mediante la convención de nomenclatura anterior. Si el parámetro /PackageType se pierde al comprimir desde una carpeta dual administrada y no administrada, de forma predeterminada se produce un solo archivo .zip no administrado.

Solución de problemas

Mensaje que se muestra al usar Visual Studio para editar archivos de recursos

Si usa Visual Studio para editar los fsiles de recursos creados por el empaquetador de soluciones, puede recibir un mensaje al volver a empaquetar de forma similar a esta: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Esto sucede porque Visual Studio reemplaza las etiquetas de metadatos del archivo de recursos por etiquetas de datos.

Solución alternativa

  1. Abra el archivo de recursos en el editor de texto que prefiera y encuentre las siguientes etiquetas:

    <data name="Source LCID" xml:space="preserve">  
<data name="Source file" xml:space="preserve">  
<data name="Source package type" xml:space="preserve">  
<data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">

  2. Cambie el nombre del nodo de <data> a <metadata>.

    Por ejemplo, esta cadena:

    <data name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</data>

    Cambia a:

    <metadata name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</metadata>

    Esto permite que el empaquetador de la solución lea e importe el archivo de recursos. Este problema solo se ha observado al usar el editor de recursos de Visual Studio.

Error: "No se encuentra el archivo necesario ...\Other\Customizations.xml" con una carpeta YAML

Este error aparece cuando se ejecuta SolutionPackager (o pac solution pack) en una carpeta que contiene archivos YAML como solution.yml, pero esos archivos se colocan en la raíz de la carpeta en lugar de dentro de la subcarpeta necesaria solutions/<SolutionUniqueName>/ .

Causa: La herramienta detecta el formato de control de código fuente de YAML buscando una solutions/ subcarpeta que contiene *solution.yml archivos. Cuando ese directorio está ausente, la herramienta vuelve de forma silenciosa al formato XML (heredado) y espera Other\Customizations.xml. El mensaje de error resultante hace referencia a un archivo XML y no menciona YAML, que es engañoso.

Corrección: Reorganice la carpeta para que los archivos de manifiesto de YAML estén en las rutas de acceso correctas:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

Si obtuvo la carpeta de una confirmación de integración de Git o pac solution clone, la estructura de carpetas ya debería ser correcta. Una carpeta que solo contiene los archivos YAML de nivel superior sin el solutions/ subdirectorio representa una extracción incompleta y no se puede empaquetar directamente.

Advertencia: el componente declarado en rootcomponents.yml no tiene archivos de origen

Esta advertencia aparece cuando un componente, como una aplicación de lienzo, aparece en rootcomponents.yml pero no existen archivos de origen correspondientes en la carpeta de componentes esperada (por ejemplo, canvasapps/<schema-name>/).

Efecto: La herramienta sigue funcionando correctamente (código de salida 0) y genera un archivo válido .zip , pero el componente declarado se omite de la solución empaquetada.

Causa: La carpeta se generó mediante una extracción parcial o los archivos de origen del componente no se incluyeron en el repositorio. Por ejemplo, solo se pusieron en el control de versiones los archivos de manifiesto de la solución y no la propia aplicación Canvas.

Corrección: Asegúrese de que todos los componentes declarados en rootcomponents.yml tienen los archivos de origen correspondientes presentes en la carpeta . En el caso de las aplicaciones de lienzo, el archivo .msapp debe existir en canvasapps/<schema-name>/. Si faltan archivos, vuelva a exportar la solución completa de Dataverse y desempaquetarla de nuevo o use pac solution clone para obtener una extracción completa.

Vea también

  • Last updated on