Partager via

Créer des packages pour l’outil Package Deployer

  • Article

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.

Note

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

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 :

  • 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

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.

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

pac package init help
pac package init --outputDirectory DeploymentPackage

Le résultat de la CLI contient les dossiers et fichiers indiqués ci-dessous. Le nom de dossier « DeploymentPackage » est utilisé ici comme exemple.

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

Dans le projet créé, recherchez le fichier de configuration ImportConfig.xml dans le dossier PkgAssets et le fichier PackageImportExtension.cs. 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 de ligne de commande (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 add (ajouter). 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. 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.

Pour créer un package créé avec la CLI, vous pouvez charger le fichier .csproj dans Visual Studio, mais nous allons plutôt utiliser la commande dotnet et MSBuild. L’exemple ci-dessous 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 éventuellement consulter les détails du package créé.

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

Note

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

  • <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