SqlPackage in ontwikkelingspijplijnen

SqlPackage is een opdrachtregelprogramma dat verschillende databaseontwikkelingstaken automatiseert en kan worden opgenomen in CI/CD-pijplijnen.

Als SqlPackage is geïnstalleerd als een globaal dotnet-hulpprogramma (aanbevolen), kunt u het aanroepen in de pijplijn met eenvoudigweg sqlpackage vanuit elke map. Als SqlPackage is geïnstalleerd als zelfstandig uitvoerbaar bestand, moet u het volledige pad naar het uitvoerbare bestand in de pijplijn opgeven. In Windows is de zelfstandige installatie van SqlPackage beschikbaar op het pad C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Als u in zowel Windows- als Linux-omgevingen de zelfstandige .zip SqlPackage voor .NET downloadt, kunt u het uitvoerbare bestand extraheren naar een locatie van uw keuze.

Beheerde virtuele omgevingen

De virtuele omgevingen die worden gebruikt voor door GitHub Actions gehoste runners en installatiekopieën van virtuele Azure Pipelines-machines worden beheerd in de GitHub-opslagplaats met runner-images . SqlPackage is opgenomen in verschillende omgevingen, waaronder windows-latest en ubuntu-22.04, maar is niet meer standaard opgenomen in ubuntu-24.04 en ubuntu-latest. Updates voor de afbeeldingen in runner-images worden binnen enkele weken na elke SqlPackage-release doorgevoerd.

In een beheerde virtuele omgeving installeert u SqlPackage tijdens runtime in de pijplijn. De installatie wordt uitgevoerd als een afzonderlijke stap in Azure Pipelines en GitHub Actions en voegt een korte vertraging toe aan elke pijplijnuitvoering terwijl de installatie plaatsvindt. Als u SqlPackage tijdens runtime wilt installeren, voegt u een stap toe aan de pijplijn die de dotnet CLI gebruikt om SqlPackage te installeren als een globaal hulpprogramma. Deze stap moet worden uitgevoerd voordat sqlPackage-acties in de pijplijn worden uitgevoerd.

dotnet tool install --global Microsoft.SqlPackage

Mogelijk moet u een .NET-installatiestap uitvoeren in de pijplijn voordat u SqlPackage installeert, aangegeven door een foutbericht waarin staat dat .NET niet kan worden gevonden. Gebruik een geïntegreerde actie om deze te configureren, zoals de UseDotNet-taak in Azure Pipelines of de actie setup-dotnet in GitHub Actions.

U kunt desgewenst een versie van SqlPackage opgeven die u wilt installeren door deze --version <version> toe te voegen aan de installatieopdracht of u kunt de --prerelease vlag gebruiken om een preview-versie te installeren.

Voorbeeld: Stappen voor het installeren van SqlPackage in Azure DevOps Pipelines

In Azure DevOps Pipelines kunt u de UseDotNet-taak gebruiken om de .NET SDK te installeren en vervolgens SqlPackage te installeren als een globaal hulpprogramma. Als u een Windows-agent van Microsoft gebruikt, is SqlPackage al geïnstalleerd in C:\Program Files\Microsoft SQL Server\170\DAC\bin. Als u een zelf-hostende agent gebruikt, kunt u sqlPackage ook installeren in de hostomgeving en deze stap in de pijplijn overslaan.

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

Voorbeeld: Stappen voor het installeren van SqlPackage in GitHub Actions

In GitHub Actions kunt u de setup-dotnet-actie gebruiken om de .NET SDK te installeren en vervolgens SqlPackage te installeren als een globaal hulpprogramma. Als u een Windows-runner gebruikt die wordt geleverd door GitHub, is SqlPackage al geïnstalleerd in C:\Program Files\Microsoft SQL Server\170\DAC\bin. Als u een zelfgehoste runner gebruikt, kunt u SqlPackage ook op de hostomgeving installeren en deze stap in de workflow overslaan.

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

De SqlPackage-versie controleren

Tijdens het oplossen van problemen is het belangrijk om te weten dat de SqlPackage-versie wordt gebruikt. U kunt deze informatie vastleggen door een stap toe te voegen aan de pijplijn om SqlPackage uit te voeren met de /version parameter. In dit artikel worden voorbeelden gegeven op basis van de door Azure DevOps en GitHub beheerde omgevingen, kunnen zelf-hostende omgevingen verschillende installatiepaden hebben voor de werkmap.

Azure-pipelines

In een Azure Pipeline retourneert het scriptwoord het sqlPackage-versienummer.

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

GitHub Actions (GitHub-acties)

In een GitHub Action-werkstroom retourneert het trefwoord uitvoeren het sqlPackage-versienummer.

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

SqlPackage bijwerken op de pijplijnagent

In sommige scenario's is de huidige versie van SqlPackage die is geïnstalleerd in de pijplijnomgeving mogelijk onvoldoende. Als de omgeving niet rechtstreeks kan worden gewijzigd, kan er een extra stap worden gebruikt om een nieuwere versie van SqlPackage te installeren tijdens de pijplijnuitvoering. Het is belangrijk om de installatiestap uit te voeren voordat u DacPac- of BacPac-bewerkingen uitvoert in de pijplijn. Deze taak kan worden gecombineerd met een stap om de versie te controleren om ervoor te zorgen dat de upgrade is voltooid zoals verwacht.

Azure Pipelines, op Windows gebaseerde agent

Wanneer de PowerShell-taak wordt gebruikt in een Azure-pijplijn, kan een stap worden toegevoegd aan een Azure-pijplijn waarmee het gewenste DacFx-installatieprogramma wordt gedownload en op de achtergrond wordt geïnstalleerd.

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

In een GitHub Action-werkstroom kunt u het trefwoord Uitvoeren gebruiken om de dotnet tool opdrachten uit te voeren om SqlPackage te installeren, te verwijderen of bij te werken. In het volgende voorbeeld ziet u hoe u SqlPackage bijwerkt naar de nieuwste preview-versie:

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

Zelf-hostende virtuele omgevingen

In een zelf-hostende virtuele omgeving, zoals een zelf-hostende Azure DevOps-agent of GitHub Actions-runner, kunt u SqlPackage installeren in de hostomgeving of SqlPackage tijdens runtime installeren, zoals beschreven in beheerde virtuele omgevingen. Als u SqlPackage installeert in de hostomgeving, hoeven pijplijnen die op die host worden uitgevoerd, SqlPackage niet tijdens runtime te installeren, waardoor de pijplijnuitvoeringen sneller kunnen worden uitgevoerd. Wanneer SqlPackage op de host is geïnstalleerd, moet u SqlPackage regelmatig bijwerken om de omgeving te onderhouden met de nieuwste versie.

Azure Container Apps-taken kunnen worden gebruikt voor het implementeren van zelfgehoste runners in een container die naar behoefte wordt ingezet voor elke aanroep van de werkstroom. Met Container Apps-taken bepaalt u de omgeving zoals gedefinieerd in de Dockerfile en installeert u zo nodig SqlPackage en andere hulpprogramma's. De zelfgehoste runner kan worden geconfigureerd om te draaien op een specifieke versie van SqlPackage door de installatiestap toe te voegen aan de containerimage. De zelfstudie bevat bijvoorbeeld een Dockerfile die curl en jq installeert.

We kunnen dit voorbeeld wijzigen om een containerinstallatiekopieën te produceren die .NET 8.0 en SqlPackage installeert:

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

Implementaties bijhouden

U kunt enkele bestanden met betrekking tot SqlPackage vastleggen om pijplijnen te reproduceren en het bijhouden van implementaties te verbeteren. De implementatie en use cases zijn afhankelijk van uw specifieke architectuur en automatiseringsomgeving.

• Dacpac-bestand

• Uitvoer van diagnostische bestanden van een actie: Gebruik de /DiagnosticsFile: parameter voor een SqlPackage-actie. Zie Diagnostische gegevens van SqlPackage ophalen in een pijplijnagent voor meer informatie

• Uitvoer van scriptactie vóór publicatieactie: Gebruik de actie Script SqlPackage voordat u een publicatieactie aanroept

Diagnostische gegevens van SqlPackage ophalen in een pijplijnagent

Diagnostische gegevens van SqlPackage zijn beschikbaar in de opdrachtregel via de parameter /DiagnosticsFile, die kan worden gebruikt in virtuele omgevingen, zoals Azure Pipelines en GitHub Actions. De diagnostische gegevens worden naar een bestand in de werkmap geschreven. De bestandsnaam wordt bepaald door de /DiagnosticsFile parameter.

Azure-pipelines

Als u de /DiagnosticsFile parameter toevoegt aan het veld Aanvullende SqlPackage-argumenten in de configuratie van Azure Pipeline SqlAzureDacpacDeployment, wordt de diagnostische gegevens van SqlPackage naar het opgegeven bestand geschreven. Na de sqlAzureDacpacDeployment-taak is het diagnostische bestand buiten de virtuele omgeving beschikbaar door een pijplijnartefact te publiceren, zoals te zien is in het volgende voorbeeld.

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

Nadat de pijplijn is uitgevoerd, kan het diagnostische bestand worden gedownload vanaf de overzichtspagina van de uitvoering onder 'Gepubliceerde artefacten'.

GitHub Actions (GitHub-acties)

Als u de /DiagnosticsFile parameter toevoegt aan het veld 'argumenten' in de configuratie van GitHub Action sql-action, wordt de diagnostische gegevens van SqlPackage naar het opgegeven bestand geschreven. Na de sql-action-taak kan het diagnostische bestand buiten de virtuele omgeving beschikbaar worden gesteld door een artefact te publiceren, zoals te zien is in het volgende voorbeeld.

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

Verwante inhoud

• SqlPackage
• Zelfstudie: Een SQL-project maken en implementeren