SqlPackage i utvecklingsflödena

SqlPackage är ett kommandoradsverktyg som automatiserar flera databasutvecklingsuppgifter och kan införlivas i CI/CD-pipelines.

Om SqlPackage installeras som ett globalt dotnet-verktyg (rekommenderas) kan du anropa det i pipelinen med bara sqlpackage från valfri katalog. Om SqlPackage installeras som en fristående körbar fil måste du ange den fullständiga sökvägen till den körbara filen i pipelinen. I Windows är den fristående installationen av SqlPackage tillgänglig på sökvägen C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). Om du laddar ned den fristående .zip SqlPackage för .NET i både Windows- och Linux-miljöer kan du extrahera den körbara filen till en plats som du väljer.

Hanterade virtuella miljöer

De virtuella miljöer som används för värdbaserade GitHub Actions-agenter och virtuella Azure Pipelines-bilder hanteras i GitHub-lagringsplatsen runner-images. SqlPackage ingår i flera miljöer, inklusive windows-latest och ubuntu-22.04 men ingår inte längre som standard i ubuntu-24.04 och ubuntu-latest. Uppdateringar av bilderna i runner-images görs inom några veckor efter varje SqlPackage-version.

I en hanterad virtuell miljö skulle du installera SqlPackage vid körning i pipelinen. Installationen utförs som ett separat steg i antingen Azure Pipelines och GitHub Actions och lägger till en kort fördröjning för varje pipelinekörning under installationen. Om du vill installera SqlPackage vid körning lägger du till ett steg i pipelinen som använder dotnet CLI för att installera SqlPackage som ett globalt verktyg. Det här steget bör köras innan sqlpackage-åtgärder i pipelinen.

dotnet tool install --global Microsoft.SqlPackage

Du kan behöva utföra ett .NET-installationssteg i pipelinen innan du installerar SqlPackage, vilket anges av ett felmeddelande om att .NET inte kan hittas. Använd en integrerad åtgärd för att konfigurera den, till exempel UseDotNet-aktiviteten i Azure Pipelines eller åtgärden setup-dotnet i GitHub Actions.

Du kan också ange en version av SqlPackage som ska installeras genom att lägga --version <version> till installationskommandot eller använda --prerelease flaggan för att installera en förhandsversion.

Exempel: Steg för att installera SqlPackage i Azure DevOps Pipelines

I Azure DevOps Pipelines kan du använda uppgiften UseDotNet för att installera .NET SDK och sedan installera SqlPackage som ett globalt verktyg. Om du använder en Windows-agent från Microsoft är SqlPackage redan installerat i C:\Program Files\Microsoft SQL Server\170\DAC\bin. Om du använder en lokalt installerad agent kan du även installera SqlPackage i värdmiljön och hoppa över det här steget i pipelinen.

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

Exempel: Steg för att installera SqlPackage i GitHub Actions

I GitHub Actions kan du använda åtgärden setup-dotnet för att installera .NET SDK och sedan installera SqlPackage som ett globalt verktyg. Om du använder en Windows-löpare från GitHub är SqlPackage redan installerat i C:\Program Files\Microsoft SQL Server\170\DAC\bin. Om du använder en lokalt installerad löpare kan du även installera SqlPackage i värdmiljön och hoppa över det här steget i arbetsflödet.

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

Kontrollera SqlPackage-versionen

Under felsökningen är det viktigt att veta att SqlPackage-versionen används. Du kan samla in den här informationen genom att lägga till ett steg i pipelinen för att köra SqlPackage med parametern /version . Exempel ges i den här artikeln baserat på azure DevOps- och GitHub-hanterade miljöer. Lokalt installerade miljöer kan ha olika installationsvägar för arbetskatalogen.

Azure-pipelines

I en Azure Pipeline returnerar skriptnyckelordet versionsnumret för SqlPackage.

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

GitHub Actions (verktyg för arbetsflöden)

I ett GitHub Action-arbetsflöde returnerar körningsnyckelordet versionsnumret för SqlPackage.

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

Uppdatera SqlPackage på pipelineagenten

I vissa scenarier kan den aktuella versionen av SqlPackage som är installerad i pipelinemiljön vara otillräcklig. Om miljön inte kan ändras direkt kan ett extra steg användas för att installera en nyare version av SqlPackage under pipelinekörningen. Det är viktigt att köra installationssteget innan du kör DacPac- eller BacPac-åtgärder i pipelinen. Den här uppgiften kan kombineras med ett steg för att kontrollera versionen för att säkerställa att uppgraderingen slutfördes som förväntat.

Azure Pipelines, Windows-baserad agent

När PowerShell-uppgiften används i en Azure Pipeline kan du lägga till ett steg i en Azure Pipeline som laddar ned det önskade DacFx-installationsprogrammet och installerar det tyst.

- 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-baserad körare

I ett GitHub Action-arbetsflöde kan du använda nyckelordet kör för att köra dotnet tool kommandona för att installera, avinstallera eller uppdatera SqlPackage. I följande exempel visas hur du uppdaterar SqlPackage till den senaste förhandsversionen:

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

Virtuella miljöer med egen värd

I en lokalt installerad virtuell miljö, till exempel en lokalt installerad Azure DevOps-agent eller GitHub Actions-löpare, kan du installera SqlPackage i värdmiljön eller installera SqlPackage vid körning enligt beskrivningen i hanterade virtuella miljöer. Om du installerar SqlPackage i värdmiljön behöver pipelines som körs på den värden inte installera SqlPackage vid körning, vilket kan påskynda pipelinekörningarna. När SqlPackage har installerats på värden bör du uppdatera SqlPackage regelbundet för att hålla miljön uppdaterad med den senaste versionen.

Azure Container Apps-jobb kan användas för att distribuera lokalt installerade löpare i en container som distribueras efter behov för varje arbetsflödesanrop. Med Container Apps-jobb styr du miljön enligt definitionen i Dockerfile och installerar SqlPackage och andra verktyg efter behov. Den lokalt självhostade arbetsmotorn kan konfigureras att köras på en specifik version av SqlPackage genom att inkludera installationsprocessen i containerbilden. Självstudien innehåller till exempel en Dockerfile som installerar curl och jq.

Vi kan ändra det här exemplet för att skapa en containeravbildning som installerar .NET 8.0 och 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"]

Spåra utplaceringar

Du kan samla in vissa filer som är relaterade till SqlPackage för att återskapa pipelines och förbättra distributionsspårningen. Implementerings- och användningsfallen beror på din specifika arkitektur och automatiseringsmiljö.

• Dacpac-fil

• Diagnostikfilutdata från valfri åtgärd: Använd parametern för /DiagnosticsFile: valfri SqlPackage-åtgärd. Mer information finns i Hämta SqlPackage-diagnostik i en pipelineagent

• Utdata från skriptåtgärden före publiceringsåtgärden: Använd åtgärden Script SqlPackage innan du anropar en publiceringsåtgärd

Hämta SqlPackage-diagnostik i en pipelineagent

Diagnostikinformation från SqlPackage finns på kommandoraden via parametern /DiagnosticsFile, som kan användas i virtuella miljöer som Azure Pipelines och GitHub Actions. Diagnostikinformationen skrivs till en fil i arbetskatalogen. Filnamnet styrs av parametern /DiagnosticsFile .

Azure-pipelines

Om du lägger till parametern /DiagnosticsFile i fältet "Ytterligare SqlPackage-argument" i Azure Pipeline SqlAzureDacpacDeployment-konfigurationen skrivs diagnostikinformationen för SqlPackage till den angivna filen. Efter SqlAzureDacpacDeployment-uppgiften blir diagnostikfilen tillgänglig utanför den virtuella miljön genom att publicera en pipeline-artifakt, enligt följande exempel.

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

Efter pipelinekörningen kan diagnostikfilen laddas ned från körningssammanfattningssidan under "Publicerade artefakter".

GitHub Actions (verktyg för arbetsflöden)

Om du lägger till parametern /DiagnosticsFile i fältet "argument" i sql-actionkonfigurationen för GitHub Action skrivs sqlPackage-diagnostikinformationen till den angivna filen. Efter sql-action-uppgiften kan diagnostikfilen göras tillgänglig utanför den virtuella miljön genom att publicera en artefakt enligt följande exempel.

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

Relaterat innehåll

• SqlPackage
• Självstudie: Skapa och distribuera ett SQL-projekt