Condividi tramite

SqlPackage nelle pipeline di sviluppo

SqlPackage è un'utilità della riga di comando che automatizza diverse attività di sviluppo di database e può essere incorporata nelle pipeline CI/CD.

Nota

È consigliabile usare un'installazione autonoma di SqlPackage per l'automazione della pipeline anziché utilizzare i file eseguibili SqlPackage in bundle con altre applicazioni, tra cui SQL Server Management Studio o Visual Studio. L'installazione autonoma di SqlPackage viene aggiornata più frequentemente e non è associata alla frequenza di rilascio di altre applicazioni.

Se SqlPackage è installato come strumento dotnet globale (scelta consigliata), è possibile richiamarlo nella pipeline semplicemente sqlpackage da qualsiasi directory. Se SqlPackage è installato come eseguibile autonomo, è necessario specificare il percorso completo del file eseguibile nella pipeline. In Windows l'installazione autonoma di SqlPackage è disponibile nel percorso C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). In entrambi gli ambienti Windows e Linux, se si scarica l'.zip SqlPackage autonomo per .NET, è possibile estrarre il file eseguibile in un percorso scelto.

Ambienti virtuali gestiti

Gli ambienti virtuali utilizzati per i runner ospitati di GitHub Actions e le immagini delle macchine virtuali di Azure Pipelines sono gestiti nel repository GitHub runner-images. SqlPackage è incluso in diversi ambienti, tra cui windows-latest e , ubuntu-22.04 ma non è più incluso per impostazione predefinita in ubuntu-24.04 e ubuntu-latest. Gli aggiornamenti delle immagini in runner-images vengono eseguiti entro poche settimane da ogni rilascio di SqlPackage.

In un ambiente virtuale gestito si installerebbe SqlPackage in fase di esecuzione nella pipeline. L'installazione viene eseguita come passaggio separato in Azure Pipelines e GitHub Actions e aggiunge un breve ritardo a ogni esecuzione della pipeline durante l'installazione. Per installare SqlPackage in fase di esecuzione, aggiungere un passaggio alla pipeline che usa l'interfaccia della riga di comando dotnet per installare SqlPackage come strumento globale. Questo passaggio deve essere eseguito prima di qualsiasi azione SqlPackage nella pipeline.

dotnet tool install --global Microsoft.SqlPackage

Potrebbe essere necessario eseguire un passaggio di installazione di .NET nella pipeline prima di installare SqlPackage, indicato da un messaggio di errore che informa che .NET non è stato trovato. Usare un'azione integrata per configurarla, ad esempio l'attività UseDotNet in Azure Pipelines o l'azione setup-dotnet in GitHub Actions.

Facoltativamente, è possibile specificare una versione di SqlPackage da installare aggiungendo --version <version> al comando di installazione oppure è possibile usare il --prerelease flag per installare una versione di anteprima.

Esempio: Passaggi per installare SqlPackage nelle pipeline di Azure DevOps

In Azure DevOps Pipelines è possibile usare l'attività UseDotNet per installare .NET SDK e quindi installare SqlPackage come strumento globale. Se si usa un agente Windows fornito da Microsoft, SqlPackage è già installato in C:\Program Files\Microsoft SQL Server\170\DAC\bin. Se si usa un agente self-hosted, è anche possibile installare SqlPackage nell'ambiente host e ignorare questo passaggio nella 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'

Esempio: Passaggi per installare SqlPackage in GitHub Actions

In GitHub Actions è possibile usare l'azione setup-dotnet per installare .NET SDK e quindi installare SqlPackage come strumento globale. Se si usa uno strumento di esecuzione di Windows fornito da GitHub, SqlPackage è già installato in C:\Program Files\Microsoft SQL Server\170\DAC\bin. Se si usa uno strumento di esecuzione self-hosted, è anche possibile installare SqlPackage nell'ambiente host e ignorare questo passaggio nel flusso di lavoro.

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

Controllare la versione di SqlPackage

Durante la risoluzione dei problemi, è importante conoscere la versione di SqlPackage in uso. L'acquisizione di queste informazioni può essere eseguita aggiungendo un passaggio alla pipeline per eseguire SqlPackage con il parametro /version. Gli esempi sono riportati in questo articolo in base agli ambienti gestiti di Azure DevOps e GitHub, gli ambienti self-hosted potrebbero avere percorsi di installazione diversi per la directory di lavoro.

Azure Pipelines

In una Azure Pipeline la parola chiave script restituisce il numero di versione di SqlPackage.

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

Azioni di GitHub

In un flusso di lavoro di GitHub Action la parola chiave esegui restituisce il numero di versione di SqlPackage.

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

Output dell'azione di GitHub che visualizza il numero di build 15.0.4897.1

Aggiornare SqlPackage nell'agente della pipeline

In alcuni scenari, la versione corrente di SqlPackage installata nell'ambiente della pipeline potrebbe non essere sufficiente. Se l'ambiente non può essere modificato direttamente, è possibile usare un passaggio aggiuntivo per installare una versione più recente di SqlPackage durante l'esecuzione della pipeline. È importante eseguire il passaggio di installazione prima di eseguire operazioni DacPac o BacPac nella pipeline. Questa attività può essere combinata con un passaggio per controllare la versione e fare in modo che l'aggiornamento venga completato come previsto.

Azure Pipelines, agente basato su Windows

Quando l'attività di PowerShell viene usata in una pipeline di Azure, è possibile aggiungere un passaggio a una pipeline di Azure che scarica il programma di installazione di DacFx desiderato e lo installa automaticamente.

- 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, strumento di esecuzione basato su Linux

In un flusso di lavoro di GitHub Action è possibile usare la parola chiave run per eseguire i dotnet tool comandi per installare, disinstallare o aggiornare SqlPackage. L'esempio seguente illustra come aggiornare SqlPackage alla versione di anteprima più recente:

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

Ambienti virtuali autogestiti

In un ambiente virtuale self-hosted, ad esempio un agente Azure DevOps self-hosted o gitHub Actions runner, è possibile installare SqlPackage nell'ambiente host o installare SqlPackage in fase di esecuzione, come descritto in ambienti virtuali gestiti. Se si installa SqlPackage nell'ambiente host, le pipeline eseguite in tale host non devono installare SqlPackage in fase di esecuzione, in modo da velocizzare le esecuzioni della pipeline. Quando SqlPackage è installato nell'host, è necessario aggiornare regolarmente SqlPackage per mantenere l'ambiente con la versione più recente.

I job di Azure Container Apps possono essere usati per distribuire runner self-hosted in un contenitore distribuito secondo le esigenze per ciascuna invocazione del flusso di lavoro. Con i processi di App contenitore, è possibile controllare l'ambiente come definito nel Dockerfile e installare SqlPackage e altri strumenti in base alle esigenze. Il runner self-hosted può essere configurato per l'esecuzione su una versione specifica di SqlPackage includendo il passaggio dell'installazione nell'immagine del container. Ad esempio, il tutorial include un file Docker che installa curl e jq.

È possibile modificare questo esempio per produrre un'immagine del contenitore che installa .NET 8.0 e 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"]

Tenere traccia delle distribuzioni

È possibile acquisire alcuni file correlati a SqlPackage per riprodurre le pipeline e migliorare il rilevamento della distribuzione. I casi d'uso e implementazione dipendono dall'architettura e dall'ambiente di automazione specifici.

  • File Dacpac

  • Output del file di diagnostica da qualsiasi azione: Usare il parametro /DiagnosticsFile: in qualsiasi azione SqlPackage. Per altre informazioni, vedere Ottenere la diagnostica di SqlPackage in un agente della pipeline

  • Output dall'azione di script prima dell'azione di pubblicazione: Usare l'azione Script SqlPackage prima di richiamare un'azione di pubblicazione

Ottenere la diagnostica di SqlPackage in un agente della pipeline

Le informazioni di diagnostica di SqlPackage sono disponibili nella riga di comando tramite il parametro /DiagnosticsFile, che può essere usato negli ambienti virtuali, ad esempio Azure Pipelines e GitHub Actions. Le informazioni di diagnostica sono scritte in un file nella directory di lavoro. Il nome del file viene dettato dal parametro /DiagnosticsFile.

Azure Pipelines

L'aggiunta del /DiagnosticsFile parametro al campo "Argomenti sqlPackage aggiuntivi" nella configurazione di SqlAzureDacpacDeployment della pipeline di Azure determina la scrittura delle informazioni di diagnostica di SqlPackage nel file specificato. Dopo l'attività SqlAzureDacpacDeployment, il file di diagnostica è disponibile all'esterno dell'ambiente virtuale pubblicando un artefatto della pipeline come illustrato nell'esempio seguente.

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

Dopo l'esecuzione della pipeline, il file diagnostico può essere scaricato dalla pagina di riepilogo dell'esecuzione della pipeline sotto "Artefatti pubblicati".

Azioni di GitHub

L'aggiunta del /DiagnosticsFile parametro al campo "arguments" nella configurazione sql-action di GitHub Action determina la scrittura delle informazioni di diagnostica di SqlPackage nel file specificato. Dopo l'attività sql-action, il file di diagnostica può essere reso disponibile all'esterno dell'ambiente virtuale pubblicando un artefatto come illustrato nell'esempio seguente.

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

Contenuti correlati

  • Last updated on