Geliştirme süreçlerinde SqlPackage

SqlPackage , çeşitli veritabanı geliştirme görevlerini otomatik hale getiren ve CI/CD işlem hatlarına dahil edilebilen bir komut satırı yardımcı programıdır.

Uyarı

SqlPackage yürütülebilir dosyaları, SQL Server Management Studio veya Visual Studio gibi diğer uygulamalarla birlikte sunulanlar yerine işlem hattı otomasyonu için SqlPackage'ın bağımsız bir kurulumu kullanılması tavsiye edilir. SqlPackage'ın bağımsız kurulumu daha sık güncelleştirilir ve diğer uygulamaların yayın temposuna bağlı değildir.

SqlPackage küresel bir dotnet aracı olarak yüklüyse (önerilir), işlem hattında sqlpackage sadece herhangi bir dizinden çağırabilirsiniz. SqlPackage tek başına yürütülebilir dosya olarak yüklendiyse, işlem hattındaki yürütülebilir dosyanın tam yolunu belirtmeniz gerekir. Windows'da, SqlPackage'ın tek başına yüklemesi C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi) dizininde mevcuttur. Hem Windows hem de Linux ortamlarında, .NET için bağımsız .zip SqlPackage'ı indirirseniz yürütülebilir dosyayı seçtiğiniz bir konuma ayıklayabilirsiniz.

Yönetilen sanal ortamlar

GitHub Actions tarafından barındırılan çalıştırıcılar ve Azure Pipelines sanal makine görüntüleri için kullanılan sanal ortamlar runner-images GitHub deposunda yönetilir. SqlPackage, windows-latest ve ubuntu-22.04 dahil çeşitli ortamlarda bulunur, ancak artık ubuntu-24.04 ve ubuntu-latest'e varsayılan olarak dahil edilmemektedir. Runner-images içindeki görüntülerde yapılan güncelleştirmeler, her SqlPackage sürümünden sonra birkaç hafta içinde yapılır.

Yönetilen bir sanal ortamda, SqlPackage'ı işlem hattının çalışma zamanında yüklersiniz. Yükleme, Azure Pipelines veya GitHub Actions'da ayrı bir adım olarak gerçekleştirilir ve yükleme sırasında her işlem hattı çalıştırma işlemine kısa bir gecikme ekler. SqlPackage'ı çalışma zamanında yüklemek için, dotnet CLI kullanarak SqlPackage'ı genel bir araç olarak yükleyen işlem hattına bir adım ekleyin. Bu adım, işlem hattındaki herhangi bir SqlPackage eyleminden önce çalıştırılmalıdır.

dotnet tool install --global Microsoft.SqlPackage

SqlPackage'ı yüklemeden önce işlem hattında .NET'in bulunamadığını belirten bir hata iletisiyle gösterilen bir .NET kurulum adımı gerçekleştirmeniz gerekebilir. Azure Pipelines'daki UseDotNet görevi veya GitHub Actions'daki setup-dotnet eylemi gibi tümleşik bir eylem kullanın.

İsteğe bağlı olarak, yükleme komutuna ekleyerek --version <version> yüklenecek SqlPackage sürümünü belirtebilir veya önizleme sürümlerini yüklemek için bayrağını --prerelease kullanabilirsiniz.

Örnek: Azure DevOps Pipelines'a SqlPackage yükleme adımları

Azure DevOps Pipelines'da UseDotNet görevini kullanarak .NET SDK'sını yükleyebilir ve ardından SqlPackage'ı genel bir araç olarak yükleyebilirsiniz. Microsoft tarafından sağlanan bir Windows aracısı kullanıyorsanız, SqlPackage C:\Program Files\Microsoft SQL Server\170\DAC\bin zaten yüklü olarak gelir. Kullanıcılar kendi kendine barındırılan bir aracı kullanıyorsa, SqlPackage'ı konak ortamına da yükleyebilir ve işlem hattında bu adımı atlayabilir.

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

Örnek: GitHub Actions'da SqlPackage yükleme adımları

GitHub Actions'da setup-dotnet eylemini kullanarak .NET SDK'sını yükleyebilir ve ardından SqlPackage'ı genel bir araç olarak yükleyebilirsiniz. GitHub tarafından sağlanan bir Windows çalıştırıcısı kullanıyorsanız, SqlPackage C:\Program Files\Microsoft SQL Server\170\DAC\bin içinde zaten yüklüdür. Kendi kendine barındırılan bir çalıştırıcı kullanıyorsanız, SqlPackage'i konak ortamına da yükleyebilir ve iş akışında bu adımı atlayabilirsiniz.

- 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 sürümünü denetleme

Sorun giderme çalışmaları sırasında SqlPackage sürümünün kullanımda olduğunu bilmeniz önemlidir. SqlPackage'ı parametresiyle /version çalıştırmak için işlem hattına bir adım eklenerek bu bilgileri yakalama işlemi gerçekleştirilebilir. Azure DevOps ve GitHub yönetilen ortamlarına göre bu makalede örnekler verilmiştir, ancak kendi kendine barındırılan ortamlar için çalışma dizininin yükleme yolları farklı olabilir.

Azure Hatları

Azure Pipeline'da betik anahtar sözcüğü SqlPackage'in sürüm numarasını döndürür.

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

GitHub İşlemleri

GitHub Action iş akışında run anahtar sözcüğü SqlPackage sürüm numarasını döndürür.

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

İşlem hattı aracında SqlPackage'i güncelleştirme

Bazı senaryolarda, işlem hattı ortamında yüklü olan geçerli SqlPackage sürümü yetersiz olabilir. Ortam doğrudan değiştirilemiyorsa, işlem hattı çalıştırması sırasında sqlpackage'ın daha yeni bir sürümünü yüklemek için ek bir adım kullanılabilir. İşlem hattında herhangi bir DacPac veya BacPac işlemi çalıştırmadan önce yükleme adımını çalıştırmak önemlidir. Bu görev, yükseltmenin beklendiği gibi tamamlandığından emin olmak için sürümü denetlemek için bir adımla birleştirilebilir.

Azure Pipelines, Windows tabanlı aracı

PowerShell görevi bir Azure Pipeline'da kullanıldığında, istenen DacFx yükleyicisini indirip sessizce yükleyen bir Azure Pipeline'a bir adım eklenebilir.

- 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 tabanlı çalıştırıcı

GitHub Action iş akışında , SqlPackage'ı yükleme, kaldırma veya güncelleştirme komutlarını yürütmek dotnet tool için run anahtar sözcüğünü kullanabilirsiniz. Aşağıdaki örnekte, SqlPackage'ı en son önizleme sürümüne güncelleştirme adımları gösterilmektedir:

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

Kendinize ait barındırılan sanal ortamlar

Kendinden barındırılan Azure DevOps aracısı veya GitHub Actions çalıştırıcısı gibi bir sanal ortamda, SqlPackage'ı yönetilen sanal ortamlarda açıklandığı şekilde konak ortamına yükleyebilir veya çalışma zamanında kurabilirsiniz. SqlPackage'ı konak ortamına yüklerseniz, bu konakta çalışan işlem hatlarının çalışma zamanında SqlPackage yüklemesi gerekmez ve bu işlem hattı çalıştırmalarını hızlandırabilir. SqlPackage konağa yüklendiğinde, ortamı en son sürümle korumak için SqlPackage'ı düzenli olarak güncelleştirmeniz gerekir.

Azure Container Apps işleri, her iş akışı çağrısında gerektiğinde dağıtılan bir kapsayıcıda, kendi kendine barındırılan çalıştırıcıları dağıtmak için kullanılabilir. Container Apps işleri ile Dockerfile'da tanımlandığı gibi ortamı denetler ve gerektiğinde SqlPackage ve diğer araçları yüklersiniz. Kendi kendine barındırılan çalıştırıcı, yükleme adımı kapsayıcı imajına dahil edilerek SqlPackage'in belirli bir sürümünde çalışacak şekilde yapılandırılabilir. Örneğin, tutorial, curl ve jq'yi yükleyen bir Dockerfile içerir.

.NET 8.0 ve SqlPackage yükleyen bir kapsayıcı görüntüsü oluşturmak için bu örneği değiştirebiliriz:

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

Dağıtımları izleme

İşlem hatlarını yeniden oluşturmak ve dağıtım izlemeyi geliştirmek için SqlPackage ile ilgili bazı dosyaları yakalayabilirsiniz. Uygulama ve kullanım örnekleri, belirli mimarinize ve otomasyon ortamınıza bağlıdır.

• Dacpac dosyası

• Herhangi bir eylemden tanılama dosyası çıktısı: Herhangi bir SqlPackage eyleminde parametresini /DiagnosticsFile: kullanın. Daha fazla bilgi için bkz. İşlem hattı aracısında SqlPackage tanılamalarını alma

• Yayımlama eyleminden önceki betik eyleminin çıktısı: Bir yayımlama eylemi çağırmadan önce Betik SqlPackage eylemini kullanın.

İşlem hattı temsilcisinde SqlPackage tanılama bilgilerini alma

SqlPackage'dan alınan tanılama bilgileri, komut satırında parametresi /DiagnosticsFilearacılığıyla kullanılabilir. Bu bilgiler Azure Pipelines ve GitHub Actions gibi sanal ortamlarda kullanılabilir. Tanılama bilgileri çalışma dizinindeki bir dosyaya yazılır. Dosya adı, /DiagnosticsFile parametresi tarafından belirlenir.

Azure Hatları

Azure Pipeline SqlAzureDacpacDeployment yapılandırmasının "Ek SqlPackage Bağımsız Değişkenleri" alanına /DiagnosticsFile parametresinin eklenmesi, SqlPackage tanılama bilgilerinin belirtilen dosyaya yazılmasına neden olur. SqlAzureDacpacDeployment görevinin ardından, tanılama dosyası aşağıdaki örnekte görüldüğü gibi bir işlem hattı yapıtı yayımlanarak sanal ortamın dışında kullanılabilir.

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

"İşlem hattı çalıştırıldıktan sonra, tanılama dosyası 'Yayınlanmış Yapıtlar' altındaki çalıştırma özeti sayfasından indirilebilir."

GitHub İşlemleri

Parametrenin /DiagnosticsFile GitHub Action sql-action yapılandırmasındaki "arguments" alanına eklenmesi, SqlPackage tanılama bilgilerinin belirtilen dosyaya yazılmasına neden olur. sql-action görevinin ardından tanılama dosyası, aşağıdaki örnekte görüldüğü gibi bir yapıt yayımlanarak sanal ortamın dışında kullanılabilir hale getirilebilir.

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

İlgili içerik

• SqlPackage
• SQL Projesi Oluşturma ve Dağıtma Öğreticisi