Outil SolutionPackager

SolutionPackager est un outil qui peut décomposer réversiblement un fichier de solution compressé Microsoft Dataverse en plusieurs fichiers XML et d’autres fichiers. Vous pouvez ensuite gérer facilement ces fichiers en utilisant un système de contrôle de code source. Les sections suivantes vous expliquent comment exécuter l’outil et comment l’utiliser avec les solutions gérées et non gérées.

Où trouver l’outil SolutionPackager

L’outil SolutionPackager est distribué dans le cadre de la Microsoft. CrmSdk.CoreTools package NuGet. Pour installer le programme, suivez ces étapes.

1. Téléchargez le package NuGet.
2. Renommez l’extension du nom de fichier du package de .nupkg en .zip.
3. Extrayez le contenu du fichier (zip) compressé.

Recherchez l’exécutable SolutionPackager.exe dans le dossier <extracted-folder-name>/contents/bin/coretools. Exécutez le programme à partir du dossier coretools ou ajoutez ce dossier à votre PATH.

Arguments de ligne de commande SolutionPackager

SolutionPackager est un outil en ligne de commande qui peut être appelé avec les paramètres identifiés dans le tableau suivant.

Formats de fichier de contrôle de code source

SolutionPackager prend en charge deux dispositions de dossiers lors de l’extraction et de l’empaquetage des solutions.

Format XML (hérité)

Format d’origine. Les métadonnées de solution sont stockées dans Other\Solution.xml et Other\Customizations.xml, et tous les fichiers de composant sont extraits dans une hiérarchie de dossiers plats en même temps que ces fichiers. Ce format est le format par défaut lors de l’extraction d’un .zip fichier sans configuration supplémentaire.

Format de contrôle de code source YAML

Introduit en même temps que l’intégration de Dataverse Git, ce format stocke les métadonnées de solution sous forme de fichiers YAML distribués dans une hiérarchie de dossiers structurée. Il s'agit du format écrit lorsque vous validez des solutions à l'aide de l'intégration Git native dans Power Apps.

Avantages par rapport au format XML

• Produit des différences plus propres et plus lisibles par composant dans le contrôle de code source
• Prend en charge plusieurs solutions dans un dossier de référentiel unique
• Les fichiers de l'application Canvas .msapp et les flux modernes ne sont pris en charge que dans ce format
• Le remappage du nom de type du plug-in est activé par défaut

Structure de dossiers requise

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

Informations supplémentaires : Informations de référence sur le format de contrôle de code source YAML de solution

Mettre en forme des règles de détection automatique

Empaquetage d’un dossier de format YAML

Les commandes suivantes packent un dossier de format YAML.

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

Empaquetage à partir d’un dossier de multiples solutions

Les commandes suivantes packent une solution spécifiée dans un dossier multi-solution.

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

Utiliser l’argument de commande /map

La discussion suivante illustre l’utilisation de l’argument /map de l’outil SolutionPackager.

Les fichiers qui sont créés dans un système de construction automatisé, tels que les fichiers .xap Silverlight et les assemblées de plug-in, ne sont généralement pas ajoutés au contrôle de version. Les ressources web peuvent être déjà présentes dans le contrôle de code source à des emplacements qui ne sont pas directement compatibles avec l’outil SolutionPackager. En incluant le paramètre /map, l’outil SolutionPackager peut être défini pour lire et empaqueter les fichiers à partir d’autres emplacements et non à partir du dossier Extract comme il le fait généralement. Le paramètre /map doit spécifier le nom et le chemin d’accès à un fichier XML contenant les directives de mappage. Ces directives indiquent à SolutionPackager de faire correspondre les fichiers par leur nom et leur chemin d’accès, et d’indiquer l’emplacement secondaire où rechercher le fichier correspondant. Les informations suivantes s’appliquent à toutes les directives équitablement.

• Plusieurs directives peuvent être répertoriées, y compris celles qui correspondent à des fichiers identiques. Les directives répertoriées plus tôt dans le fichier ont priorité sur les directives répertoriées plus bas.

• Si un fichier correspond à une directive, il doit être présent dans au moins un autre emplacement. Si aucune autre solution de correspondance n’est détectée, SolutionPackager émet une erreur.

• Les chemins d’accès au dossier et aux fichiers peuvent être absolus ou relatifs. Les chemins d’accès relatifs sont toujours évalués à partir du dossier spécifié par le paramètre /folder.

• Les variables d’environnement peuvent être spécifiées à l’aide d’une syntaxe %variable%.

• Un caractère générique de dossier « ** » peut être utilisé pour signifier « dans n’importe quel sous-dossier ». Elle ne peut être utilisée que comme partie finale d’un chemin d’accès, par exemple : « c :\folderA\** ».

• Les caractères génériques de nom de fichier peuvent être utilisés uniquement dans les formulaires « *.ext » ou « *.* ». Aucun autre modèle n’est pris en charge.

  Les trois types de mappages de directives sont décrits ici, avec un exemple qui montre comment les utiliser.

Mappage de dossiers

Les informations suivantes fournissent des détails sur le mappage de dossiers.

Format XML

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

Description

Les chemins d’accès aux fichiers correspondant à « folderA » sont basculés vers « folderB ».

• La hiérarchie des sous-dossiers sous chacun doit correspondre exactement.

• Les caractères génériques de dossiers ne sont pas pris en charge.

• Aucun nom de fichier ne peut être spécifié.

  Exemples

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

Mappage de fichier à fichier

Les informations suivantes fournissent plus de détails sur le mappage fichier-à-fichier.

Format XML

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

Description

Tout fichier correspondant au paramètre map est lu à partir du nom et du chemin d’accès spécifiés dans le paramètre to.

Pour le paramètre map :

• Un nom de fichier doit être spécifié. Le chemin est facultatif. Si aucun chemin d’accès n’est spécifié, les fichiers de n’importe quel dossier peuvent être mis en correspondance.

• Les caractères génériques de noms de fichier ne sont pas pris en charge.

• Le caractère générique de type pour les répertoires est pris en charge.

  Pour le paramètre to :

• Un nom de fichier et un chemin d’accès doivent être spécifiés.

• Le nom de fichier peut être différent du nom dans le paramètre map.

• Les caractères génériques de noms de fichier ne sont pas pris en charge.

• Le caractère générique de dossier est pris en charge.

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

Dans l'exemple de paquet NuGet ci-dessus, cr886_PluginPackageTest.nupkg n’est pas écrasé si le fichier existe déjà à l’emplacement spécifié.

Mappage fichier-à-chemin d’accès

Le tableau suivant présente des informations détaillées sur le mappage fichier-à-chemin d’accès.

Format XML

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

Description

Tout fichier correspondant au paramètre map est lu à partir du chemin d’accès spécifié dans le paramètre to.

Pour le paramètre map :

• Un nom de fichier doit être spécifié. Le chemin est facultatif. Si aucun chemin d’accès n’est spécifié, les fichiers de n’importe quel dossier peuvent être mis en correspondance.

• Les caractères génériques de noms de fichier sont pris en charge.

• Le caractère générique pour les dossiers est pris en charge.

Pour le paramètre to :

• Un chemin d’accès doit être spécifié.

• Le joker pour les dossiers est supporté.

• Un nom de fichier ne doit pas être spécifié.

  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 de mappage

L’exemple de code XML suivant illustre un fichier de mappage complet qui permet à l’outil SolutionPackager de lire une ressource web et les deux assemblys générés par défaut à partir d’un projet Kit de ressources pour les développeurs nommé 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>  

Solutions gérées et non gérées

Un fichier compressé Dataverse de solution (.zip) peut être exporté dans l’un des deux types indiqués ici.

Solution gérée
Solution terminée prête à être importée dans une organisation. Une fois importés, les composants ne peuvent pas être ajoutés ou supprimés, bien qu’ils puissent éventuellement autoriser une personnalisation supplémentaire. Ceci est recommandé lorsque le développement de la solution est terminée.

Solution non gérée
Une solution ouverte sans restrictions sur ce qui peut être ajouté, supprimé ou modifié. Ceci est recommandé lors du développement d’une solution.

Le format d’un fichier de solution compressé est différent selon le type de solution, gérée ou non gérée. SolutionPackager peut traiter les fichiers de solution compressés des deux types. Toutefois, l’outil ne peut pas convertir un type en un autre. La seule façon de convertir des fichiers de solution en un autre type, par exemple de non gérée à gérée, est d’importer le fichier .zip de solution non gérée sur un serveur Dataverse, puis d’exporter la solution comme solution gérée.

SolutionPackager peut traiter des fichiers .zip de solution non gérée et gérée sous forme d’ensemble combiné via le paramètre /PackageType:Both. Pour effectuer cette opération, il est nécessaire d’exporter votre solution deux fois dans chaque type, en nommant les fichiers .zip comme suit.

L’outil supposera la présence du fichier zip géré dans le même dossier que le fichier non géré et extraira les deux fichiers dans un même dossier, en conservant les différences lors de la présence de composants gérés et non gérés.

Lorsqu’une solution a été extraite comme solution non gérée et gérée, il est possible, à partir de ce même dossier, de packager les deux, ou chaque type individuellement, à l’aide du paramètre /PackageType pour spécifier quel type créer. Lorsque vous spécifiez les deux fichiers, deux fichiers .zip sont créés avec la convention d’affectation de noms indiquée ci-dessus. Si le paramètre /PackageType est manquant lors de la compression d’un dossier double géré et non géré, par défaut, un seul fichier .zip non géré est créé.

Dépannage

Message affiché lors de l’utilisation de Visual Studio pour modifier les fichiers de ressources

Si vous utilisez Visual Studio pour modifier les fichiers de ressources créés par le Solution Packager, vous pouvez recevoir un message lorsque vous repackez similaire à ceci : "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." Cela se produit car Visual Studio remplace les balises de métadonnées du fichier de ressources par des balises de données.

Solution de contournement

1. Ouvrez le fichier de ressources dans votre éditeur de texte préféré et mettez à jour les balises suivantes :

   <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. Modifiez le nom de nœud de <data> à <metadata>.

   Par exemple, cette chaîne :

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

   Devient :

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

   Cela permet à l’outil de création de package de solution de lire et d’importer le fichier de ressources. Ce problème n’a été observé que lors de l’utilisation de l’éditeur de ressources Visual Studio.

Erreur : « Impossible de trouver le fichier requis ...\Other\Customizations.xml» avec un dossier YAML

Cette erreur s’affiche lorsque vous exécutez SolutionPackager (ou pac solution pack) sur un dossier qui contient des fichiers YAML tels que solution.yml, mais ces fichiers sont placés à la racine du dossier plutôt qu’à l’intérieur du sous-dossier requis solutions/<SolutionUniqueName>/ .

Cause : L’outil détecte le format de contrôle de code source YAML en recherchant un solutions/ sous-dossier contenant des *solution.yml fichiers. Lorsque ce répertoire est absent, l’outil revient silencieusement au format XML (hérité) et attend Other\Customizations.xml. Le message d’erreur résultant fait référence à un fichier XML et ne mentionne pas YAML, ce qui est trompeur.

Correction: Réorganisez le dossier pour que les fichiers de manifeste YAML soient placés dans les chemins d’accès corrects :

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

Si vous avez obtenu le dossier à partir d’une validation d’intégration Git ou pac solution clone, la structure des dossiers doit déjà être correcte. Un dossier qui contient uniquement les fichiers YAML de niveau supérieur sans le solutions/ sous-répertoire représente une extraction incomplète et ne peut pas être emballé directement.

Avertissement : le composant déclaré dans rootcomponents.yml n’a pas de fichiers sources

Cet avertissement s’affiche lorsqu’un composant, tel qu’une application canevas, est répertorié, rootcomponents.yml mais qu’aucun fichier source correspondant n’existe dans le dossier de composant attendu (par exemple). canvasapps/<schema-name>/

Effet: L’outil réussit toujours (code de sortie 0) et produit un fichier valide .zip , mais le composant déclaré est omis de la solution empaquetée.

Cause : Le dossier a été généré par un extrait partiel, ou les fichiers sources du composant n’ont pas été inclus dans le référentiel. Par exemple, seuls les fichiers manifestes de solution ont été validés et non l’application canevas elle-même.

Correctif: Vérifiez que tous les composants déclarés dans rootcomponents.yml ont des fichiers sources correspondants présents dans le dossier. Pour les applications de canevas, le .msapp fichier doit exister sous canvasapps/<schema-name>/. Si des fichiers sont manquants, réexportez la solution complète à partir de Dataverse et décompressez-la à nouveau, ou utilisez-la pac solution clone pour obtenir un extrait complet.

Voir aussi

• Utiliser le contrôle de code source avec les fichiers de solution
• Concepts de la solution