SqlPackage dans les pipelines de développement

SqlPackage est un utilitaire en ligne de commande qui permet d’automatiser plusieurs tâches de développement de bases de données. Il peut être intégré dans des pipelines CI/CD.

Remarque

L’utilisation d’une installation autonome de SqlPackage pour l’automatisation des pipelines est recommandée sur l’utilisation des exécutables SqlPackage groupés avec d’autres applications, notamment SQL Server Management Studio ou Visual Studio. L’installation autonome de SqlPackage est mise à jour plus fréquemment et n’est pas liée à la cadence de publication d’autres applications.

Si SqlPackage est installé en tant qu’outil dotnet global (recommandé), vous pouvez l’appeler dans le pipeline avec simplement sqlpackage à partir de n’importe quel répertoire. Si SqlPackage est installé en tant qu’exécutable autonome, vous devez spécifier le chemin complet de l’exécutable dans le pipeline. Sur Windows, l’installation autonome de SqlPackage est disponible sur le chemin d’accès C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Dans les environnements Windows et Linux, si vous téléchargez l'.zip SqlPackage autonome pour .NET, vous pouvez extraire l’exécutable à un emplacement de votre choix.

Environnements virtuels gérés

Les environnements virtuels utilisés pour les exécuteurs hébergés GitHub Actions et les images de machine virtuelle Azure Pipelines sont gérés dans le référentiel GitHub runner-images. SqlPackage est inclus dans plusieurs environnements, notamment windows-latest et ubuntu-22.04 n’est plus inclus par défaut dans ubuntu-24.04 et ubuntu-latest. Les mises à jour des images dans runner-images sont effectuées dans les semaines qui suivent la publication d’une nouvelle version de SqlPackage.

Dans un environnement virtuel managé, vous allez installer SqlPackage au moment de l’exécution dans le pipeline. L’installation est effectuée en tant qu’étape distincte dans Azure Pipelines et GitHub Actions et ajoute un court délai à chaque exécution de pipeline pendant que l’installation se produit. Pour installer SqlPackage au moment de l’exécution, ajoutez une étape au pipeline qui utilise l’interface CLI dotnet pour installer SqlPackage en tant qu’outil global. Cette étape doit être exécutée avant toutes les actions SqlPackage dans le pipeline.

dotnet tool install --global Microsoft.SqlPackage

Vous devrez peut-être effectuer une étape d’installation .NET dans le pipeline avant d’installer SqlPackage, indiqué par un message d’erreur indiquant que .NET est introuvable. Utilisez une action intégrée pour la configurer, telle que la tâche UseDotNet dans Azure Pipelines ou l’action setup-dotnet dans GitHub Actions.

Si vous le souhaitez, vous pouvez spécifier une version de SqlPackage à installer en ajoutant --version <version> à la commande d’installation ou en utilisant l’indicateur --prerelease pour installer une préversion.

Exemple : étapes d’installation de SqlPackage dans Azure DevOps Pipelines

Dans Azure DevOps Pipelines, vous pouvez utiliser la tâche UseDotNet pour installer le Kit de développement logiciel (SDK) .NET, puis installer SqlPackage en tant qu’outil global. Si vous utilisez un agent Windows fourni par Microsoft, SqlPackage est déjà installé dans C:\Program Files\Microsoft SQL Server\170\DAC\bin. Si vous utilisez un agent auto-hébergé, vous pouvez également installer SqlPackage sur l’environnement hôte et ignorer cette étape dans le pipeline.

- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '8.x'
- script: dotnet tool install --global Microsoft.SqlPackage --version <version>
  displayName: 'Install specific version of SqlPackage'

Exemple : Étapes d’installation de SqlPackage dans GitHub Actions

Dans GitHub Actions, vous pouvez utiliser l’action setup-dotnet pour installer le Kit de développement logiciel (SDK) .NET, puis installer SqlPackage en tant qu’outil global. Si vous utilisez un exécuteur Windows fourni par GitHub, SqlPackage est déjà installé dans C:\Program Files\Microsoft SQL Server\170\DAC\bin. Si vous utilisez un exécuteur auto-hébergé, vous pouvez également installer SqlPackage sur l’environnement hôte et ignorer cette étape dans le flux de travail.

- name: Setup .NET
  uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '8.x'
- name: Install SqlPackage
  run: dotnet tool install --global Microsoft.SqlPackage --version <version>

Vérifier la version de SqlPackage

Lors de la résolution des problèmes, il est important de connaître la version de SqlPackage utilisée. Pour capturer cette information, vous pouvez ajouter une étape au pipeline afin d’exécuter SqlPackage avec le paramètre /version. Des exemples sont fournis dans cet article en fonction des environnements managés Azure DevOps et GitHub, les environnements auto-hébergés peuvent avoir différents chemins d’installation pour le répertoire de travail.

Azure Pipelines

Dans un pipeline Azure, le mot clé script retourne le numéro de version sqlPackage.

- script: SqlPackage /version
  workingDirectory: 'C:\Program Files\Microsoft SQL Server\170\DAC\bin\'
  displayName: 'get sqlpackage version'

GitHub Actions

Dans un flux de travail GitHub Action, le mot clé run retourne le numéro de version sqlPackage.

- name: get sqlpackage version
  working-directory: 'C:\Program Files\Microsoft SQL Server\170\DAC\bin\'
  run: ./SqlPackage /version

Mettre à jour SqlPackage sur l’agent de pipeline

Dans certains scénarios, la version actuelle de SqlPackage installée dans l’environnement de pipeline peut être insuffisante. Si l’environnement ne peut pas être modifié directement, une étape supplémentaire peut être utilisée pour installer une version plus récente de SqlPackage pendant l’exécution du pipeline. Il est important d’exécuter l’étape d’installation avant toute opération DacPac ou BacPac dans le pipeline. Cette tâche peut être associée à une étape pour vérifier la version et s’assurer que la mise à niveau s’est terminée comme prévu.

Azure Pipelines, agent basé sur Windows

Lorsque la tâche PowerShell est utilisée dans un pipeline Azure, une étape peut être ajoutée à un pipeline Azure qui télécharge le programme d’installation DacFx souhaité et l’installe en mode silencieux.

- task: PowerShell@2
  displayName: 'upgrade sqlpackage'
  inputs:
    targetType: 'inline'
    script: |
      # use evergreen or specific dacfx msi link below
      wget -O DacFramework.msi "https://aka.ms/dacfx-msi"
      msiexec.exe /i "DacFramework.msi" /qn

GitHub Actions, exécuteur Linux

Dans un flux de travail GitHub Action, vous pouvez utiliser le mot clé d’exécution pour exécuter les dotnet tool commandes pour installer, désinstaller ou mettre à jour SqlPackage. L’exemple suivant montre comment mettre à jour SqlPackage vers la dernière préversion :

- name: Update SqlPackage
  run: dotnet tool update --global Microsoft.SqlPackage --prerelease

Environnements virtuels autohébergés

Dans un environnement virtuel auto-hébergé, tel qu’un agent Azure DevOps auto-hébergé ou un exécuteur GitHub Actions, vous pouvez installer SqlPackage sur l’environnement hôte ou installer SqlPackage au moment de l’exécution, comme décrit dans les environnements virtuels managés. Si vous installez SqlPackage sur l’environnement hôte, les pipelines qui s’exécutent sur cet hôte n’ont pas besoin d’installer SqlPackage au moment de l’exécution, ce qui peut accélérer les exécutions du pipeline. Lorsque SqlPackage est installé sur l’hôte, vous devez mettre à jour SqlPackage régulièrement pour maintenir l’environnement avec la dernière version.

Les travaux Azure Container Apps peuvent être utilisés pour déployer des exécuteurs auto-hébergés dans un conteneur déployé selon les besoins de chaque appel de flux de travail. Avec les travaux Container Apps, vous contrôlez l’environnement tel que défini dans le fichier Dockerfile et installez SqlPackage et d’autres outils en fonction des besoins. L’exécuteur auto-hébergé peut être configuré pour s’exécuter sur une version spécifique de SqlPackage en incluant l’étape d’installation dans l’image conteneur. Par exemple, le didacticiel inclut un fichier Dockerfile qui installe curl et jq.

Nous pouvons modifier cet exemple pour produire une image conteneur qui installe .NET 8.0 et SqlPackage :

FROM ghcr.io/actions/actions-runner:2.323.0

USER root

# install dotnet sdk and sqlpackage
RUN apt-get update && apt-get install -y dotnet-sdk-8.0 && \
    dotnet tool install --tool-path /usr/local/bin/ Microsoft.SqlPackage

COPY entrypoint.sh ./entrypoint.sh
RUN chmod +x ./entrypoint.sh

USER runner

ENTRYPOINT ["./entrypoint.sh"]

Suivre les déploiements

Vous pouvez capturer certains fichiers liés à SqlPackage pour reproduire des pipelines et améliorer le suivi du déploiement. L’implémentation et les cas d’usage dépendent de votre architecture et de votre environnement d’automatisation spécifiques.

• Fichier DACPAC

• Sortie du fichier de diagnostic à partir de n’importe quelle action : Utilisez le paramètre sur n’importe /DiagnosticsFile: quelle action SqlPackage. Pour plus d’informations, consultez Obtenir des diagnostics SqlPackage dans un agent de pipeline

• Sortie de l'action de script avant l'action de publication : Utilisez l'action Script de SqlPackage avant d'invoquer une action de publication

Obtenir les diagnostics SqlPackage dans un agent de pipeline

Les informations de diagnostic SqlPackage sont disponibles dans la ligne de commande via le paramètre /DiagnosticsFile, qui peut être utilisé dans des environnements virtuels comme Azure Pipelines et GitHub Actions. Les informations de diagnostic sont écrites dans un fichier dans le répertoire de travail. Le nom de fichier est dicté par le paramètre /DiagnosticsFile.

Azure Pipelines

L’ajout du /DiagnosticsFile paramètre au champ « Arguments SqlPackage supplémentaires » dans la configuration d’Azure Pipeline SqlAzureDacpacDeployment entraîne l’écriture des informations de diagnostic SqlPackage dans le fichier spécifié. Après la tâche SqlAzureDacpacDeployment, le fichier de diagnostic est disponible en dehors de l’environnement virtuel en publiant un artefact de pipeline, comme indiqué dans l’exemple suivant.

- task: SqlAzureDacpacDeployment@1
  inputs:
    azureSubscription: '$(azuresubscription)'
    AuthenticationType: 'server'
    ServerName: '$(servername)'
    DatabaseName: '$(databasename)'
    SqlUsername: '$(sqlusername)'
    SqlPassword: '$(sqladminpassword)'
    deployType: 'DacpacTask'
    DeploymentAction: 'Publish'
    DacpacFile: '$(Build.Repository.LocalPath)\$(dacpacname).dacpac'
    AdditionalArguments: '/DiagnosticsFile:$(System.DefaultWorkingDirectory)/output.log'
    IpDetectionMethod: 'AutoDetect'

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(System.DefaultWorkingDirectory)/output.log'
    artifact: 'Diagnostic File'
    publishLocation: 'pipeline'

Une fois l’exécution du pipeline exécutée, le fichier de diagnostic peut être téléchargé à partir de la page récapitulative de l’exécution sous « Artefacts publiés ».

GitHub Actions

L’ajout du /DiagnosticsFile paramètre au champ « arguments » dans la configuration de l’action sql-action GitHub Entraîne l’écriture des informations de diagnostic SqlPackage dans le fichier spécifié. Après la tâche sql-action, le fichier de diagnostic peut être mis à disposition en dehors de l’environnement virtuel en publiant un artefact, comme indiqué dans l’exemple suivant.

- name: Azure SQL Deploy
  uses: Azure/sql-action@v2
  with:
    # The connection string, including authentication information, for the Azure SQL Server database.
    connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
    # Path to DACPAC file to deploy
    path: .\DatabaseProjectAdventureWorksLT\bin\Release\DatabaseProjectAdventureWorksLT.dacpac
    action: publish
    # additional SqlPackage arguments
    arguments: /DiagnosticsFile:DatabaseProjectAdventureWorksLT/DiagnosticLog.log

- uses: actions/upload-artifact@v2
  with:
    name: 'DiagnosticLog.txt'
    path: 'DatabaseProjectAdventureWorksLT/DiagnosticLog.log'

Contenu connexe

• SqlPackage
• Tutoriel : Créer et déployer un projet SQL