SqlPackage dalam alur pengembangan

SqlPackage adalah utilitas baris perintah yang mengotomatiskan beberapa tugas pengembangan database dan dapat dimasukkan ke dalam alur CI/CD.

Catatan

Memanfaatkan penginstalan mandiri SqlPackage untuk otomatisasi alur disarankan daripada menggunakan executable SqlPackage yang dibundel dengan aplikasi lain, termasuk SQL Server Management Studio atau Visual Studio. Penginstalan mandiri SqlPackage diperbarui lebih sering dan tidak terkait dengan irama rilis aplikasi lain.

Jika SqlPackage diinstal sebagai alat dotnet global (disarankan), Anda dapat memanggilnya dalam pipeline hanya dengan sqlpackage dari direktori apa pun. Jika SqlPackage diinstal sebagai eksekutabel mandiri, Anda harus menentukan jalur lengkap ke file eksekusi tersebut di pipeline. Di Windows, instalasi mandiri SqlPackage tersedia di jalur C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Di lingkungan Windows dan Linux, jika Anda mengunduh .zip SqlPackage mandiri untuk .NET, Anda dapat mengekstrak berkas eksekusi ke lokasi yang Anda pilih.

Lingkungan virtual terkelola

Lingkungan virtual yang digunakan untuk runner yang dihosting oleh GitHub Actions dan gambar mesin virtual Azure Pipelines dikelola di repositori GitHub runner-images. SqlPackage disertakan dalam beberapa lingkungan termasuk windows-latest dan ubuntu-22.04 tetapi tidak lagi disertakan secara default di ubuntu-24.04 dan ubuntu-latest. Pembaruan pada gambar dalam runner-images dibuat dalam beberapa minggu setelah setiap rilis SqlPackage.

Di dalam lingkungan virtual terkelola, Anda akan menginstal SqlPackage saat waktu eksekusi di alur. Penginstalan dilakukan sebagai langkah terpisah di Azure Pipelines dan GitHub Actions dan menambahkan penundaan singkat ke setiap eksekusi alur saat penginstalan terjadi. Untuk menginstal SqlPackage saat runtime, tambahkan langkah ke alur yang menggunakan CLI dotnet untuk menginstal SqlPackage sebagai alat global. Langkah ini harus dijalankan sebelum langkah-langkah SqlPackage dalam pipeline.

dotnet tool install --global Microsoft.SqlPackage

Anda mungkin perlu melakukan langkah penyiapan .NET di alur sebelum menginstal SqlPackage, yang ditunjukkan oleh pesan kesalahan yang menyatakan bahwa .NET tidak dapat ditemukan. Gunakan tindakan terintegrasi untuk mengonfigurasinya seperti tugas UseDotNet di Azure Pipelines atau tindakan setup-dotnet di GitHub Actions.

Secara opsional, Anda dapat menentukan versi SqlPackage untuk diinstal dengan menambahkan --version <version> ke perintah instal atau Anda dapat menggunakan --prerelease bendera untuk menginstal versi pratinjau.

Contoh: Langkah-langkah untuk menginstal SqlPackage di Alur Azure DevOps

Di Azure DevOps Pipelines, Anda dapat menggunakan tugas UseDotNet untuk menginstal .NET SDK lalu menginstal SqlPackage sebagai alat global. Jika Anda menggunakan agen Windows yang disediakan oleh Microsoft, SqlPackage sudah diinstal di C:\Program Files\Microsoft SQL Server\170\DAC\bin. Jika Anda menggunakan agen yang dihost sendiri, Anda juga dapat menginstal SqlPackage di lingkungan host dan melewati langkah ini di alur.

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

Contoh: Langkah-langkah untuk menginstal SqlPackage di GitHub Actions

Di GitHub Actions, Anda dapat menggunakan tindakan setup-dotnet untuk menginstal .NET SDK lalu menginstal SqlPackage sebagai alat global. Jika Anda menggunakan runner Windows yang disediakan oleh GitHub, SqlPackage sudah diinstal di C:\Program Files\Microsoft SQL Server\170\DAC\bin. Jika Anda menggunakan runner yang dihost sendiri, Anda juga dapat menginstal SqlPackage di lingkungan host dan melewati langkah ini dalam alur kerja.

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

Periksa versi SqlPackage

Selama upaya pemecahan masalah, penting untuk mengetahui versi SqlPackage sedang digunakan. Menangkap informasi ini dapat dilakukan dengan menambahkan langkah ke alur untuk menjalankan SqlPackage dengan /version parameter . Contoh diberikan dalam artikel ini berdasarkan lingkungan terkelola Azure DevOps dan GitHub, lingkungan yang dihost sendiri mungkin memiliki jalur penginstalan yang berbeda untuk direktori kerja.

Azure Pipelines (Alat otomatisasi alur kerja pengembangan perangkat lunak dari Microsoft)

Dalam Azure Pipeline, kata kunci skrip mengembalikan nomor versi SqlPackage.

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

Tindakan GitHub

Dalam alur kerja GitHub Action, kata kunci eksekusi mengembalikan nomor versi SqlPackage.

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

Memperbarui SqlPackage pada agen alur

Dalam beberapa skenario, versi SqlPackage yang saat ini diinstal di lingkungan pipeline mungkin tidak cukup. Jika lingkungan tidak dapat dimodifikasi secara langsung, langkah tambahan dapat digunakan untuk menginstal versi SqlPackage yang lebih baru selama eksekusi alur. Penting untuk menjalankan langkah instalasi sebelum menjalankan operasi DacPac atau BacPac dalam pipeline. Tugas ini dapat dikombinasikan dengan langkah untuk memeriksa versi untuk memastikan bahwa peningkatan selesai seperti yang diharapkan.

Azure Pipelines, agen berbasis Windows

Saat tugas PowerShell digunakan dalam Azure Pipeline, langkah dapat ditambahkan ke Azure Pipeline yang mengunduh penginstal DacFx yang diinginkan dan menginstalnya secara diam-diam.

- 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, runner berbasis Linux

Dalam alur kerja GitHub Action, Anda dapat menggunakan kata kunci run untuk menjalankan perintah dotnet tool untuk menginstal, menghapus instalasi, atau memperbarui SqlPackage. Contoh berikut menunjukkan cara memperbarui SqlPackage ke versi pratinjau terbaru:

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

Lingkungan virtual yang dihost sendiri

Di lingkungan virtual yang dihost sendiri seperti agen Azure DevOps yang dihost sendiri atau runner GitHub Actions, Anda dapat menginstal SqlPackage di lingkungan host atau menginstal SqlPackage pada runtime seperti yang dijelaskan di lingkungan virtual terkelola. Jika Anda menginstal SqlPackage di lingkungan host, alur yang berjalan pada host tersebut tidak perlu menginstal SqlPackage saat runtime, yang dapat mempercepat eksekusi alur. Ketika SqlPackage diinstal pada host, Anda harus memperbarui SqlPackage secara teratur untuk mempertahankan lingkungan dengan versi terbaru.

Azure Container Apps jobs dapat digunakan untuk menyebarkan runner yang di-host sendiri dalam kontainer yang disebarkan sesuai kebutuhan untuk setiap pemanggilan alur kerja. Dengan pekerjaan Container Apps, Anda mengontrol lingkungan seperti yang didefinisikan dalam Dockerfile dan menginstal SqlPackage dan alat lain sesuai kebutuhan. Runner yang dihost sendiri dapat dikonfigurasi untuk berjalan pada versi SqlPackage tertentu dengan menyertakan langkah penginstalan dalam gambar kontainer. Misalnya, tutorial mencakup Dockerfile yang menginstal curl dan jq.

Kita dapat memodifikasi contoh ini untuk menghasilkan gambar kontainer yang menginstal .NET 8.0 dan 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"]

Melacak penyebaran

Anda dapat mengambil beberapa file yang terkait dengan SqlPackage untuk mereproduksi alur dan meningkatkan pelacakan penyebaran. Implementasi dan kasus penggunaan tergantung pada arsitektur dan lingkungan otomatisasi spesifik Anda.

• File Dacpac

• File output diagnostik dari aksi apa pun: Gunakan parameter /DiagnosticsFile: pada operasi SqlPackage apa pun. Untuk informasi selengkapnya, lihat Mendapatkan diagnostik SqlPackage di agen alur

• Hasil keluaran dari tindakan skrip sebelum tindakan penerbitan: Gunakan tindakan script SqlPackage sebelum menggunakan tindakan penerbitan

Mendapatkan diagnostik SqlPackage di agen alur

Informasi diagnostik dari SqlPackage tersedia di baris perintah melalui parameter /DiagnosticsFile, yang dapat digunakan di lingkungan virtual seperti Azure Pipelines dan GitHub Actions. Informasi diagnostik ditulis ke file di direktori kerja. Nama file ditentukan oleh /DiagnosticsFile parameter .

Azure Pipelines (Alat otomatisasi alur kerja pengembangan perangkat lunak dari Microsoft)

Menambahkan parameter /DiagnosticsFile ke dalam bidang "Argumen SqlPackage Tambahan" dalam konfigurasi Azure Pipeline SqlAzureDacpacDeployment menyebabkan informasi diagnostik SqlPackage ditulis ke file yang telah ditentukan. Mengikuti tugas SqlAzureDacpacDeployment, file diagnostik tersedia di luar lingkungan virtual dengan menerbitkan artefak alur seperti yang terlihat dalam contoh berikut.

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

Setelah jalur pemrosesan dieksekusi, file diagnostik dapat diunduh dari halaman ringkasan jalur pemrosesan di bawah "Artefak yang Diterbitkan."

Tindakan GitHub

Menambahkan parameter /DiagnosticsFile ke bidang "arguments" dalam konfigurasi tindakan sql-action di GitHub Action menyebabkan informasi diagnostik SqlPackage ditulis ke file yang ditentukan. Setelah tugas sql-action, file diagnostik dapat diakses dari luar lingkungan virtual dengan menerbitkan artefak seperti yang terlihat dalam contoh berikut.

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

Konten terkait

• SqlPackage
• Tutorial: Membuat dan menyebarkan proyek SQL