Compartilhar via

SqlPackage em pipelines de desenvolvimento

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

Observação

É recomendável utilizar uma instalação autônoma do SqlPackage para automação de pipeline, em vez de usar os executáveis do SqlPackage agrupados com outros aplicativos, incluindo o SQL Server Management Studio ou o Visual Studio. A instalação autônoma do SqlPackage é atualizada com mais frequência e não está vinculada à cadência de lançamento de outros aplicativos.

Se o SqlPackage estiver instalado como uma ferramenta de dotnet global (recomendado), você pode invocá-lo no pipeline de qualquer diretório, simplesmente sqlpackage. Se o 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 você baixar o SqlPackage autocontido no formato .zip para .NET, poderá extrair o executável para um local à sua escolha.

Ambientes virtuais gerenciados

Os ambientes virtuais usados para os runners hospedados do GitHub Actions e as imagens de máquina virtual do Azure Pipelines são gerenciados no repositório GitHub runner-images. O 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 realizadas dentro de algumas semanas após cada lançamento do SqlPackage.

Em um ambiente virtual gerenciado, você instalaria o SqlPackage em runtime no pipeline. A instalação é executada como uma etapa separada no Azure Pipelines e no GitHub Actions e adiciona um pequeno atraso a cada execução de pipeline enquanto a instalação ocorre. Para instalar o SqlPackage em runtime, adicione uma etapa ao pipeline que usa a CLI do dotnet para instalar o SqlPackage como uma ferramenta global. Esta etapa deve ser executada antes de qualquer ação do 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, indicado por uma mensagem de erro informando que o .NET não pode ser encontrado. Use uma ação integrada para configurá-la, como a tarefa UseDotNet no Azure Pipelines ou a ação setup-dotnet no GitHub Actions.

Opcionalmente, você pode especificar uma versão do SqlPackage a ser instalada acrescentando ao comando de instalação --version <version> ou pode usar o --prerelease sinalizador para instalar uma versão prévia.

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.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 do host e ignorar essa 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 no GitHub Actions

No GitHub Actions, 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.C:\Program Files\Microsoft SQL Server\170\DAC\bin Se você estiver usando um executor auto-hospedado, também poderá instalar o SqlPackage no ambiente do host e ignorar essa etapa 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>

Verificar a versão do SqlPackage

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

Azure Pipelines

No Azure Pipeline, 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'

GitHub Actions

No fluxo de trabalho do GitHub Action, a palavra-chave run (execução) 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

Saída da ação do GitHub exibindo o número de build 15.0.4897.1

Atualizar o 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 da execução de qualquer operação DacPac ou BacPac no pipeline. Essa tarefa pode ser combinada com uma etapa de verificação da versão a fim de garantir que a atualização foi 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 do 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, executor baseado em Linux

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

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

Ambientes virtuais autohospedados

Em um ambiente virtual auto-hospedado, como um agente do Azure DevOps auto-hospedado ou um executor do GitHub Actions, você pode instalar o SqlPackage no ambiente do host ou instalar o SqlPackage em runtime, 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 runtime, o que pode acelerar as execuções do pipeline. Quando o SqlPackage estiver instalado no host, você deverá atualizar o 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 auto-hospedados em um contêiner implantado conforme necessário para cada invocação 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 executor 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"]

Acompanhar 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 de 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 parâmetro /DiagnosticsFile: em qualquer ação do SqlPackage. Para obter mais informações, consulte Obter o diagnóstico do SqlPackage em um agente de pipeline

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

Obter o diagnóstico SqlPackage em um operador 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 Azure Pipelines e GitHub Actions. As informações de diagnóstico são gravadas em um arquivo no diretório de trabalho. O nome do arquivo é indicado pelo parâmetro /DiagnosticsFile.

Azure Pipelines

Adicionar o /DiagnosticsFile parâmetro ao campo "Argumentos Adicionais do SqlPackage" na configuração sqlAzureDacpacDeployment do Azure Pipeline faz com que as informações de diagnóstico do SqlPackage sejam gravadas no arquivo especificado. Após a tarefa SqlAzureDacpacDeployment, o arquivo de diagnóstico fica disponível fora do ambiente virtual pela publicação de 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 arquivo de diagnóstico pode ser baixado na página de resumo de execução em "Artefatos Publicados".

GitHub Actions

Adicionar o /DiagnosticsFile parâmetro ao campo "argumentos" na configuração de ação sql do GitHub Action faz com que as informações de diagnóstico do SqlPackage sejam gravadas 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

  • Last updated on