Поделиться через

SqlPackage в конвейерах разработки

SqlPackage — это программа командной строки, которая автоматизирует несколько задач разработки баз данных и может быть включена в конвейеры CI/CD.

Примечание.

Использование автономной установки SqlPackage для автоматизации конвейера рекомендуется, а не использование исполняемых файлов SqlPackage, входящих в состав других приложений, таких как SQL Server Management Studio или Visual Studio. Автономная установка SqlPackage обновляется чаще и не привязана к частоте выпуска других приложений.

Если SqlPackage установлен как глобальное средство dotnet (рекомендуется), его можно вызвать в конвейере с помощью sqlpackage из любого каталога. Если SqlPackage установлен как автономный исполняемый файл, необходимо указать полный путь к исполняемому файлу в конвейере. В Windows автономная установка SqlPackage доступна по пути C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). В средах Windows и Linux при скачивании автономного .zip SqlPackage для .NET можно извлечь исполняемый файл в выбранное расположение.

Управляемые виртуальные среды

Виртуальные среды, используемые для агентов GitHub Actions и образов виртуальных машин Azure Pipelines, управляются в репозитории GitHub runner-images. SqlPackage включается в несколько сред, включая windows-latest и ubuntu-22.04, но больше не включается по умолчанию в ubuntu-24.04 и ubuntu-latest. Обновления образов в runner-images выполняются в течение нескольких недель после каждого выпуска SqlPackage.

В управляемой виртуальной среде вы устанавливаете SqlPackage в конвейере во время выполнения. Установка выполняется как отдельный шаг либо в Azure Pipelines, либо в GitHub Actions и добавляет короткую задержку к каждому запуску конвейера на время установки. Чтобы установить SqlPackage во время выполнения, добавьте шаг в конвейер, использующий dotnet CLI для установки SqlPackage в качестве глобального инструмента. Этот шаг должен выполняться перед любыми действиями SqlPackage в конвейере.

dotnet tool install --global Microsoft.SqlPackage

Перед установкой SqlPackage может потребоваться выполнить шаг настройки .NET, если появится сообщение об ошибке, указывающее на то, что .NET не найден. Используйте интегрированное действие, чтобы настроить его, например задачу UseDotNet в Azure Pipelines или действие setup-dotnet в GitHub Actions.

При необходимости можно указать версию SqlPackage для установки, добавив --version <version> в команду установки или с помощью --prerelease флага для установки предварительных версий.

Пример. Шаги по установке SqlPackage в Azure DevOps Pipelines

В Azure DevOps Pipelines можно использовать задачу UseDotNet для установки пакета SDK для .NET, а затем установить SqlPackage в качестве глобального средства. Если вы используете агент Windows, предоставляемый корпорацией Майкрософт, SqlPackage уже установлен в C:\Program Files\Microsoft SQL Server\170\DAC\bin. Если вы используете локальный агент, вы также можете установить SqlPackage в среде узла и пропустить этот шаг в конвейере.

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

Пример. Действия по установке SqlPackage в GitHub Actions

В GitHub Actions можно использовать действие setup-dotnet для установки пакета SDK для .NET, а затем установить SqlPackage в качестве глобального средства. Если вы используете средство запуска Windows, предоставляемое GitHub, SqlPackage уже установлено в C:\Program Files\Microsoft SQL Server\170\DAC\bin. Если вы используете локальный агент выполнения, вы также можете установить SqlPackage в хост-среде и пропустить этот шаг в рабочем процессе.

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

Проверка версии SqlPackage

При устранении неполадок очень важно знать, какая версия SqlPackage используется. Получить эти данные можно, добавив в конвейер шаг для выполнения SqlPackage с параметром /version. Примеры приведены в этой статье на основе управляемых сред Azure DevOps и GitHub, локальные среды могут иметь разные пути установки для рабочего каталога.

Azure Pipelines (система конвейеров Azure)

В Azure Pipeline ключевое слово скрипта возвращает номер версии SqlPackage.

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

Действия GitHub

В рабочем процессе GitHub Action ключевое слово run возвращает номер версии SqlPackage.

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

Вывод действия GitHub, отображающего номер сборки 15.0.4897.1

Обновление SqlPackage в агенте конвейера

В некоторых сценариях текущая версия SqlPackage, установленная в среде конвейера, может оказаться недостаточной. Если среда не может быть изменена напрямую, можно использовать дополнительный шаг для установки более новой версии SqlPackage во время выполнения конвейера. Важно выполнить шаг установки перед выполнением любых операций DacPac или BacPac в конвейере. Эту задачу можно объединить с шагом проверки версии, чтобы убедиться, что обновление выполнено.

Azure Pipelines, агент на основе Windows

Когда задача PowerShell используется в Azure Pipeline, шаг можно добавить в Azure Pipeline, который скачивает нужный установщик DacFx и автоматически устанавливает его.

- 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, раннер на основе Linux

В рабочем процессе GitHub Action можно использовать ключевое слово run для выполнения dotnet tool команд для установки, удаления или обновления SqlPackage. В следующем примере показано, как обновить SqlPackage до последней предварительной версии:

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

Виртуальные среды с локальным размещением

В локальной виртуальной среде, например локально размещенном агенте Azure DevOps или GitHub Actions runner, можно установить SqlPackage в хост-среде или установить SqlPackage во время выполнения, как описано в управляемых виртуальных средах. Если установить программу SqlPackage в среде узла, конвейеры, которые выполняются на этом узле, не нужно устанавливать SqlPackage во время выполнения, что поможет ускорить выполнение конвейеров. При установке SqlPackage на узле следует регулярно обновлять SqlPackage для поддержания среды с последней версией.

Задания приложений контейнеров Azure можно использовать для развертывания самостоятельно размещаемых агентов в контейнере, который разворачивается по мере необходимости для каждого вызова рабочего процесса. С помощью заданий "Приложения контейнеров" вы управляете средой, как определено в Dockerfile, и устанавливаете SqlPackage и другие средства по мере необходимости. Локальное средство выполнения можно настроить для запуска в определенной версии SqlPackage, включив шаг установки в образ контейнера. Например, в этом руководстве содержится файл Dockerfile, который устанавливает curl и jq.

Мы можем изменить этот пример, чтобы создать образ контейнера, который устанавливает .NET 8.0 и 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"]

Отслеживание развертываний

Вы можете записать некоторые файлы, связанные с SqlPackage, чтобы воспроизвести конвейеры и улучшить отслеживание развертывания. Варианты реализации и использования зависят от конкретной архитектуры и среды автоматизации.

  • DACPAC-файл

  • Вывод диагностического файла из любого действия: Используйте параметр /DiagnosticsFile: в любом действии SqlPackage. Дополнительные сведения см. в разделе «Получение диагностики SqlPackage в агенте конвейера»

  • Выходные данные действия скрипта перед действием опубликования: используйте действие Скрипт SqlPackage перед выполнением действия публикации.

Получение диагностик SqlPackage на агенте конвейера

Диагностические данные из SqlPackage можно получить в командной строке с помощью параметра /DiagnosticsFile, который доступен для использования в виртуальных средах, таких как Azure Pipelines и GitHub Actions. Диагностическая информация записывается в файл в рабочем каталоге. Имя файла определяется параметром /DiagnosticsFile.

Azure Pipelines (система конвейеров Azure)

/DiagnosticsFile Добавление параметра в поле "Дополнительные аргументы SqlPackage" в конфигурации Azure Pipeline SqlAzureDacpacDeployment приводит к записи диагностических сведений SqlPackage в указанный файл. После задачи SqlAzureDacpacDeployment файл диагностики доступен за пределами виртуальной среды благодаря публикации артефакта конвейера, как показано в следующем примере.

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

После запуска конвейера файл диагностики можно скачать на странице сводки запуска в разделе "Опубликованные артефакты".

Действия GitHub

/DiagnosticsFile Добавление параметра в поле "аргументы" в конфигурации GitHub Action sql-action приводит к записи диагностических сведений SqlPackage в указанный файл. После задачи sql-action файл диагностики можно сделать доступным за пределами виртуальной среды, публикуя артефакт, как показано в следующем примере.

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

Связанный контент