Eina Empaquetador de solucions

SolutionPackager és una eina que pot descompondre reversiblement un fitxer de solució comprimida de Microsoft Dataverse en múltiples fitxers XML i altres fitxers. A continuació, podeu gestionar fàcilment aquests fitxers mitjançant un sistema de control de codi font. A les seccions següents es mostra com executar l'eina i com utilitzar l'eina amb solucions administrades i no administrades.

Important

L'eina SolutionPackager ja no és la manera recomanada de desempaquetar i empaquetar solucions. Les capacitats de l'eina SolutionPackager s'incorporen a la CLI de Power Platform. La pac solution comanda té molts verbs, incloent-hi unpack, pack, clone, i sync que incorporen les mateixes capacitats subjacents de l'eina SolutionPackager.

On trobar l'eina Empaquetador de solucions

L'eina SolutionPackager es distribueix com a part del Microsoft. CrmSdk.CoreTools Paquet NuGet. Per instal·lar el programa, seguiu aquests passos.

  1. Descarrega el NuGet paquet.
  2. Canvieu el nom de l'extensió del nom de fitxer del paquet de .nupkg a .zip.
  3. Extreu el contingut del fitxer comprimit (zip).

Cerqueu l'executable SolutionPackager.exe a la carpeta <extracted-folder-name>/contents/bin/coretools. Executeu el programa des de la carpeta coretools o afegiu aquesta carpeta al vostre PATH.

Arguments de la línia d'ordres de l'Empaquetador de solucions

SolutionPackager és una eina de línia d'ordres. Pots invocar-lo utilitzant els paràmetres descrits a la taula següent.

Argument Descripció
/acció: {Extracte|Pack} Obligatori. L'acció que voleu dur a terme. L'acció pot ser o bé extreure un fitxer .zip de solució en una carpeta o empaquetar una carpeta en un fitxer .zip.
/zipfile: <camí del fitxer> Obligatori. El camí i el nom d'un fitxer .zip de solució. En l'extreure, el fitxer ha d'existir i ser llegible. En empaquetar, el fitxer se substitueix.
/folder: <camí de la carpeta> Obligatori. El camí a una carpeta. Quan extraieu, es crearà i s'omplirà aquesta carpeta amb fitxers de components. Quan s'empaqueta, aquesta carpeta ja ha d'existir i contenir fitxers de components extrets prèviament.
/packagetype: {No gestionat|Gestionat|Tots dos} Opcional. Tipus de paquet per processar. El valor per defecte és Unmanaged. S'omet aquest argument en la majoria de casos perquè l'eina pot llegir el tipus de paquet des de dins del fitxer .zip o fitxers de components. Quan s'extreu i s'especifica Both, els fitxers .zip de solució administrada i no administrada han d'estar presents i es processen en una única carpeta. Quan s'especifica l'empaquetament i Ambdós, els fitxers de solució gestionada i no administrada .zip es produeixen des d'una carpeta. Per obtenir més informació, vegeu la secció sobre com treballar amb solucions administrades i no administrades més endavant en aquest article.
/allowWrite:{Yes|No} Opcional. Sí es el valor per defecte. Utilitza aquest argument només durant una extracció. Quan especifiques /allowWrite:No, l'eina realitza totes les operacions però no escriu ni elimina cap fitxer. Pots avaluar l'operació d'extracció sense sobreescriure ni esborrar cap fitxer existent.
/allowDelete:{Yes|No|Prompt} Opcional. El valor per defecte és Prompt. Utilitza aquest argument només durant una extracció. Quan especifiques /allowDelete:Yes, l'eina elimina automàticament qualsevol fitxer present a la carpeta especificat pel paràmetre /folder que no s'esperi. Quan especifiques /allowDelete:No, l'eina no elimina cap fitxer. Quan especifiques /allowDelete:Prompt, a través de la consola es demana a l'usuari que permeti o denegi totes les operacions d'eliminació. Si especifiques /allowWrite:No, l'eina no elimina cap fitxer encara que /allowDelete:Yes també estigui especificat.
/clobber Opcional. Utilitza aquest argument només durant una extracció. Quan especifiques /clobber, l'eina sobreescriu o elimina fitxers que tenen l'atribut de només lectura configurat. Quan no s'especifica, l'eina no sobreescriu ni elimina fitxers amb l'atribut de només lectura.
/errorlevel: {Desactivat|Error|Avís |Informació|Verbose} Opcional. Info és el valor per defecte. Aquest argument indica el nivell d'informació de registre a la sortida.
/map: <camí del fitxer> Opcional. El camí i el nom d'un fitxer .xml que conté les directives d'assignació de fitxers. Quan s'utilitza durant una extracció, l'eina llegeix fitxers que normalment es llegeixen des de dins de la carpeta especificada pel paràmetre /folder des de llocs alternatius segons s'especifica al fitxer de mapatge. Durant una operació de pack, l'eina no escriu fitxers que coincideixin amb les directrius.
/nologo Opcional. Suprimeix el bàner en temps d'execució.
/log: <camí del fitxer> Opcional. El camí i el nom d'un fitxer de registre. Si el fitxer ja existeix, la nova informació del registre s'afegirà al fitxer.
Camí del fitxer @ <> Opcional. El camí i el nom d'un fitxer que conté arguments de la línia d'ordres per a l'eina.
/sourceLoc: <cadena> Opcional. Aquest argument genera un fitxer de recursos de plantilla i només és vàlid a l'extracció.

Els valors possibles són auto o un codi LCID/ISO per a la llengua que voleu exportar. Quan utilitzes aquest argument, l'eina extreu els recursos de cadena de la localització donada com un fitxer .resx neutral. Si especifiques auto o només la forma llarga o curta de l'interruptor, s'utilitza la ubicació base o la solució. Podeu utilitzar la forma curta de l'ordre: /src.
/localize Opcional. Extraieu o fusioneu tots els recursos de cadena en fitxers .resx. Podeu utilitzar la forma curta de l'ordre: /loc. L'opció de localització admet components compartits per als fitxers .resx. Per a més informació, vegeu Ús dels recursos web de RESX.
/SolutionName: <nom> Opcional. El nom únic de la solució a empaquetar o extreure quan la carpeta font conté múltiples solucions sota solutions/*/solution.yml. És necessari quan es detecten més d'una solució. Només s'aplica al format de control de versions YAML. Pots utilitzar la forma abreujada de l'ordre: /sn.
/remapPluginTypeNames Opcional. Quan s'especifica, l'eina reassigna els noms dels tipus totalment qualificats dels connectors basant-se en els conjunts inclosos a la solució. Activat per defecte en el format de control de versions YAML. Pots utilitzar la forma abreujada de l'ordre: /fp.

Formats de fitxer de control de versions

SolutionPackager admet la disposició de dues carpetes a l'hora d'extreure i empaquetar solucions.

Format XML (llegat)

El format original. L'eina emmagatzema les metadades de la solució a Other\Solution.xml i Other\Customizations.xml. L'eina extreu tots els fitxers components en una jerarquia plana de carpetes al costat d'aquests fitxers. Aquest format és el per defecte quan extreu un .zip fitxer sense més configuració.

Format de control de versions YAML

Introduït juntament amb la integració amb Dataverse Git, aquest format emmagatzema les metadades de la solució com a fitxers YAML distribuïts en una jerarquia estructurada de carpetes. És el format que s'escriu quan fas commit de solucions utilitzant la integració nativa de Git a Power Apps.

Avantatges respecte al format XML

  • Produeix diferencials per component més nets i llegibles en el control de versió.
  • Suporta múltiples solucions en una sola carpeta de repositori.
  • Els fitxers d'aplicacions .msapp Canvas i els fluxos moderns només són compatibles en aquest format.
  • La reassignació del nom del tipus de connector està activada per defecte.

Estructura de carpetes 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]/

Important

La presència d'una solutions/ subcarpeta que conté *solution.yml fitxers indica el format YAML. Si col·loques els teus fitxers de manifest YAML (solution.yml, solutioncomponents.yml, i així successivament) a l'arrel de la carpeta en lloc de sota solutions/<SolutionUniqueName>/, l'eina no detecta el format YAML. L'eina torna a la ruta XML i informa d'un error enganyós sobre una manca Customizations.xmlde fitxers . Consulta Resolució de problemes per a informació sobre com solucionar aquest problema.

Més informació: Referència del format de control de versions YAML de la solució

Regles de detecció automàtica de format

Condició Format utilitzat
solutions/*/solution.yml trobada — exactament una solució YAML, on el nom de la solució s'infereix de la carpeta
solutions/*/solution.yml trobada — múltiples solucions format YAML, on es requereix l'argument /SolutionName
No hi ha solutions/ cap subdirectori present Format XML (llegat)

Empaquetant una carpeta en format YAML

La següent ordre empaqueta una carpeta en format YAML.

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

Empaquetament des d'una carpeta multi-solució

La següent ordre empaqueta una solució especificada en una carpeta multi-solució.

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

Utilitzar l'argument de l'ordre /map

La discussió següent inclou detalls de l'ús de l'argument /map a l'eina Empaquetador de solucions.

Els fitxers que es construeixen en un sistema de compilació automatitzat, com ara .xap fitxers Silverlight i assemblatges de connectors, normalment no es registren al control de versiments. Potser ja tens recursos web en control de versions en ubicacions que no són directament compatibles amb l'eina SolutionPackager. Incloent el paràmetre /map, pots dirigir l'eina SolutionPackager perquè llegeixi i empaqueti aquests fitxers des de llocs alternatius en lloc de des de dins la carpeta Extract. El paràmetre /map ha d'especificar el nom i el camí d'un fitxer XML que contingui directives d'assignació. Aquestes directives indiquen al SolutionPackager que faci coincidir els fitxers pel seu nom i camí i indiqui la ubicació alternativa per trobar el fitxer coincident. La següent informació s'aplica a totes les directives de manera equitativa.

  • Pots llistar múltiples directrius, incloent-hi aquelles que coincideixen amb fitxers idèntics. Les directives enumerades al principi del fitxer tenen prioritat sobre les directives enumerades més endavant.

  • Si un fitxer coincideix amb qualsevol directiva, s'ha de trobar en almenys una ubicació alternativa. Si no es troba cap alternativa coincident, el SolutionPackager emet un error.

  • Les rutes de carpetes i fitxers poden ser absolutes o relatives. Els camins relatius són sempre avaluats des de la carpeta especificada pel paràmetre /folder.

  • Especifica les variables d'entorn utilitzant una %variable% sintaxi.

  • Utilitza un comodí ** de carpeta per significar "en qualsevol subcarpeta". Només el pots utilitzar com a part final d'un camí, per exemple: c:\folderA\**.

  • Utilitza les targetes comodins del nom del fitxer només als formularis *.ext o *.*. No s'admet cap altre patró.

    La secció següent descriu els tres tipus de mapatges directius, juntament amb un exemple que mostra com utilitzar-los.

Assignació de carpetes

La secció següent proporciona informació detallada sobre el mapatge de carpetes.

XML Format

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

Descripció

Els camins de fitxer que coincideixen amb "carpetaA" canvien a "folderB".

  • La jerarquia de subcarpetes sota cada carpeta ha de coincidir exactament.

  • No s'admeten comodins de carpeta.

  • No pots especificar noms d'arxiu.

    Exemples

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

Mapeig de fitxer a fitxer

La informació següent proporciona més detalls sobre l'assignació de fitxer a fitxer.

XML Format

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

Descripció

Qualsevol fitxer que coincideixi amb el map paràmetre es llegeix del nom i el camí especificats al to paràmetre.

Per al paràmetre map:

  • Especifica un nom de fitxer. El camí és opcional. Si no especifiques un camí, la correspondència pot coincidir amb fitxers de qualsevol carpeta.

  • No s'admeten comodins de nom de fitxer.

  • Suporta el comodí de carpeta.

    Per al paràmetre to:

  • Especifica un nom de fitxer i una ruta.

  • El nom del fitxer pot diferir del nom del map paràmetre.

  • No s'admeten comodins de nom de fitxer.

  • Suporta el comodí de carpeta.

Exemples

  <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 l'exemple anterior del paquet NuGet, cr886_PluginPackageTest.nupkg no s'escriu si el fitxer ja existeix a la ubicació especificada.

Mapeig entre fitxer i ruta

La secció següent proporciona informació detallada sobre el mapeig de fitxer a camí.

XML Format

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

Descripció

El map paràmetre especifica el fitxer que coincideix, i el to paràmetre especifica el camí des d'on llegir.

Per al paràmetre map:

  • Especifica un nom de fitxer. El camí és opcional. Si no especifiques un camí, la correspondència pot coincidir amb fitxers de qualsevol carpeta.

  • Suporta comodins de nom d'arxiu.

  • Suporta el comodí de carpeta.

Per al paràmetre to:

  • Especifica un camí.

  • Suporta el comodí de carpeta.

  • No especifiquis un nom d'arxiu.

    Exemples

  <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" />

Exemple d'assignació

L'exemple següent de codi XML mostra un fitxer d'assignació complet que permet a l'eina Empaquetador de solucions llegir qualsevol recurs web i els dos assemblatges generats per defecte d'un projecte de kit d'eines de desenvolupador anomenat 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>

Solucions administrades i no administrades

Pots exportar un fitxer de solució comprimida de Dataverse (.zip) com a solució gestionada o no gestionada.

Solució gestionada
Una solució acabada i llesta per importar a una organització. Un cop importat, no pots afegir ni treure components, tot i que opcionalment pots permetre una personalització addicional. Utilitza aquest tipus quan el desenvolupament de la solució estigui complet.

Solució no administrada
Una solució oberta sense restriccions sobre què pots afegir, eliminar o modificar. Utilitza aquest tipus durant el desenvolupament d'una solució.

El format d'un fitxer de solució comprimida varia segons el seu tipus, ja sigui gestionat o no. L'Empaquetador de solucions pot processar fitxers de solució comprimits de qualsevol tipus. Tanmateix, l'eina no pot convertir un tipus en un altre. L'única manera de convertir fitxers de solució a un altre tipus, com ara de no gestionat a gestionat, és important el fitxer .zip de la solució no gestionada a un servidor Dataverse i després exportant la solució com a solució gestionada.

El SolutionPackager pot processar fitxers de solucions no gestionades i gestionades .zip com un conjunt combinat utilitzant el /PackageType:Both paràmetre. Per fer aquesta operació, has d'exportar la teva solució dues vegades com a cada tipus. Anomena els fitxers .zip de la manera següent:

Fitxer .zip no administrat: AnyName.zip

Fitxer .zip administrat: AnyName_managed.zip

L'eina assumeix que el fitxer zip gestionat està a la mateixa carpeta que el fitxer no gestionat. Extreu ambdós fitxers en una sola carpeta i preserva les diferències on existeixen components gestionats i no gestionats.

Després d'extreure una solució tant com a no gestionada com a gestionada, pots empaquetar ambdós tipus o cada tipus individualment d'aquesta sola carpeta. Utilitza el /PackageType paràmetre per especificar quin tipus crear. Quan especifiquis ambdós fitxers, l'eina produeix dos fitxers .zip utilitzant la convenció de nomenclatura anterior. Si no inclous el /PackageType paràmetre quan empaquetes des d'una carpeta dual gestionada i una no gestionada, el predeterminat és produir un únic fitxer de .zip no gestionat.

Solució de problemes

Missatge mostrat quan s'utilitza Visual Studio per editar fitxers de recursos

Si utilitzes Visual Studio per editar fitxers de recursos creats pel paquetador de la solució, potser veuràs un missatge similar quan tornes a empaquetar"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.": Aquest missatge apareix perquè Visual Studio substitueix les etiquetes de metadades del fitxer de recursos per etiquetes de dades.

Solució alternativa

  1. Obre el fitxer de recursos al teu editor de text preferit i després localitza i actualitza les següents etiquetes:

    <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. Canvieu el nom del node de <data> a <metadata>.

    Per exemple, aquesta cadena:

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

    Canvia a:

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

    Aquest canvi permet que l'empaquetador de la solució llegeixi i importi el fitxer de recurs. Aquest problema només es produeix quan utilitzes l'editor de recursos de Visual Studio.

Error: "No es pot trobar el fitxer requerit ...\Other\Customizations.xml" amb una carpeta YAML

Aquest error apareix quan executes SolutionPackager (o pac solution pack) en una carpeta que conté fitxers YAML com solution.yml, però col·loques aquests fitxers a l'arrel de la carpeta en lloc de dins la subcarpeta requerida solutions/<SolutionUniqueName>/ .

Causa: L'eina detecta el format de control de versions YAML buscant una solutions/ subcarpeta que contingui *solution.yml arxius. Quan aquest directori no hi és, l'eina torna silenciosament al format XML (heretat) i espera Other\Customizations.xml. El missatge d'error fa referència a un fitxer XML i no menciona YAML, cosa que pot ser confusa.

Correcció: Reorganitza la carpeta perquè els fitxers de manifest YAML estiguin sota els camins correctes:

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

Si has obtingut la carpeta d'un commit d'integració Git o pac solution clone, l'estructura de carpetes ja és correcta. Una carpeta que només conté els fitxers YAML de primer nivell sense el solutions/ subdirectori representa una extracció incompleta i no es pot empaquetar directament.

Avís: component declarat a rootcomponents.yml no té fitxers font

Aquest avís apareix quan un component, com una aplicació canvas, apareix però rootcomponents.yml no existeixen fitxers font corresponents a la carpeta de components esperats (per exemple, canvasapps/<schema-name>/).

Efecte: L'eina encara té èxit (codi de sortida 0) i produeix un fitxer vàlid .zip , però el component declarat s'omet de la solució empaquetada.

Causa: La carpeta es produïa mitjançant una extracció parcial, o bé els fitxers font del component no s'incloïen al repositori. Per exemple, només es van comprometre els fitxers manifest de la solució i no l'aplicació canvas en si.

Correcció: Assegureu-vos que tots els components declarats a rootcomponents.yml tinguin els fitxers font corresponents presents a la carpeta. Per a aplicacions canvas, el .msapp fitxer ha d'existir sota canvasapps/<schema-name>/. Si falta algun fitxer, reexporta la solució completa des de Dataverse i desempaqueta-la de nou, o utilitza-la pac solution clone per obtenir una extracció completa.

Consulteu també

  • Darrera actualització el