Créer des packages pour l’outil Package Deployer

Package Deployer permet aux administrateurs de déployer des packages sur Microsoft Dataverse instances. Un package Deployer package 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.

Note

Il existe un autre type de package appelé package de plug-in. Ce type de package est destiné aux assemblys dépendants des plug-ins et n’a aucune relation avec les packages Package Deployer.

Prerequisites

  • 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

Pour créer un package Package Deployer, procédez comme suit :

  • Créer un projet Visual Studio ou MSBuild
  • Ajouter les solutions et autres fichiers au projet
  • Mettre à jour les fichiers HTML fournis (facultatif)
  • Spécifier les valeurs de configuration pour le package
  • Définir un code personnalisé pour le package
  • Créer et déployer le package

Cet article décrit ces étapes en détail.

Créer un projet de package

Tout d’abord, créez un projet Visual Studio ou MSBuild pour le package. Pour créer le projet, installez l’une des deux extensions d’outil disponibles sur votre ordinateur de développement. Si vous utilisez Visual Studio Code, installez Microsoft Power Platform CLI. Si vous utilisez Visual Studio 2019 ou version ultérieure, installez les outils Power Platform pour Visual Studio.

Pour savoir comment créer un projet à l’aide de l’extension d’outil souhaitée, sélectionnez l’onglet approprié dans la section suivante. Les deux outils génèrent le projet dans un format similaire.

Exécutez la commande pac package init pour créer le package initial. Pour plus d’informations, consultez le package pac.

pac package init help
pac package init --outputDirectory DeploymentPackage

La sortie CLI inclut les dossiers et fichiers suivants. Le nom DeploymentPackage est utilisé ici comme exemple.

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

Dans le projet créé, recherchez le ImportConfig.xml fichier de configuration dans le PkgAssets dossier et le PackageImportExtension.cs fichier. Vous modifierez ces fichiers comme décrit plus loin dans cet article.

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.

Lorsque vous utilisez l’interface CLI, vous pouvez ajouter des packages externes, des solutions et des références à votre projet de package à l’aide de l’une des sous-commandes d’ajout . Entrez pac package help pour voir la liste des sous-commandes. Ajoutons une solution à notre package.

> 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. Pour obtenir un exemple et une description des éléments et attributs valides à utiliser, consultez Référence ImportConfig.

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 ajouter du code personnalisé, suivez ces instructions :

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

  2. Dans le fichier C#, vous pouvez :

    1. Entrez le code personnalisé à exécuter lorsque le package s'initialise dans la définition de méthode de remplacement de InitializeCustomExtension.

      Utilisez cette méthode 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 spécifie des paramètres d’exécution lors de l’exécution de Package Deployer (à l’aide de la ligne de commande ou de PowerShell), puis traite les informations en conséquence. Si l’utilisateur ne spécifie pas de paramètre d’exécution lors de l’exécution du package, la valeur de la RuntimeSettings propriété est Null.

      public override void InitializeCustomExtension()  
{
  // 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 vérifications de sécurité lors de l’exécution de l’outil Package Deployer pour importer le package. Pour plus d’informations, consultez Déployer des packages à l’aide de 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 override de PreSolutionImport. Utilisez cette méthode 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 s’il faut activer automatiquement les plug-ins et les workflows.

    3. Utilisez la définition de la méthode override de RunSolutionUpgradeMigrationStep pour effectuer une transformation de données ou effectuer une mise à niveau entre deux versions d’une solution. Cette méthode s’exécute 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. Remplacez la méthode OverrideSolutionImportDecision pour renvoyer une énumération UserRequestedImportAction qui contrôle si l’importation d’une solution est ignorée, mise à jour ou mise à niveau (valeur par défaut).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
  string solutionUniqueName, Version organizationVersion,
  Version packageSolutionVersion, Version inboundSolutionVersion,
  Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
{
  return systemSelectedImportAction == 
      ImportAction.Import ? UserRequestedImportAction.ForceUpdate
      : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
      packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
      systemSelectedImportAction);
}

    5. 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. L’outil importe les exemples de données et certains fichiers plats pour les solutions spécifiées dans le ImportConfig.xml fichier avant la fin de l’importation de la solution.

    6. Forcez la langue actuellement sélectionnée pour l’importation de données de configuration à l’aide de la définition de méthode de remplacement de OverrideConfigurationDataFileLanguage. Si l’ID de paramètres régionaux (LCID) spécifié 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. Vous spécifiez le fichier d’importation de données de configuration par défaut dans l’attribut crmmigdataimportfile du ImportConfig.xml fichier.

      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.

    7. Entrez le code personnalisé à exécuter une fois l’importation terminée dans la définition de surcharge de la méthode AfterPrimaryImport. L’outil importe les fichiers plats restants qui n’ont pas été importés précédemment, avant le démarrage de l’importation de solution.

    8. Modifiez le nom par défaut de votre dossier de package en le nom de package souhaité. Pour ce faire, renommez le PkgFolder dossier PkgAssets dans le volet Explorateur de solutions, puis modifiez la valeur de retour sous la GetImportPackageDataFolderName propriété.

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

    9. 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 renvoyée est le nom de votre package qui s’affiche sur la page de sélection de package dans l’Assistant Dynamics 365 Package Deployer.

    10. 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.

    11. 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 avoir sélectionné le package à installer.

  3. Le package a également accès aux fonctions et variables suivantes :

    Nom Type Description
    CreateProgressItem(String) Function Crée un élément de progression dans l’interface utilisateur.
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Met à jour la progression créée par l’appel à CreateProgressItem(String).

    ProgressPanelItemStatus est une énumération avec les valeurs suivantes :

    En cours = 0
    Terminé = 1
    Échec = 2
    Avertissement = 3
    Inconnu = 4
    RaiseFailEvent(String, Exception) Function Échoue à importer l’état actuel avec un message d’exception.
    IsRoleAssociatedWithTeam(Guid, Guid) Function Détermine si un rôle est associé à une équipe spécifiée.
    IsWorkflowActive(Guid) Function Détermine si un flux de travail spécifié est actif.
    PackageLog Pointeur de classe Un pointeur vers l’interface d’enregistrement initialisée du package. Le package utilise cette interface pour consigner les messages et les exceptions dans le fichier journal du package.
    RootControlDispatcher Propriété Interface de dispatcher utilisée par votre contrôle pour 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. Vérifiez que cette variable n’est pas nulle avant de l’utiliser, car elle n’est peut-être pas définie sur une valeur.
    CrmSvc Propriété Pointeur vers la classe CrmServiceClient qui permet à un package d’accéder à Dynamics 365 à partir du package. Utilisez ce pointeur pour exécuter les méthodes du SDK et d’autres actions dans les méthodes remplacées.
    DataImportBypass Propriété Spécifiez si Dynamics 365 Package Deployer ignore toutes les opérations d’importation de données, telles que l’importation d’exemples de données Dataverse, les données de fichier plat et les données exportées à partir de l’outil Migration de configuration. Spécifiez true ou false. La valeur par défaut est false.
    OverrideDataImportSafetyChecks Propriété Spécifiez si Dynamics 365 Package Deployer contourne certaines de ses vérifications de sécurité, ce qui permet d’améliorer les performances d’importation. Spécifiez true ou false. La valeur par défaut est false.

    Définissez 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.

Construire et déployer

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

Build

Les sections suivantes décrivent comment générer votre package, en fonction de l’outil que vous utilisez.

Pour générer un package créé avec l’interface CLI, vous pouvez charger le .csproj fichier dans Visual Studio, mais vous pouvez également utiliser la dotnet commande et MSBuild. L’exemple suivant suppose que le répertoire de travail contient le fichier *.csproj.

> dotnet publish

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

Vous pouvez si vous le souhaitez afficher les détails du package généré.

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

Votre package se compose des fichiers suivants sous le *<Project>*\Bin\Debug dossier :

  • <PackageName> dossier : le nom du dossier correspond au nom que vous avez choisi pour votre dossier de package à l’étape 2.g de la section Ajouter du code personnalisé . Ce dossier contient toutes les solutions, les données de configuration, les fichiers plats et les contenus pour votre package.

Note

Vous pouvez voir un dossier .NET (par exemple, net472) qui contient un dossier pdpublish. Votre DLL et d’autres fichiers projet se trouvent dans ce pdpublish dossier.

  • <PackageName>.dll: l’assemblage contient le code personnalisé de votre paquet. Par défaut, le nom de l’assembly correspond au nom de votre projet.

Deploy

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

  • Pour effectuer le déploiement à l’aide de l’outil Package Deployer, téléchargez d’abord l’outil comme décrit dans les outils de développement Dataverse. Ensuite, suivez les informations détaillées sur le déploiement de packages dans l’article Deploy packages à l’aide de Package Deployer ou Windows PowerShell.

  • Pour effectuer un déploiement à l’aide de l’interface de ligne de commande (CLI), 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 CLI, vous devez d’abord configurer un profil d’authentification et sélectionner une organisation. Pour plus d’informations, consultez pac auth create et 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 :

  • S'assurer que les assemblages de paquets sont signés.

Déploiement de packages

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

  • Exiger des assemblages de paquets signés afin de pouvoir suivre les assemblages depuis leur source.
  • Tester le package sur une instance de préproduction, de préférence une image miroir de l’instance de production, avant de l’exécuter sur une instance de production.
  • Sauvegarder l’instance de production avant de déployer le package.

Voir aussi

Outil d'emballage de solution

  • Dernière mise à jour :