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 du package NuGet Microsoft.CrmSdk.CoreTools . 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. Vous pouvez l’appeler à l’aide des paramètres décrits 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. L’outil stocke les métadonnées de la solution dans Other\Solution.xml et Other\Customizations.xml. L’outil extrait tous les fichiers de composant dans une hiérarchie de dossiers plats à côté de ces fichiers. Ce format est le format par défaut lorsque vous extrayez un .zip fichier sans plus de configuration.

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 version.
• Prend en charge plusieurs solutions dans un dossier de dépôt unique.
• Les fichiers Canvas app .msapp et les flux modernes ne sont pris en charge que dans ce format.
• Le remapping de nom de type de 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]/

En savoir plus : Référence du format YAML de contrôle de code source des solutions

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

Utilisation de l’argument de commande /map

La discussion suivante détaille l’utilisation de l’argument /map dans l’outil SolutionPackager.

Les fichiers créés dans un système de génération automatisé, tels que .xap les fichiers Silverlight et les assemblys de plug-in, ne sont généralement pas archivés dans le contrôle de code source. Vous pouvez déjà disposer de ressources web dans le contrôle de code source dans des emplacements qui ne sont pas directement compatibles avec l’outil SolutionPackager. En incluant le paramètre /map, vous pouvez diriger l’outil SolutionPackager pour lire et empaqueter ces fichiers à partir d’autres emplacements au lieu de depuis l’intérieur du dossier Extract. 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 également à toutes les directives.

• Vous pouvez répertorier plusieurs directives, 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 se trouver 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.

• Spécifiez des variables d’environnement à l’aide de la syntaxe %variable%.

• Utilisez un caractère générique ** de dossier pour signifier « dans n’importe quel sous-dossier ». Vous ne pouvez l’utiliser que comme partie finale d’un chemin d’accès, par exemple : c:\folderA\**.

• Utilisez des caractères génériques de nom de fichier uniquement sous les formes *.ext ou *.*. Aucun autre modèle n’est pris en charge.

  La section suivante décrit les trois types de mappages de directive, ainsi qu’un exemple qui vous montre comment les utiliser.

Mappage de dossiers

La section suivante fournit des informations détaillées sur le mappage de dossiers.

format XML

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

Description

Les chemins d’accès aux fichiers correspondant à « folderA » passent à « folderB ».

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

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

• Vous ne pouvez pas spécifier de noms de fichiers.

  Examples

  <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 map paramètre lit à partir du nom et du chemin spécifiés dans le to paramètre.

Pour le paramètre map :

• Spécifiez un nom de fichier. Le chemin d’accès est facultatif. Si vous ne spécifiez pas de chemin d’accès, le mappage peut correspondre aux fichiers d’un dossier quelconque.

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

• Prend en charge le caractère générique du dossier.

  Pour le paramètre to :

• Spécifiez un nom de fichier et un chemin d’accès.

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

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

• Prend en charge le caractère générique de dossier.

Examples

  <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 package NuGet précédent, cr886_PluginPackageTest.nupkg n’est pas remplacé si le fichier existe déjà à l’emplacement spécifié.

Correspondance fichier/chemin

La section suivante fournit des informations détaillées sur le mappage de fichier à chemin.

format XML

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

Description

Le map paramètre spécifie le fichier à mettre en correspondance et le to paramètre spécifie le chemin d’accès à partir duquel lire.

Pour le paramètre map :

• Spécifiez un nom de fichier. Le chemin d’accès est facultatif. Si vous ne spécifiez pas de chemin d’accès, le mappage peut correspondre à des fichiers de n’importe quel dossier.

• Prend en charge les caractères génériques de nom de fichier.

• Prend en charge le caractère générique du dossier.

Pour le paramètre to :

• Spécifiez un chemin d’accès.

• Prend en charge les caractères génériques de dossier.

• Ne spécifiez pas de nom de fichier.

  Examples

  <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 montre un fichier de mappage complet qui permet à l’outil SolutionPackager de lire n’importe quelle ressource Web et les deux assemblys générés par défaut à partir d’un projet Developer Toolkit 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

Vous pouvez exporter un fichier compressé Dataverse (.zip) en tant que solution gérée ou non gérée.

Solution gérée
Solution terminée prête à être importée dans une organisation. Une fois importé, vous ne pouvez pas ajouter ou supprimer des composants, bien que vous puissiez éventuellement autoriser une personnalisation supplémentaire. Utilisez ce type lorsque le développement de la solution est terminé.

Solution non gérée
Une solution ouverte sans restriction sur ce que vous pouvez ajouter, supprimer ou modifier. Utilisez ce type pendant le développement d’une solution.

Le format d’un fichier de solution compressé diffère en fonction de son type, géré ou non géré. 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, comme de non géré à managé, consiste à importer le fichier .zip de la solution non managée dans un serveur Dataverse, puis à exporter la solution en tant que solution managée.

SolutionPackager peut traiter des fichiers de solution non gérées et gérées .zip en tant qu’ensemble combiné à l’aide du paramètre /PackageType:Both. Pour effectuer cette opération, vous devez exporter votre solution deux fois dans chacun des types. Nommez les fichiers .zip comme suit :

L’outil suppose que le fichier zip managé se trouve dans le même dossier que le fichier non managé. Il extrait les deux fichiers dans un dossier unique et conserve les différences là où des composants managés et non managés existent.

Après avoir extrait une solution en tant que solution non gérée et gérée, vous pouvez empaqueter les deux types ou chaque type individuellement à partir de ce dossier unique. Utilisez le paramètre /PackageType pour spécifier le type à créer. Lorsque vous spécifiez les deux fichiers, l’outil produit deux fichiers .zip à l’aide de la convention de nommage précédente. Si vous n’incluez pas le paramètre /PackageType lors de l’emballage à partir d’un dossier double managé et non managé, la valeur par défaut consiste à produire un fichier .zip non managé unique.

Résolution des problèmes

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 Solution Packager, un message peut s'afficher lorsque vous recréez le package, similaire à celui-ci : "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." Ce message s'affiche, 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 favori, puis recherchez 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>  
   
   

   Modifications apportées à :

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

   Cette modification permet à Solution Packager de lire et d’importer le fichier de ressources. Ce problème se produit uniquement lorsque vous utilisez 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 que vous placez ces fichiers à 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 fait référence à un fichier XML et ne mentionne pas YAML, ce qui peut prêter à confusion.

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 de pac solution clone, la structure du dossier est déjà 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 solution