Compartir a través de

SqlPackage en canalizaciones de desarrollo

SqlPackage es una utilidad de línea de comandos que automatiza varias tareas de desarrollo de la base de datos y que se puede incorporar en canalizaciones de CI/CD.

Nota

Se recomienda utilizar una instalación independiente de SqlPackage para la automatización de canalizaciones en lugar de usar los ejecutables de SqlPackage agrupados con otras aplicaciones, incluido SQL Server Management Studio o Visual Studio. La instalación independiente de SqlPackage se actualiza con más frecuencia y no está vinculada a la cadencia de versión de otras aplicaciones.

Si SqlPackage está instalado como una herramienta dotnet global (recomendada), puede invocarlo en el pipeline simplemente con sqlpackage desde cualquier directorio. Si SqlPackage se instala como un ejecutable independiente, debe especificar la ruta de acceso completa al ejecutable en la canalización. En Windows, la instalación independiente de SqlPackage está disponible en la ruta C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). En entornos de Windows y Linux, si descarga el SqlPackage autocontenido en formato .zip para .NET, puede extraer el archivo ejecutable a una ubicación de su elección.

Entornos virtuales administrados

Los entornos virtuales que se usan para los ejecutores hospedados en Acciones de GitHub y las imágenes de máquina virtual de Azure Pipelines se administran en el repositorio de GitHub runner-images . SqlPackage se incluye en varios entornos, incluidos windows-latest y ubuntu-22.04 , pero ya no se incluye de forma predeterminada en ubuntu-24.04 y ubuntu-latest. Las actualizaciones de las imágenes en runner-images se realizan a las pocas semanas de cada lanzamiento de SqlPackage.

En un entorno virtual administrado, instalaría SqlPackage durante la ejecución dentro de la canalización. La instalación se realiza como un paso separado tanto en Azure Pipelines como en GitHub Actions y agrega un breve retraso a cada ejecución de la canalización durante la instalación. Para instalar SqlPackage en tiempo de ejecución, agregue un paso a la canalización que usa la CLI de dotnet para instalar SqlPackage como una herramienta global. Este paso debe ejecutarse antes de cualquier acción de SqlPackage en la canalización.

dotnet tool install --global Microsoft.SqlPackage

Es posible que tenga que realizar un paso de instalación de .NET en la canalización antes de instalar SqlPackage, indicado por un mensaje de error que indica que no se encuentra .NET. Use una acción integrada para configurarla, como la tarea UseDotNet en Azure Pipelines o la acción setup-dotnet en Acciones de GitHub.

Opcionalmente, puede especificar una versión de SqlPackage que se va a instalar anexando --version <version> al comando de instalación o puede usar la --prerelease marca para instalar una versión preliminar.

Ejemplo: Pasos para instalar SqlPackage en canalizaciones de Azure DevOps

En Azure DevOps Pipelines, puede usar la tarea UseDotNet para instalar el SDK de .NET y, a continuación, instalar SqlPackage como una herramienta global. Si usa un agente de Windows proporcionado por Microsoft, SqlPackage ya está instalado en C:\Program Files\Microsoft SQL Server\170\DAC\bin. Si usa un agente autohospedado, también puede instalar SqlPackage en el entorno hospedado y omitir este paso en la canalización.

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

Ejemplo: Pasos para instalar SqlPackage en Acciones de GitHub

En Acciones de GitHub, puede usar la acción setup-dotnet para instalar el SDK de .NET y, a continuación, instalar SqlPackage como una herramienta global. Si usa un ejecutor de Windows proporcionado por GitHub, SqlPackage ya está instalado en C:\Program Files\Microsoft SQL Server\170\DAC\bin. Si usa un ejecutor autohospedado, también puede instalar SqlPackage en el entorno de host y omitir este paso en el flujo de trabajo.

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

Comprobación de la versión de SqlPackage

Durante la solución de problemas, es importante saber cuál es la versión de SqlPackage que está en uso. Para capturar esta información, puede agregar un paso a la canalización para ejecutar SqlPackage con el parámetro /version. En este artículo se proporcionan ejemplos basados en los entornos administrados de Azure DevOps y GitHub, los entornos autohospedados pueden tener diferentes rutas de instalación para el directorio de trabajo.

Azure Pipelines

En una canalización de Azure, la palabra clave script devuelve el número de versión de SqlPackage.

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

Acciones de GitHub

En un flujo de trabajo de acción de GitHub, la palabra clave run devuelve el número de versión de SqlPackage.

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

Salida de la instancia de Acciones de GitHub que muestra el número de compilación 15.0.4897.1

Actualización de SqlPackage en el agente de canalización

En algunos escenarios, la versión actual de SqlPackage instalada en el entorno de canalización podría ser insuficiente. Si el entorno no se puede modificar directamente, se puede usar un paso adicional para instalar una versión más reciente de SqlPackage durante la ejecución de la canalización. Es importante ejecutar el paso de instalación antes de ejecutar cualquier operación DacPac o BacPac en la canalización. Esta tarea se puede combinar con un paso para comprobar la versión a fin de asegurarse de que la actualización se ha completado según lo previsto.

Azure Pipelines, agente basado en Windows

Cuando se usa la tarea de PowerShell en una canalización de Azure, se puede agregar un paso a una canalización de Azure que descargue el instalador de DacFx deseado e instálelo de forma silenciosa.

- 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

Acciones de GitHub, ejecutor basado en Linux

En un flujo de trabajo de acción de GitHub, puede usar la palabra clave run para ejecutar los dotnet tool comandos para instalar, desinstalar o actualizar SqlPackage. En el ejemplo siguiente se muestra cómo actualizar SqlPackage a la versión preliminar más reciente:

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

Entornos virtuales auto-hospedados

En un entorno virtual autohospedado, como un agente de Azure DevOps autohospedado o un ejecutor de Acciones de GitHub, puede instalar SqlPackage en el entorno de host o instalar SqlPackage en tiempo de ejecución, tal como se describe en entornos virtuales administrados. Si instala SqlPackage en el entorno de host, las canalizaciones que se ejecutan en ese host no necesitan instalar SqlPackage en tiempo de ejecución, lo que puede acelerar las ejecuciones de canalización. Cuando SqlPackage está instalado en el host, debe actualizar SqlPackage periódicamente para mantener el entorno con la versión más reciente.

Los trabajos de Azure Container Apps se pueden usar para implementar ejecutores autohospedados en un contenedor que se implementa según sea necesario para cada invocación de flujo de trabajo. Con los trabajos de Container Apps, puede controlar el entorno tal como se define en Dockerfile e instalar SqlPackage y otras herramientas según sea necesario. El ejecutor autohospedado se puede configurar para que se ejecute en una versión específica de SqlPackage mediante la inclusión del paso de instalación en la imagen de contenedor. Por ejemplo, el tutorial incluye un Dockerfile que instala curl y jq.

Este ejemplo se puede modificar para generar una imagen de contenedor que instale .NET 8.0 y 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"]

Seguimiento de implementaciones

Puede capturar algunos archivos relacionados con SqlPackage para reproducir canalizaciones y mejorar el seguimiento de la implementación. Los casos de implementación y uso dependen de su arquitectura y entorno de automatización específicos.

  • Archivo Dacpac

  • Salida del archivo de diagnóstico de cualquier acción: Utilice el /DiagnosticsFile: parámetro en cualquier acción SqlPackage. Para obtener más información, consulte Obtener diagnósticos de SqlPackage en un agente de canalización.

  • Salida de la acción de script antes de la acción de publicación: utilice la acción Script de SqlPackage antes de invocar una acción de publicación

Obtención de diagnósticos de SqlPackage en un agente de canalización

La información de diagnóstico de SqlPackage está disponible en la línea de comandos a través del parámetro /DiagnosticsFile, que se puede usar en entornos virtuales como Azure Pipelines y Acciones de GitHub. La información de diagnóstico se escribe en un archivo en el directorio de trabajo. El nombre del archivo viene determinado por el parámetro /DiagnosticsFile.

Azure Pipelines

Al agregar el /DiagnosticsFile parámetro al campo "Argumentos adicionales de SqlPackage" en la configuración de SqlAzureDacpacDeployment de Azure Pipeline, la información de diagnóstico de SqlPackage se escribirá en el archivo especificado. Después de la tarea SqlAzureDacpacDeployment, el archivo de diagnóstico está disponible fuera del entorno virtual mediante la publicación de un artefacto de canalización como se muestra en el ejemplo siguiente.

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

Después de ejecutar la canalización, el archivo de diagnóstico se puede descargar desde la página de resumen de ejecución en "Artefactos publicados".

Acciones de GitHub

Agregar el parámetro /DiagnosticsFile al campo "argumentos" en la configuración de acciones de GitHub para sql-action hace que la información de diagnóstico de SqlPackage se escriba en el archivo especificado. Después de la tarea sql-action, el archivo de diagnóstico se puede poner a disposición fuera del entorno virtual mediante la publicación de un artefacto como se muestra en el ejemplo siguiente.

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

Contenido relacionado

  • Last updated on