Utiliser l’outil SolutionPackager pour compresser et extraire un fichier de solution

  • Article

Cette rubrique s’applique à Dynamics 365 Customer Engagement (on-premises). Pour la version Power Apps de cette rubrique, voir : outil SolutionPackager

SolutionPackager est un outil qui peut décomposer de manière réversible un fichier de solution Dynamics 365 Customer Engagement (on-premises) compressé en plusieurs fichiers XML et autres fichiers, afin qu’ils puissent être facilement gérés par 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 Microsoft.CrmSdk.CoreTools NuGet. Consultez Outils de développement Dataverse pour obtenir des informations de téléchargement.

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.

Argument Description
/action : {Extract|Pack} Obligatoire. Action à effectuer. L’action peut être d’extraire d’un fichier .zip de solution dans un dossier, ou de compresser un dossier dans un fichier .zip.
/zipfile: <chemin d’accès au fichier> Obligatoire. Chemin d’accès et nom d’un fichier .zip de solution. Lors de l’extraction, le fichier doit exister et être lu. Lors de la compression, le fichier est remplacé.
/folder : <chemin d’accès au dossier> Obligatoire. Chemin d’accès à un dossier. Lors de l’extraction, ce dossier est créé et rempli avec les fichiers de composants. Lors de la compression, ce dossier doit exister et contenir les fichiers de composants précédemment extraits.
/type d’emballage : {Unmanaged|Managed|tous les deux} Facultatif. Type de package à traiter. La valeur par défaut est Unmanaged. Cet argument peut être omis la plupart du temps, car le type de package peut être lu à partir du fichier .zip ou des fichiers de composants. Lors de l’extraction, si Both est spécifié, les fichiers .zip de solutions gérées et non gérées doivent être présents et sont traités dans un dossier unique. Lors de la compression, si Both est spécifié, les fichiers .zip de solutions gérées et non gérées sont produits d’un dossier. Pour plus d’informations, voir la section sur l’utilisation des solutions gérées et non gérées plus loin dans cette rubrique.
/allowWrite:{Yes|No} Facultatif. La valeur par défaut est Oui. Cet argument est utilisé uniquement lors d’une extraction. Lorsque /allowWrite:No est spécifié, l’outil exécute toutes les opérations, mais ne peut pas écrire ou supprimer des fichiers. L’opération d’extraction peut être évaluée en toute sécurité sans remplacer ni supprimer de fichiers.
/allowDelete:{Yes|No|Prompt} Facultatif. La valeur par défaut est Invite. Cet argument est utilisé uniquement lors d’une extraction. Lorsque /allowDelete:Yes est spécifié, tous les fichiers présents dans le dossier spécifié par le paramètre /folder et qui ne sont pas attendus sont automatiquement supprimés. Lorsque /allowDelete:No est spécifié, aucune suppression n’est effectuée. Lorsque /allowDelete:Prompt est spécifié, l’utilisateur est invité via la console à autoriser ou à refuser toutes les opérations de suppression. Notez que si /allowWrite:No est spécifié, aucune suppression ne se produit pas même si /allowDelete:Yes est également spécifié.
/clobber Facultatif. Cet argument est utilisé uniquement lors d’une extraction. Lorsque /clobber est spécifié, les fichiers dont l’attribut lecture seule est défini sont remplacés ou supprimés. Lorsqu’il n’est pas spécifié, les fichiers avec l’attribut lecture seule ne sont pas remplacés ou supprimés.
/errorlevel: {Off|Error|Warning|Info|Verbose} Facultatif. La valeur par défaut est Info. Cet argument indique le niveau des informations de journalisation.
/map: <chemin d’accès au fichier> Facultatif. Chemin d’accès et nom d’un fichier .xml contenant les directives de mappage de fichiers. Si cet argument est utilisé pendant une extraction, les fichiers qui sont généralement lus à partir du dossier spécifié par le paramètre /folder sont lus depuis d’autres emplacements, comme spécifié dans le fichier de mappage. Lors d’une opération de compression, les fichiers qui correspondent aux directives ne sont pas écrits.
/nologo Facultatif. Supprimer la bannière au moment de l’exécution.
/log: <chemin d’accès au fichier> Facultatif. Chemin d’accès et nom d’un fichier journal. Si le fichier existe déjà, les nouvelles informations de journalisation sont ajoutées au fichier.
@ <chemin d’accès au fichier> Facultatif. Chemin d’accès et nom d’un fichier contenant les arguments de ligne de commande pour l’outil.
/sourceLoc: <chaîne> Facultatif. Cet argument génère un fichier de ressources modèle, et n’est valide que pour l’extraction.

Les valeurs possibles sont auto ou un code LCID/ISO pour le langage à exporter. Lorsque cet argument est utilisé, les ressources de chaînes des paramètres régionaux indiqués sont extraits en tant que fichier .resx neutre. Si auto ou la forme longue ou courte du commutateur est spécifié, les paramètres régionaux de base ou la solution sont utilisés. Vous pouvez utiliser la forme courte de la commande : /src.
/localize Facultatif. Extrayez ou fusionnez toutes les ressources de chaînes dans les fichiers .resx. Vous pouvez utiliser la forme courte de la commande : /loc.

Utiliser l’argument de commande /map

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

Les fichiers sont intégrés dans un système de création automatisé, tel que des fichiers .xapSilverlight, et les assemblys de plug-in ne sont généralement pas activés dans le contrôle de code source. Les ressources web peuvent être déjà présentes dans le contrôle de code source aux 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 d’un fichier XML contenant les directives de mappage qui indiquent au SolutionPackager de faire correspondre les fichiers selon 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 sélectionnent des fichiers identiques. Les directives répertoriées plus tôt dans le fichier ont priorité sur celles 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 signifier « dans un sous-dossier ». Il peut être utilisé dans la dernière partie d’un chemin d’accès, Par exemple : « c:\folderA\** ».

  • Les caractères génériques de nom de fichier peuvent uniquement être utilisés au format « *.ext » ou « *.* ». Aucun autre critère 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

Le tableau suivant présente des informations détaillées sur le mappage de dossiers.

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

Description
Les chemins d’accès qui correspondent à « folderA » seront changés en « folderB ».

  • La hiérarchie des sous-dossiers 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 fichier-à-fichier

Le tableau suivant présente des informations détaillées sur le mappage fichier-à-fichier.

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

Description
Tout fichier correspondant au paramètre map sera 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 dossier 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.

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

    Notez que dans l’exemple de package 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 de dossier est pris en charge.

    Pour le paramètre to :

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

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

  • 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 sub-folders -->  
       <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é Dynamics 365 Customer Engagement (on-premises) 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, même s’ils peuvent éventuellement permettre 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 l’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 Dynamics 365 Server, 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.

  • Fichier .zip non géré : AnyName.zip
  • Fichier .zip géré : AnyName_managed.zip

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 comprimer les deux, ou de chaque type individuellement, à l’aide du paramètre /PackageType pour spécifier quel type créer. Lorsque vous spécifiez les deux, 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éé.

Résolution des erreurs

Si vous utilisez Visual Studio 2012 pour modifier les fichiers de ressources créés par l’outil de création de package de solution, un message similaire au message suivant peut s’afficher lorsque vous créez un package : “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.” Cette erreur se produit parce que Visual Studio remplace les balises des 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 a été observé uniquement avec l’Éditeur de ressources Visual Studio.

Voir aussi

Outils de solution pour le développement d’équipe
Utiliser le contrôle de code source avec les fichiers de solution
Présentation des solutions