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.

Ambientes virtuais

Observação

É recomendável utilizar uma instalação autônoma do SqlPackage para automação de pipeline usando os executáveis do SqlPackage agrupados com outros aplicativos, incluindo SQL Server Management Studio ou 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.

No Windows, a instalação autônoma do SqlPackage está disponível no caminho C:\Program Files\Microsoft SQL Server\160\DAC\bin (DacFx.msi) ou %USERPROFILE%\.dotnet\tools (ferramenta dotnet). No Linux, a instalação autônoma do SqlPackage está disponível no caminho ~/.dotnet/tools (ferramenta dotnet). Em ambientes Windows e Linux, se você baixar o .zip SqlPackage autocontido para .NET Core, poderá extrair o executável para um local de sua escolha.

Ambientes virtuais gerenciados

Os ambientes virtuais usados para executores hospedados do GitHub Actions e imagens de VM do Azure Pipelines são gerenciados no repositório runner-images do GitHub. O SqlPackage está incluído em vários ambientes, incluindo windows-latest 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.

Ambientes virtuais autohospedados

Caso você esteja utilizando o SqlPackage em um ambiente virtual auto-hospedado, como um agente Azure DevOps auto-hospedado, é recomendável atualizar o aplicativo regularmente para manter o ambiente com a versão mais recente.

Acompanhar implantações

Há alguns arquivos relacionados ao SqlPackage que podem ser capturados como artefatos de pipeline para criar a reprodutibilidade de execução de pipeline e melhorar o acompanhamento da implantação. A implementação e os casos de uso variam dependendo de seu ambiente de automação e arquitetura específico.

• Arquivo Dacpac
• Saída do arquivo de diagnóstico de qualquer ação: Use o parâmetro /DiagnosticsFile: em qualquer ação do SqlPackage, confira o exemplo abaixo
• 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

Outros exemplos do SqlPackage

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. Abaixo, são fornecidos exemplos com base nos ambientes gerenciados da Microsoft e do GitHub; ambientes auto-hospedados podem ter caminhos de instalação diferentes para o diretório de trabalho.

Azure Pipelines

Ao usar a palavra-chave script em um Pipeline do Azure, uma etapa que gera o número de versão do SqlPackage pode ser adicionada ao Pipeline do Azure.

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

GitHub Actions

Ao usar a palavra-chave run no fluxo de trabalho de uma Ação do GitHub, uma etapa pode ser adicionada à Ação do GitHub, que gera o número de versão do SqlPackage.

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

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

A adição do parâmetro /DiagnosticsFile ao campo "Argumentos Adicionais do SqlPackage" na configuração SqlAzureDacpacDeployment do pipeline do Azure fará com que a informação de diagnóstico do SqlPackage seja gravada no arquivo especificado. Após a tarefa SqlAzureDacpacDeployment, o arquivo de diagnóstico pode ser disponibilizado fora do ambiente virtual publicando um artefato de pipeline, como visto no exemplo abaixo.

- 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 da página de resumo de execução em "Artefatos Publicados".

GitHub Actions

Adicionar o parâmetro /DiagnosticsFile ao campo "argumentos" na configuração sql-action do GitHub Actions fará com que as informações de diagnóstico do SqlPackage seja gravada no arquivo especificado. Após a tarefa sql-action task, o arquivo de diagnóstico pode ser disponibilizado fora do ambiente virtual publicando um artefato, como visto no exemplo abaixo.

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

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 adicional poderá ser usada para instalar uma versão mais recente do SqlPackage durante a execução de 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

Ao usar a tarefa do PowerShell em um pipeline do Azure, uma etapa pode ser adicionada a um pipeline do Azure que baixa o MSI 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

Próximas etapas

• Saiba mais sobre o SqlPackage