SqlPackage ve vývojových kanálech

SqlPackage je nástroj příkazového řádku, který automatizuje několik úloh vývoje databází a dá se začlenit do kanálů CI/CD.

Poznámka:

Použití samostatné instalace SqlPackage pro automatizaci kanálů se doporučuje před použitím spustitelných souborů SqlPackage, které jsou součástí jiných aplikací, včetně SQL Server Management Studia nebo sady Visual Studio. Samostatná instalace SqlPackage se aktualizuje častěji a není svázaná s četností vydávání jiných aplikací.

Pokud je SqlPackage nainstalovaný jako globální nástroj dotnet (doporučeno), můžete jej v pipeline spustit jednoduše sqlpackage z libovolného adresáře. Pokud je SqlPackage nainstalovaný jako samostatný spustitelný soubor, musíte zadat úplnou cestu ke spustitelnému souboru v potrubí. Ve Windows je samostatná instalace sqlPackage k dispozici na cestě C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Pokud si v prostředích s Windows i Linuxem stáhnete samostatnou .zip SqlPackage pro .NET, můžete spustitelný soubor extrahovat do umístění podle vlastního výběru.

Spravovaná virtuální prostředí

Virtuální prostředí pro běhové procesy GitHub Actions a image virtuálních počítačů Azure Pipelines jsou spravována v úložišti GitHub runner-images. SqlPackage je součástí několika prostředí, včetně windows-latest a ubuntu-22.04, ale již není ve výchozím nastavení zahrnuta v ubuntu-24.04 a ubuntu-latest. Aktualizace obrazů runner-images se provádějí během několika týdnů od každé verze SqlPackage.

Ve spravovaném virtuálním prostředí byste za běhu nainstalovali SqlPackage v pipeline. Instalace se provádí jako samostatný krok buď v Azure Pipelines nebo GitHub Actions a přidává krátkou prodlevu ke každému spuštění kanálu během instalace. Pokud chcete nainstalovat SqlPackage za běhu, přidejte do kanálu krok, který používá rozhraní příkazového řádku dotnet k instalaci SqlPackage jako globální nástroj. Tento krok by se měl spustit před všemi akcemi SqlPackage v pipeline.

dotnet tool install --global Microsoft.SqlPackage

Před instalací balíčku SqlPackage možná bude nutné provést krok nastavení .NET v rámci potrubí, což je indikováno chybovou zprávou, že .NET nelze najít. Pomocí integrované akce ji můžete nakonfigurovat, například úlohu UseDotNet v Azure Pipelines nebo akci setup-dotnet v GitHub Actions.

Volitelně můžete zadat verzi SqlPackage, kterou chcete nainstalovat, připojením --version <version> k příkazu install nebo pomocí příznaku --prerelease nainstalovat verze Preview.

Příklad: Postup instalace SqlPackage v Azure DevOps Pipelines

V Azure DevOps Pipelines můžete pomocí úlohy UseDotNet nainstalovat sadu .NET SDK a pak nainstalovat SqlPackage jako globální nástroj. Pokud používáte agenta Systému Windows poskytovaný Microsoftem, sqlPackage je již nainstalován v C:\Program Files\Microsoft SQL Server\170\DAC\binsystému . Pokud používáte samohostovaného agenta, můžete nainstalovat SqlPackage do hostitelského prostředí a přeskočit tento krok v 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'

Příklad: Postup instalace SqlPackage v GitHub Actions

V GitHub Actions můžete pomocí akce setup-dotnet nainstalovat sadu .NET SDK a pak nainstalovat SqlPackage jako globální nástroj. Pokud používáte spouštěč Windows poskytovaný GitHubem, SqlPackage je už nainstalovaný v C:\Program Files\Microsoft SQL Server\170\DAC\bin. Pokud používáte spouštěč v místním prostředí, můžete také nainstalovat SqlPackage do hostitelského prostředí a tento krok v pracovním postupu přeskočit.

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

Kontrola verze SqlPackage

Během řešení potíží je důležité vědět, že se používá verze SqlPackage. Tyto informace lze zachytit přidáním kroku do potrubí, který spustí SqlPackage s parametrem /version. Příklady uvedené v tomto článku jsou založeny na spravovaných prostředích Azure DevOps a GitHub. Prostředí hostovaná lokálně mohou mít pro pracovní adresář různé instalační cesty.

Kanály Azure

Ve službě Azure Pipeline vrátí klíčové slovo skriptu číslo verze SqlPackage.

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

Akce na GitHubu

V pracovním postupu akce GitHub klíčové slovo run vrátí číslo verze SqlPackage.

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

Aktualizace balíčku SqlPackage v agentu kanálu

V některých scénářích nemusí být aktuální verze SqlPackage nainstalovaná v prostředí kanálu dostatečná. Pokud prostředí nejde přímo upravit, můžete během spuštění kanálu použít další krok k instalaci novější verze SqlPackage. Před spuštěním jakýchkoli operací DacPac nebo BacPac v potrubí je důležité spustit krok instalace. Tuto úlohu je možné kombinovat s krokem, který zkontroluje verzi , aby se zajistilo, že upgrade byl dokončen podle očekávání.

Azure Pipelines, agent založený na Windows

Když se úloha PowerShellu použije v kanálu Azure, můžete do kanálu Azure přidat krok, který stáhne požadovaný instalační program DacFx a nainstaluje ho bezobslužně.

- 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, Spouštěč založený na Linuxu

V pracovním postupu akce GitHubu můžete pomocí klíčového slova spustit příkazy pro instalaci, odinstalaci nebo aktualizaci SqlPackage. Následující příklad ukazuje, jak aktualizovat SqlPackage na nejnovější verzi Preview:

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

Samo-hostovaná virtuální prostředí

V místním virtuálním prostředí, jako je agent Azure DevOps v místním prostředí nebo spouštěč GitHub Actions, můžete sqlPackage nainstalovat do hostitelského prostředí nebo nainstalovat SqlPackage za běhu, jak je popsáno ve spravovaných virtuálních prostředích. Pokud nainstalujete SqlPackage do hostitelského prostředí, kanály, které běží na daném hostiteli, nemusí za běhu instalovat SqlPackage, což může urychlit spuštění kanálu. Pokud je sqlPackage nainstalovaný na hostiteli, měli byste sqlPackage pravidelně aktualizovat , aby se prostředí udržovalo s nejnovější verzí.

Úlohy Azure Container Apps je možné použít k nasazení spouštěčů v místním prostředí v kontejneru, který je nasazený podle potřeby pro vyvolání jednotlivých pracovních postupů. Pomocí úloh Container Apps řídíte prostředí definované v souboru Dockerfile a podle potřeby nainstalujete SqlPackage a další nástroje. Spouštěč v místním prostředí je možné nakonfigurovat tak, aby běžel na konkrétní verzi sqlPackage, a to zahrnutím kroku instalace do image kontejneru. Například kurz obsahuje soubor Dockerfile, který nainstaluje curl a jq.

Tento příklad můžeme upravit tak, aby se vytvořila image kontejneru, která nainstaluje .NET 8.0 a 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"]

Sledování nasazení

Můžete získat některé soubory související s SqlPackage, abyste mohli znovuvytvořit kanály a zlepšit sledování nasazení. Případy implementace a použití závisí na konkrétní architektuře a prostředí automatizace.

• Soubor Dacpac

• Výstup diagnostického souboru z jakékoli akce: Použijte parametr pro libovolnou /DiagnosticsFile: akci SqlPackage. Další informace najdete v tématu Získání diagnostiky SqlPackage v agentovi pipeline.

• Výstup z akce skriptu před akcí publikování: Před vyvoláním akce publikování použijte akci Script SqlPackage.

Získání diagnostiky SqlPackage v agentu kanálu

Diagnostické informace z SqlPackage jsou k dispozici v příkazovém řádku prostřednictvím parametru /DiagnosticsFile, který lze použít ve virtuálních prostředích, jako jsou Azure Pipelines a GitHub Actions. Diagnostické informace se zapisuje do souboru v pracovním adresáři. Název souboru je diktován parametrem /DiagnosticsFile .

Kanály Azure

Přidání parametru /DiagnosticsFile do pole Další argumenty SqlPackage v konfiguraci Azure Pipeline SqlAzureDacpacDeployment způsobí zápis diagnostických informací SqlPackage do zadaného souboru. Po úloze SqlAzureDacpacDeployment je diagnostický soubor dostupný mimo virtuální prostředí publikováním artefaktu kanálu, jak je vidět v následujícím příkladu.

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

Po běhu pipeline můžete stáhnout diagnostický soubor ze stránky souhrnu běhu v části Publikované artefakty.

Akce na GitHubu

Přidání parametru /DiagnosticsFile do pole Argumenty v konfiguraci akce sql-action GitHubu způsobí zápis diagnostických informací SqlPackage do zadaného souboru. Po úloze akce SQL lze diagnostický soubor zpřístupnit mimo virtuální prostředí publikováním artefaktu, jak je vidět v následujícím příkladu.

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

Související obsah

• sqlpackage
• kurz : Vytvoření a nasazení projektu SQL