Partage via

Extensibilité pour les projets SQL

La bibliothèque .NET Data-tier Application Framework (DacFx) fournit des points d'extensibilité que vous pouvez utiliser pour modifier le comportement des actions de génération et de déploiement pour les projets de bases de données.

  • Build (BuildContributor) : Ce type d’extension est exécuté lorsque le projet SQL est généré après la validation complète du modèle de projet. Un contributeur de génération peut accéder au modèle terminé, ainsi qu'à toutes les propriétés de la tâche de génération et de tous les arguments personnalisés.
  • Déployer (DeploymentPlanModifier) : Ce type d’extension est exécuté lorsque le projet SQL est déployé, dans le cadre du pipeline de déploiement, une fois le plan de déploiement généré, mais avant l’exécution du plan de déploiement. Vous pouvez utiliser un DeploymentPlanModifier pour modifier le plan de déploiement en ajoutant ou en supprimant des étapes. Les contributeurs de déploiement peuvent accéder au plan de déploiement, au résultat de la comparaison, ainsi qu'aux modèles source et cible.
  • Deployer (DeploymentPlanExecutor) : ce type d'extension est exécuté lorsque le plan de déploiement est exécuté et autorise l'accès en lecture seule au plan de déploiement. DeploymentPlanExecutor effectue des actions basées sur le plan de déploiement.

Exemples de scénarios d'extensibilité

Vous pouvez implémenter des contributeurs de génération et de déploiement pour activer les scénarios d'exemple suivant :

  • Générer la documentation d'un schéma lors de la génération du projet : pour prendre en charge ce scénario, vous implémentez un BuildContributor et surchargez la méthode OnExecute pour générer la documentation du schéma. Vous pouvez créer un fichier de cibles qui définit les arguments par défaut qui déterminent si l'extension est exécutée et qui spécifient le nom du fichier de sortie.
  • Créer un rapport de différence lorsqu'un projet SQL est déployé : pour prendre en charge ce scénario, vous implémentez un DeploymentPlanExecutor, qui génère le fichier XML lorsque le projet SQL est déployé.
  • Modifier le plan de déploiement pour changer le moment du transfert des données : pour prendre en charge ce scénario, vous implémentez un DeploymentPlanModifier et l'itérez sur le plan de déploiement. Pour chaque SqlTableMigrationStep dans ce plan, vous examinez le résultat de la comparaison pour déterminer si cette opération doit être effectuée ou ignorée.
  • Copier les fichiers vers le dacpac généré lorsqu'un projet SQL est déployé : pour prendre en charge ce scénario, vous implémentez un contributeur de déploiement et vous remplacez la méthode OnEstablishDeploymentConfiguration pour spécifier quels fichiers sont marqués comme DeploymentExtensionConfiguration par le système de projet. Ces fichiers doivent être copiés dans le dossier de sortie et ajouté dans le dacpac généré. Vous pouvez également modifier le contributeur pour qu'il fusionne plusieurs fichiers en un nouveau fichier qui est copié dans le dossier de sortie et ajouté au manifeste de déploiement. Lors du déploiement, vous pouvez appliquer la méthode OnApplyDeploymentConfiguration pour extraire ces fichiers du dacpac et les préparer pour les utiliser dans la méthode OnExecute.

Un contributeur peut accepter l'entrée au moment de l'exécution sous forme de paires d'arguments nom/valeur. Ces arguments permettent aux utilisateurs finaux, au moment de la génération ou du déploiement, de personnaliser le comportement de votre contributeur. Par exemple, vous pouvez permettre aux utilisateurs de spécifier le nom d'un fichier d'entrée ou de sortie ou de contrôler la sélection d'objets dans le modèle.

Contributeurs au déploiement

Le processus de déploiement des projets SQL est extensible grâce aux contributeurs au déploiement, qui accèdent au plan de déploiement et peuvent soit le modifier (DeploymentPlanModifier), soit implémenter une action basée sur le plan (DeploymentPlanExecutor). Les contributeurs de déploiement peuvent accéder au plan de déploiement, au résultat de la comparaison, ainsi qu'aux modèles source et cible. Avec un DeploymentPlanModifier, vous pouvez utiliser les contributeurs au déploiement pour ajouter ou supprimer des étapes du plan de déploiement, ou pour modifier les étapes du plan de déploiement. DeploymentPlanModifiers sont les contributeurs de déploiement les plus fréquemment utilisés.

Capture d'écran du processus de déploiement DacFx où le plan de déploiement est calculé à partir des différences entre les modèles et modifié par un contributeur au déploiement.

Les contributeurs au déploiement sont réutilisables grâce au paramétrage et peuvent être utilisés dans plusieurs projets. Outre les exemples archivés pour DacExtensions, les membres de la communauté ont créé et partagé leurs propres contributeurs de déploiement réutilisables en tant que projets open source.

Intégration de SqlPackage

SqlPackage est un utilitaire de ligne de commande qui peut être utilisé pour créer et déployer des projets SQL. Lorsqu’ils sont utilisés avec SqlPackage, les contributeurs de déploiement personnalisent le processus de publication et peuvent être spécifiés avec des propriétés sur l’action de publication, telles que /p:AdditionalDeploymentContributors. Les contributeurs de déploiement doivent se trouver dans un emplacement accessible à SqlPackage, tel que le même dossier que l’exécutable SqlPackage ou dans un dossier spécifié dans la propriété /p:AdditionalDeploymentContributorPaths. Pour plus d’informations sur l’action de publication et les propriétés que vous pouvez utiliser pour spécifier des contributeurs de déploiement, consultez Publication SqlPackage.

Les contributeurs de déploiement doivent être créés avec la même version principale de la bibliothèque DacFx que SqlPackage dans les scénarios suivants :

  • À l’aide de la version .NET Framework de SqlPackage, qui nécessite que la version principale corresponde à celle du contributeur de déploiement.
  • Lorsque SqlPackage est mis à jour avec des définitions d’API de bibliothèque DacFx modifiées, qui peuvent passer de la version à la version. Les changements cassants sont limités aux mises à jour de version majeures.

Si un contributeur de déploiement n’est pas généré avec une version compatible de DacFx, l’opération SqlPackage échoue lors de la tentative de chargement de l’extension au moment de l’exécution. Lorsqu’un contributeur de déploiement ne parvient pas à charger dans SqlPackage, un message d’erreur similaire au message suivant s’affiche :

Could not load extensions from file 'D:\a\_work\....dll' because the assembly has dependency to older versions of DacFx. For more information check https://aka.ms/sqlprojects-extensions

Error SQL0: Required contributor with id 'MyCompany.MyExtension' could not be loaded.
System.Management.Automation.RemoteException
Contributor initialization error.

Lors de l'intégration des contribuants de déploiement à SqlPackage dans des pipelines d'automatisation, envisagez de gérer la version de SqlPackage installée sur l'agent de build. La gestion de l’installation de SqlPackage vous permet de vous assurer qu’elle correspond à la version de la bibliothèque DacFx utilisée pour générer vos contributeurs de déploiement. Pour une plus grande flexibilité, utilisez l’outil dotnet Microsoft.SqlPackage au lieu de .NET Framework SqlPackage. Pour plus d’informations sur l’installation de SqlPackage dans votre agent de build à partir du flux de travail si l’environnement ne peut pas être modifié, consultez l’article SqlPackage dans les pipelines de développement .

Contenu connexe

  • Last updated on