Créer des packages pour l’outil Package Deployer

Package Deployer permet aux administrateurs de déployer des packages sur des instances Microsoft Dataverse. Un package Package Deployer peut être constitué de l’un ou de plusieurs des éléments suivants :

• Un ou plusieurs fichiers de solution Dataverse.
• Des fichiers plats ou des fichiers de données de configuration exportés à partir de l’outil de migration de la configuration. Pour en savoir plus sur l’outil, consultez Déplacer les données de configuration entre instances et organisations avec l’outil de migration de la configuration.
• Du code personnalisé pouvant s’exécuter avant, pendant ou après le déploiement du package sur l’instance Dataverse.
• Du contenu HTML spécifique au package qui peut s’afficher au début et à la fin du processus de déploiement. Ce contenu peut être utile pour fournir une description des solutions et des fichiers qui sont déployés dans le package.

Conditions préalables

• Assurez-vous que toutes les solutions et les autres fichiers que vous souhaitez inclure dans le package sont prêts.
• Visual Studio 2019 ou version ultérieure, ou Visual Studio Code.

Vue d’ensemble du processus

Exécutez les étapes ci-dessous pour créer un package Package Deployer :

Ces étapes sont décrites en détail dans cet article.

Créer un projet de package

La première étape consiste à créer un projet Visual Studio ou MSBuild pour le package. Pour ce faire, vous devez avoir installé l’une des deux extensions d’outils disponibles sur votre ordinateur de développement. Si vous utilisez Visual Studio Code, installez Microsoft Power Platform CLI. Sinon, si vous utilisez Visual Studio 2019 ou version ultérieure, installez Power Platform Tools pour Visual Studio.

Sélectionnez l’onglet approprié ci-dessous pour savoir comment créer un projet à l’aide de l’extension d’outil souhaitée. Les deux outils génèrent le projet dans un format similaire.

pac package init help
pac package init --outputDirectory DeploymentPackage

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

Ajouter des fichiers au package

Après avoir créé un projet de package, vous pouvez commencer à ajouter des solutions et d’autres fichiers à ce projet.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Configurer le package

Définissez la configuration du package en ajoutant des informations sur votre package dans le fichier ImportConfig.xml dans le projet. Reportez-vous à la Référence ImportConfig pour obtenir un exemple et des descriptions des éléments et attributs valides à utiliser.

Ajouter du code personnalisé

Vous pouvez ajouter du code personnalisé qui s’exécute avant, pendant et après l’importation du package dans un environnement. Pour ce faire, suivez les instructions ci-après.

1. Modifiez le fichier PackageTemplate.cs (ou le fichier PackageImportExtension.cs) dans le dossier racine du projet.

2. Dans le fichier C#, vous pouvez :

   1. Entrer le code personnalisé à exécuter lorsque le package est initialisé dans la définition de la méthode de remplacement de InitializeCustomExtension.

      Cette méthode peut être utilisée pour permettre aux utilisateurs d’utiliser les paramètres d’exécution lors de l’exécution d’un package. En tant que développeur, vous pouvez ajouter le support de tout paramètre d’exécution à votre package en utilisant la propriété RuntimeSettings tant que vous avez le code pour la traiter selon les données saisies par l’utilisateur.

      Par exemple, l’exemple de code suivant active un paramètre d’exécution appelé SkipChecks pour le package qui a deux valeurs possibles : true ou false. L’exemple de code vérifie si l’utilisateur possède les paramètres d’exécution spécifiés en exécutant Package Deployer (à l’aide de la ligne de commande ou de PowerShell), puis traite les informations en conséquence. Si aucun paramètre d’exécution n’est spécifié par l’utilisateur lors de l’exécution du package, la valeur de la propriété RuntimeSettings sera null.

      public override void InitializeCustomExtension()  
      {  
      // Do nothing.  
      
      // Validate the state of the runtime settings object.  
      if (RuntimeSettings != null)  
      {  
      PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
      foreach (var setting in RuntimeSettings)  
      {  
      PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
      }  
      
      // Check to see if skip checks is present.  
      if ( RuntimeSettings.ContainsKey("SkipChecks") )  
      {  
      bool bSkipChecks = false;  
      if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
      OverrideDataImportSafetyChecks = bSkipChecks;  
      }  
      }  
      else  
      PackageLog.Log("Runtime Settings not populated");  
      }  
      

      Ce code permet à l’administrateur d’utiliser la ligne de commande ou l’applet de commande Import-CrmPackage pour spécifier s’il faut ignorer les contrôles de sécurité lors de l’exécution de l’outil Package Deployer pour importer le package. Pour plus d’informations, voir Déployer des packages avec Package Deployer et Windows PowerShell

   2. Entrez le code personnalisé à exécuter avant l’importation des solutions dans la définition de la méthode de remplacement de PreSolutionImport pour spécifier s’il faut conserver ou remplacer les personnalisations lors de la mise à jour de la solution spécifiée dans une instance Dataverse cible, et si vous souhaitez activer automatiquement des plug-ins et des workflows.

   3. Utilisez la définition de la méthode de remplacement de RunSolutionUpgradeMigrationStep pour effectuer la transformation ou la mise à niveau des données entre deux versions d’une solution. Cette méthode est appelée uniquement si la solution que vous importez est déjà présente dans l’instance Dataverse cible.

      Cette fonction requiert les paramètres suivants :

      Paramètre	Description
      solutionName	Nom de la solution
      oldVersion	Numéro de version de l’ancienne solution
      newVersion	Numéro de version de la nouvelle solution
      oldSolutionId	GUID de l’ancienne solution.
      newSolutionId	GUID de la nouvelle solution.

   4. Entrez le code personnalisé à exécuter avant la fin de l’importation de la solution dans la définition de remplacement de la méthode BeforeImportStage. Les exemples de données et certains fichiers plats pour des solutions spécifiées dans le fichier ImportConfig.xml sont importés avant la fin de l’importation de la solution.

   5. Remplacez la langue actuellement sélectionnée pour l’importation des données de configuration à l'aide de la définition de la méthode de remplacement de OverrideConfigurationDataFileLanguage. Si l’ID de paramètres régionaux (LCID) de la langue spécifiée est introuvable dans la liste des langues disponibles dans le package, le fichier de données par défaut est importé.

      Vous spécifiez les langues disponibles pour les données de configuration dans le nœud <cmtdatafiles> dans le fichier ImportConfig.xml. Le fichier d’importation de données de configuration par défaut est spécifié dans l’attribut crmmigdataimportfile dans le fichier ImportConfig.xml.

      Ignorer les contrôles de données (OverrideDataImportSafetyChecks = true) peut être efficace ici si vous êtes certain que l’instance Dataverse cible ne contient aucune donnée.

   6. Entrez le code personnalisé à exécuter après l’importation de la solution dans la définition de remplacement de la méthode AfterPrimaryImport>. Les fichiers plats restants qui n’ont pas été importés précédemment, avant le début de l’importation de la solution, sont importés maintenant.

   7. Modifiez le nom par défaut de votre dossier de package en le nom de package souhaité. Pour cela, renommez le dossier PkgFolder (ou PkgAssets) dans le volet Explorateur de solutions, puis modifiez la valeur renvoyée sous la propriété GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
      {  
      get  
      {  
      // WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
      // Changing this name requires that you also change the correlating name in the Solution Explorer  
      return "PkgFolder";  
      }  
      }  
      

   8. Modifier le nom du package en modifiant la valeur renvoyée sous la propriété GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
      {  
      return "Package Short Name";  
      }  
      

      La valeur retournée est le nom de votre package qui apparaît sur la page de sélection de package dans l'Assistant Dynamics 365 Package Deployer.

   9. Modifier la description du package en modifiant la valeur renvoyée sous la propriété GetImportPackageDescriptionText.

      
      public override string GetImportPackageDescriptionText  
      {  
      get { return "Package Description"; }  
      }  
      
      

      La valeur retournée est la description du package qui apparaît à côté du nom du package sur la page de sélection de package dans l'Assistant Package Deployer.

   10. Modifier le nom long du package en modifiant la valeur renvoyée sous la propriété GetLongNameOfImport.

       
       public override string GetLongNameOfImport  
       {  
       get { return "Package Long Name"; }  
       }  
       
       

       Le nom long du package apparaît sur la page suivante après que vous ayez sélectionné le package à installer.

3. En outre, la fonctionnalité et les variables suivantes sont disponibles pour le package :

   Nom	Type	Description
   CreateProgressItem(String)	Fonction	Utilisé pour créer un élément de progression dans l’interface utilisateur.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Fonction	Utilisé pour mettre à jour la progression créée par l’appel à CreateProgressItem(String). ProgressPanelItemStatus est un enum avec les valeurs suivantes : En cours = 0 Terminé = 1 Échec = 2 Avertissement = 3 Inconnu = 4
   RaiseFailEvent(String, Exception)	Fonction	Utilisé pour faire échouer l’importation d’état actuel avec un message d’exception.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Fonction	Utilisé pour déterminer si un rôle est associé à une équipe spécifiée.
   IsWorkflowActive(Guid)	Fonction	Utilisé pour déterminer si un workflow spécifié est actif.
   PackageLog	Pointeur de classe	Un pointeur vers l’interface d’enregistrement initialisée du package. Cette interface est utilisée par un package pour enregistrer des messages et des exceptions dans le fichier journal du package.
   RootControlDispatcher	Property	Une interface de distributeur utilisée pour permettre à votre contrôle d’afficher sa propre interface utilisateur pendant le déploiement du package. Utilisez cette interface pour inclure dans un wrapper tous les éléments ou commandes de l’interface utilisateur. Il est important de vérifier si cette variable comporte des valeurs Null avant de l’utiliser, car il se peut qu'elle ne contienne pas de valeur.
   CrmSvc	Property	Un pointeur vers la classe CrmServiceClient qui permet à un package de traiter Dynamics 365 depuis l’intérieur du package. Utilisez ce pointeur pour exécuter les méthodes du SDK et d’autres actions dans les méthodes remplacées.
   DataImportBypass	Property	Indiquez si Dynamics 365 Package Deployer doit ignorer toutes les opérations d’importation de données telles que l’importation d’exemples de données Dataverse, les données du fichier plat, et les données exportées depuis l’outil de migration de la configuration. Choisissez Vrai ou Faux. La valeur par défaut est false.
   OverrideDataImportSafetyChecks	Property	Indiquez si Dynamics 365 Package Deployer doit ignorer certains de ses contrôles de sécurité, afin d'améliorer les performances d'importation. Spécifiez true ou false. La valeur par défaut est false. Vous devez définir cette propriété sur true uniquement si l'instance Dataverse cible ne contient aucune donnée.

4. Enregistrez votre projet. L’étape suivante consiste à créer le package.

Créer et déployer

Les sections suivantes décrivent comment créer et déployer un package.

Créer

La création de votre package est décrite ci-dessous en fonction de l’outil que vous utilisez.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Votre package est composé des fichiers suivants sous le dossier <Project>\Bin\Debug.

• <Nom du package> dossier : Le nom du dossier est le même que celui que vous avez modifié pour le nom du dossier de votre package dans étape 2.g de cette section Ajouter un code personnalisé. Ce dossier contient toutes les solutions, les données de configuration, les fichiers plats et les contenus pour votre package.

• <Nom du package> .DLL : L’assembly contient le code personnalisé de votre package. Par défaut, le nom de l’assembly est le même que celui de votre projet.

Déployer

Après avoir créé un package, vous pouvez le déployer sur l’instance Dataverse à l’aide de l’outil Package Deployer, Windows PowerShell ou une commande CLI.

• Pour déployer à l’aide de l’outil Package Deployer, téléchargez d’abord l’outil comme décrit dans Outils de développement Dataverse. Suivez ensuite les informations détaillées sur le déploiement des packages dans l’article Déployer des packages avec Package Deployer ou Windows PowerShell.

• Pour déployer à l’aide de l’interface de ligne de commande, utilisez la commande pac package deploy.

  > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
  

  Note

  Pour déployer un package dans un environnement cible à l’aide de l’interface de ligne de commande, vous devez d’abord configurer un profil d’authentification et sélectionner une organisation. Pour plus d’informations : pac auth create, pac org select

Bonnes pratiques

Vous trouverez ci-dessous quelques conseils de bonnes pratiques à suivre lorsque vous travaillez avec des packages Package Deployer.

Création de packages

Lors de la création de packages, les développeurs doivent :

• Assurez-vous que les assemblages de packages sont signés.

Déploiement de packages

Lors du déploiement de packages, les administrateurs Dataverse doivent :

• Insistez sur les assemblages de packages signés afin que vous puissiez suivre un assemblage jusqu’à sa source.
• Tester le package sur une instance de préproduction, de préférence une image miroir du instance de production, avant de l’exécuter sur un instance de production.
• Soutenez le instance de production avant de déployer le package.

Voir aussi

Outil de création de package de solutions