SqlPackage in Entwicklungspipelines

sqlPackage ist ein Befehlszeilenhilfsprogramm, das verschiedene Aufgaben bei der Datenbankentwicklung automatisiert und in CI/CD-Pipelines integriert werden kann.

Virtuelle Umgebungen

Hinweis

Die Verwendung einer eigenständigen Installation von SqlPackage für die Pipelineautomatisierung wird gegenüber der Verwendung der ausführbaren SqlPackage-Dateien empfohlen, die mit anderen Anwendungen gebündelt sind, einschließlich SQL Server Management Studio oder Visual Studio. Die eigenständige Installation von SqlPackage wird häufiger aktualisiert und ist nicht an den Releaserhythmus anderer Anwendungen gebunden.

Unter Windows ist die eigenständige Installation von SqlPackage im Pfad C:\Program Files\Microsoft SQL Server\160\DAC\bin (DacFx.msi) oder %USERPROFILE%\.dotnet\tools (dotnet-Tool) verfügbar. Unter Linux ist die eigenständige Installation von SqlPackage im Pfad ~/.dotnet/tools (dotnet-Tool) verfügbar. Wenn Sie sowohl in Windows- als auch in Linux-Umgebungen das eigenständige ZIP-SqlPackage für .NET Core herunterladen, können Sie die ausführbare Datei in einen Speicherort Ihrer Wahl extrahieren.

Verwaltete virtuelle Umgebungen

Die Verwaltung der virtuellen Umgebungen, die für die von GitHub Actions gehosteten Runner und Azure Pipelines-VM-Images verwendet werden, erfolgt im GitHub-Repository runner-images. SqlPackage ist in verschiedenen Umgebungen enthalten, darunter auch in windows-latest und ubuntu-latest. Aktualisierungen der Images in runner-images werden innerhalb weniger Wochen nach jedem neuen SqlPackage-Release durchgeführt.

Selbstgehostete virtuelle Umgebungen

Wenn Sie SqlPackage in einer selbstgehosteten virtuellen Umgebung nutzen, beispielsweise auf einem selbstgehosteten Azure DevOps-Agent, wird eine regelmäßige Aktualisierung der Anwendung empfohlen, um für die Umgebung immer die neueste Version zu verwenden.

Nachverfolgen von Bereitstellungen

Es gibt einige Dateien im Zusammenhang mit SqlPackage, die als Pipelineartefakte erfasst werden können, um reproduzierbare Pipelineausführungen zu erstellen und die Bereitstellungsnachverfolgung zu verbessern. Implementierung und Anwendungsfälle variieren je nach Ihrer spezifischen Architektur und Automatisierungsumgebung.

• DACPAC-Datei
• Diagnosedateiausgabe einer beliebigen Aktion: Verwenden Sie den Parameter /DiagnosticsFile: für eine beliebige SqlPackage-Aktion (siehe Beispiel unten)
• Ausgabe der Skriptaktion vor der Veröffentlichungsaktion: Verwenden Sie die SqlPackage-Skriptaktion vor dem Aufrufen einer Veröffentlichungsaktion.

Weitere SqlPackage-Beispiele

Überprüfen der Version von SqlPackage

Während der Problembehandlung ist es wichtig zu wissen, welche Version von SqlPackage verwendet wird. Die Erfassung dieser Informationen kann durch Hinzufügen eines Schritts zur Pipeline erfolgen, durch den SqlPackage mit dem Parameter /version ausgeführt wird. Im Folgenden finden Sie Beispiele, die auf den von Microsoft und GitHub verwalteten Umgebungen basieren. Selbst gehostete Umgebungen können unterschiedliche Installationspfade für das Arbeitsverzeichnis haben.

Azure Pipelines

Durch Nutzung des Schlüsselworts script in einer Azure-Pipeline kann dieser ein Schritt hinzugefügt werden, der die Versionsnummer von SqlPackage liefert.

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

GitHub Actions

Durch Nutzung des Schlüsselworts run in einem GitHub Actions-Workflow kann einer GitHub-Aktion ein Schritt hinzugefügt werden, der die Versionsnummer von SqlPackage liefert.

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

Abrufen der SqlPackage-Diagnose in einem Pipeline-Agent

Diagnoseinformationen von SqlPackage sind in der Befehlszeile über den Parameter /DiagnosticsFile verfügbar, der in virtuellen Umgebungen wie Azure Pipelines und GitHub verwendet werden kann. Die Diagnoseinformationen werden in eine Datei im Arbeitsverzeichnis geschrieben. Der Dateiname wird durch den /DiagnosticsFile-Parameter bestimmt.

Azure Pipelines

Wenn Sie den Parameter /DiagnosticsFile dem Feld „Zusätzliche SqlPackage-Argumente“ in der Azure Pipeline-Konfiguration „SqlAzureDacpacDeployment“ hinzufügen, werden die SqlPackage-Diagnoseinformationen in die angegebene Datei geschrieben. Nach der SqlAzureDacpacDeployment-Aufgabe kann die Diagnosedatei außerhalb der virtuellen Umgebung verfügbar gemacht werden, indem ein Pipelineartefakt veröffentlicht wird, wie im folgenden Beispiel gezeigt.

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

Nach der Ausführung der Pipeline kann die Diagnosedatei von der Ausführungszusammenfassungsseite unter „Veröffentlichte Artefakte“ heruntergeladen werden.

GitHub-Aktionen

Das Hinzufügen des /DiagnosticsFile-Parameters zum Feld „arguments“ in der Konfiguration der GitHub-Aktion „sql-action“ bewirkt, dass die SqlPackage-Diagnoseinformationen in die angegebene Datei geschrieben werden. Nach der sql-action-Aufgabe kann die Diagnosedatei außerhalb der virtuellen Umgebung verfügbar gemacht werden, indem ein Pipelineartefakt veröffentlicht wird, wie im folgenden Beispiel gezeigt.

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

Aktualisieren von SqlPackage für den Pipeline-Agent

In manchen Szenarios reicht die aktuelle in der Pipelineumgebung installierte Version von SqlPackage möglicherweise nicht aus. Wenn die Umgebung nicht direkt geändert werden kann, ist es über einen zusätzlichen Schritt während der Pipelineausführung möglich, eine neuere Version von SqlPackage zu installieren. Es ist wichtig, den Installationsschritt vor der Ausführung von DacPac- oder BacPac-Vorgängen in der Pipeline auszuführen. Diese Aufgabe kann mit einem Schritt kombiniert werden, bei dem die Version überprüft wird, um sicherzustellen, dass das Upgrade erwartungsgemäß abgeschlossen wurde.

Azure Pipelines

Durch Verwendung des PowerShell-Tasks in einer Azure-Pipeline kann dieser ein Schritt hinzugefügt werden, mit dem die gewünschte MSI-Datei heruntergeladen und im Hintergrund installiert wird.

- 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

Nächste Schritte

• Weitere Informationen zu SqlPackage