SqlPackage nos pipelines de desenvolvimento

SqlPackage é um utilitário de linha de comando que automatiza várias tarefas de desenvolvimento de banco de dados e pode ser incorporado em pipelines de CI/CD.

Se o SqlPackage estiver instalado como uma ferramenta dotnet global (recomendado), pode invocá-lo no pipeline simplesmente usando sqlpackage a partir de qualquer diretório. Se SqlPackage estiver instalado como um executável autônomo, você deverá especificar o caminho completo para o executável no pipeline. No Windows, a instalação autônoma do SqlPackage está disponível no caminho C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Em ambientes Windows e Linux, se baixar o SqlPackage autossuficiente .zip para .NET, pode extrair o executável para um local da sua escolha.

Ambientes virtuais gerenciados

Os ambientes virtuais usados para runners alojados do GitHub Actions e imagens de máquina virtual do Azure Pipelines são geridos no repositório runner-images do GitHub. SqlPackage está incluído em vários ambientes, incluindo windows-latest e ubuntu-22.04 mas não está mais incluído por padrão em ubuntu-24.04 e ubuntu-latest. As atualizações das imagens em runner-images são feitas dentro de algumas semanas após cada liberação do SqlPackage.

Em um ambiente virtual gerenciado, você instalaria o SqlPackage em tempo de execução no pipeline. A instalação é realizada como uma etapa separada em Azure Pipelines e GitHub Actions e introduz um pequeno atraso em cada execução do pipeline enquanto a instalação ocorre. Para instalar o SqlPackage em tempo de execução, adicione uma etapa ao pipeline que usa a CLI dotnet para instalar o SqlPackage como uma ferramenta global. Esta etapa deve ser executada antes de qualquer ação SqlPackage no pipeline.

dotnet tool install --global Microsoft.SqlPackage

Talvez seja necessário executar uma etapa de instalação do .NET no pipeline antes de instalar o SqlPackage, indicada por uma mensagem de erro informando que o .NET não pode ser encontrado. Use uma ação integrada para configurá-lo, como a tarefa UseDotNet no Azure Pipelines ou a ação setup-dotnet em Ações do GitHub.

Opcionalmente, pode especificar uma versão do SqlPackage para instalar anexando --version <version> ao comando install ou pode usar a flag --prerelease para instalar versões de visualização.

Exemplo: etapas para instalar o SqlPackage no Azure DevOps Pipelines

No Azure DevOps Pipelines, você pode usar a tarefa UseDotNet para instalar o SDK do .NET e, em seguida, instalar o SqlPackage como uma ferramenta global. Se você estiver usando um agente do Windows fornecido pela Microsoft, o SqlPackage já está instalado no C:\Program Files\Microsoft SQL Server\170\DAC\bin. Se você estiver usando um agente auto-hospedado, também poderá instalar o SqlPackage no ambiente host e ignorar esta etapa no 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'

Exemplo: Etapas para instalar o SqlPackage em ações do GitHub

Em Ações do GitHub, você pode usar a ação setup-dotnet para instalar o SDK do .NET e, em seguida, instalar o SqlPackage como uma ferramenta global. Se você estiver usando um executor do Windows fornecido pelo GitHub, o SqlPackage já está instalado no C:\Program Files\Microsoft SQL Server\170\DAC\bin. Se estiver a utilizar um runner auto-hospedado, pode também instalar o SqlPackage no ambiente de hospedagem e ignorar este passo no fluxo de trabalho.

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

Verifique a versão do SqlPackage

Durante os esforços de solução de problemas, é importante saber que a versão do SqlPackage está em uso. A captura dessas informações pode ser feita adicionando uma etapa ao pipeline para executar SqlPackage com o /version parâmetro. Exemplos são fornecidos neste artigo com base nos ambientes gerenciados do Azure DevOps e GitHub, os ambientes auto-hospedados podem ter caminhos de instalação diferentes para o diretório de trabalho.

Azure Pipelines (Pipelines do Azure)

Em um Pipeline do Azure, a palavra-chave script retorna o número de versão do SqlPackage.

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

Ações do GitHub

Em um fluxo de trabalho GitHub Action, a palavra-chave run retorna o número de versão do SqlPackage.

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

Atualizar SqlPackage no agente de pipeline

Em alguns cenários, a versão atual do SqlPackage instalada no ambiente de pipeline pode ser insuficiente. Se o ambiente não puder ser modificado diretamente, uma etapa extra poderá ser usada para instalar uma versão mais recente do SqlPackage durante a execução do pipeline. É importante executar a etapa de instalação antes de executar qualquer operação DacPac ou BacPac no pipeline. Essa tarefa pode ser combinada com uma etapa para verificar a versão para garantir que a atualização seja concluída conforme o esperado.

Azure Pipelines, agente baseado no Windows

Quando a tarefa do PowerShell é usada em um Pipeline do Azure, uma etapa pode ser adicionada a um Pipeline do Azure que baixa o instalador DacFx desejado e o instala silenciosamente.

- 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, executante baseado em Linux

Em um fluxo de trabalho de Ação do GitHub, você pode usar a palavra-chave run para executar os comandos para instalar, desinstalar ou atualizar o dotnet tool SqlPackage. O exemplo a seguir mostra como atualizar SqlPackage para a versão de visualização mais recente:

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

Ambientes virtuais auto-hospedados

Em um ambiente virtual auto-hospedado, como um agente de DevOps do Azure auto-hospedado ou um executor de Ações do GitHub, você pode instalar o SqlPackage no ambiente host ou instalar o SqlPackage em tempo de execução, conforme descrito em ambientes virtuais gerenciados. Se você instalar o SqlPackage no ambiente de host, os pipelines executados nesse host não precisarão instalar o SqlPackage em tempo de execução, o que pode acelerar as execuções do pipeline. Quando SqlPackage é instalado no host, você deve atualizar SqlPackage regularmente para manter o ambiente com a versão mais recente.

Os trabalhos dos Aplicativos de Contêiner do Azure podem ser usados para implantar executores autohospedados em um contêiner que é implantado conforme necessário para cada chamada de fluxo de trabalho. Com trabalhos de Aplicativos de Contêiner, você controla o ambiente conforme definido no Dockerfile e instala o SqlPackage e outras ferramentas conforme necessário. O runner auto-hospedado pode ser configurado para ser executado em uma versão específica do SqlPackage incluindo a etapa de instalação na imagem do contêiner. Por exemplo, o tutorial inclui um Dockerfile que instala curl e jq.

Podemos modificar este exemplo para produzir uma imagem de contêiner que instala o .NET 8.0 e o 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"]

Acompanhe implantações

Você pode capturar alguns arquivos relacionados ao SqlPackage para reproduzir pipelines e melhorar o acompanhamento da implantação. A implementação e os casos de uso dependem da sua arquitetura específica e do ambiente de automação.

• Arquivo Dacpac

• Saída do arquivo de diagnóstico de qualquer ação: Use o /DiagnosticsFile: parâmetro em qualquer ação SqlPackage. Para obter mais informações, consulte Obter diagnóstico SqlPackage em um agente de pipeline

• Saída da ação de script antes da ação de publicação: Utilize a ação Script do SqlPackage antes de executar uma ação de publicação

Obter diagnóstico SqlPackage em um agente de pipeline

As informações de diagnóstico do SqlPackage estão disponíveis na linha de comando por meio do parâmetro /DiagnosticsFile, que pode ser usado em ambientes virtuais, como Pipelines do Azure e Ações do GitHub. As informações de diagnóstico são gravadas em um arquivo no diretório de trabalho. O nome do ficheiro é ditado pelo parâmetro /DiagnosticsFile.

Azure Pipelines (Pipelines do Azure)

Adicionar o /DiagnosticsFile parâmetro ao campo "Additional SqlPackage Arguments" na configuração do Azure Pipeline SqlAzureDacpacDeployment faz com que as informações de diagnóstico do SqlPackage sejam gravadas no arquivo especificado. Seguindo a tarefa SqlAzureDacpacDeployment, o arquivo de diagnóstico está disponível fora do ambiente virtual publicando um artefato de pipeline, como visto no exemplo a seguir.

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

Após a execução do pipeline, o ficheiro de diagnóstico pode ser baixado a partir da página de resumo da execução em "Artefatos publicados".

Ações do GitHub

Adicionar o parâmetro /DiagnosticsFile ao campo "arguments" na configuração da ação sql-action do GitHub faz com que as informações de diagnóstico do SqlPackage sejam escritas no arquivo especificado. Após a tarefa sql-action, o arquivo de diagnóstico pode ser disponibilizado fora do ambiente virtual publicando um artefato, como visto no exemplo a seguir.

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

Conteúdo relacionado

• SqlPackage
• Tutorial: Criar e implantar um projeto SQL