Pakiet SqlPackage w potokach programowania

SqlPackage to narzędzie wiersza polecenia, które automatyzuje kilka zadań tworzenia bazy danych i można je włączyć do potoków ciągłej integracji/ciągłego wdrażania.

Uwaga

Korzystanie z autonomicznej instalacji pakietu SqlPackage do automatyzacji procesów w potoku jest zalecane zamiast używania plików wykonywalnych SqlPackage dołączonych do innych aplikacji, w tym programu SQL Server Management Studio lub Visual Studio. Autonomiczna instalacja pakietu SqlPackage jest aktualizowana częściej i nie jest powiązana z cyklem wydawania innych aplikacji.

Jeśli pakiet SqlPackage jest zainstalowany jako globalne narzędzie .NET (zalecane), możesz wywołać go w potoku po prostu za pomocą sqlpackage z dowolnego katalogu. Jeśli pakiet SqlPackage jest zainstalowany jako autonomiczny plik wykonywalny, należy określić pełną ścieżkę do pliku wykonywalnego w potoku. W systemie Windows autonomiczna instalacja pakietu SqlPackage jest dostępna w ścieżce C:\Program Files\Microsoft SQL Server\170\DAC\bin (DacFx.msi). W środowiskach Windows i Linux, jeśli pobierzesz samodzielne .zip SqlPackage dla platformy .NET, możesz wyodrębnić plik wykonywalny do wybranej lokalizacji.

Zarządzane środowiska wirtualne

Środowiska wirtualne używane do uruchamiaczy hostowanych przez GitHub Actions i obrazów maszyn wirtualnych Azure Pipelines są zarządzane w repozytorium GitHub runner-images. Pakiet SqlPackage jest uwzględniony w kilku środowiskach, w tym w systemach windows-latest i ubuntu-22.04 , ale nie jest już dołączany domyślnie w systemach ubuntu-24.04 i ubuntu-latest. Aktualizacje obrazów w runner-images są dokonywane w ciągu kilku tygodni od każdego wydania pakietu SqlPackage.

W zarządzanym środowisku wirtualnym należy zainstalować pakiet SqlPackage w czasie wykonywania w potoku. Instalacja jest wykonywana jako oddzielny krok zarówno w Azure Pipelines, jak i GitHub Actions, co dodaje krótkie opóźnienie do każdego uruchomienia potoku podczas instalacji. Aby zainstalować pakiet SqlPackage w czasie wykonywania, dodaj krok do potoku, który używa interfejsu wiersza polecenia dotnet do zainstalowania pakietu SqlPackage jako narzędzia globalnego. Ten krok powinien zostać uruchomiony przed wszystkimi akcjami SqlPackage w potoku.

dotnet tool install --global Microsoft.SqlPackage

Może być konieczne wykonanie kroku konfiguracji platformy .NET w potoku przed zainstalowaniem narzędzia SqlPackage, co jest sygnalizowane komunikatem o błędzie informującym, że nie można odnaleźć platformy .NET. Użyj zintegrowanej akcji, aby skonfigurować ją, taką jak zadanie UseDotNet w usłudze Azure Pipelines lub akcja setup-dotnet w funkcji GitHub Actions.

Opcjonalnie możesz określić wersję pakietu SqlPackage do zainstalowania, dołączając --version <version> polecenie instalacji lub używając --prerelease flagi do zainstalowania wersji zapoznawczych.

Przykład: kroki instalacji pakietu SqlPackage w potokach usługi Azure DevOps

W usłudze Azure DevOps Pipelines możesz użyć zadania UseDotNet , aby zainstalować zestaw SDK platformy .NET, a następnie zainstalować pakiet SqlPackage jako narzędzie globalne. Jeśli używasz agenta systemu Windows dostarczonego przez firmę Microsoft, pakiet SqlPackage jest już zainstalowany w programie C:\Program Files\Microsoft SQL Server\170\DAC\bin. Jeśli używasz własnego agenta hostowanego lokalnie, możesz również zainstalować pakiet SqlPackage w środowisku hosta i pominąć ten krok w pipeline'u.

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

Przykład: kroki instalacji pakietu SqlPackage w funkcji GitHub Actions

W funkcji GitHub Actions można użyć akcji setup-dotnet , aby zainstalować zestaw SDK platformy .NET, a następnie zainstalować pakiet SqlPackage jako narzędzie globalne. Jeśli używasz modułu uruchamiającego system Windows dostarczonego przez usługę GitHub, pakiet SqlPackage jest już zainstalowany w programie C:\Program Files\Microsoft SQL Server\170\DAC\bin. Jeśli używasz własnego agenta uruchamiającego, możesz również zainstalować narzędzie SqlPackage w środowisku serwera i pominąć ten krok w przepływie pracy.

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

Sprawdzanie wersji pakietu SqlPackage

Podczas rozwiązywania problemów ważne jest, aby wiedzieć, że używana jest wersja pakietu SqlPackage. Przechwytywanie tych informacji można wykonać, dodając krok do potoku, aby uruchomić pakiet SqlPackage za pomocą parametru /version . W tym artykule podano przykłady oparte na środowiskach zarządzanych usług Azure DevOps i GitHub, środowiska samo-hostowane mogą mieć inne ścieżki instalacji dla katalogu roboczego.

Azure Pipelines (narzędzie do automatyzacji procesów w chmurze Azure)

W Azure Pipeline słowo kluczowe script zwraca numer wersji SqlPackage.

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

Działania GitHub

W przepływie pracy akcji usługi GitHub słowo kluczowe run zwraca numer wersji pakietu SqlPackage.

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

Aktualizowanie pakietu SqlPackage na agencie potoku

W niektórych przypadkach obecna wersja SqlPackage zainstalowana w środowisku potokowym może być niewystarczająca. Jeśli środowiska nie można zmodyfikować bezpośrednio, podczas uruchamiania potoku można wykonać dodatkowy krok, aby zainstalować nowszą wersję SqlPackage. Ważne jest, aby uruchomić krok instalacji przed uruchomieniem dowolnych operacji DacPac lub BacPac w potoku. To zadanie można połączyć z krokiem sprawdzania wersji, aby upewnić się, że uaktualnienie zostało ukończone zgodnie z oczekiwaniami.

Azure Pipelines, agent oparty na systemie Windows

Gdy zadanie programu PowerShell jest używane w usłudze Azure Pipeline, można dodać krok do usługi Azure Pipeline, który pobiera żądany instalator DacFx i instaluje go w trybie dyskretnym.

- 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, agent działający na systemie Linux

W przepływie pracy akcjami w usłudze GitHub możesz użyć słowa kluczowego run, aby wykonać polecenia dotnet tool, które umożliwiają zainstalowanie, odinstalowanie lub zaktualizowanie pakietu SqlPackage. W poniższym przykładzie pokazano, jak zaktualizować pakiet SqlPackage do najnowszej wersji zapoznawczej:

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

Środowiska wirtualne hostowane samodzielnie

W środowisku wirtualnym, takim jak własny agent Azure DevOps lub runner GitHub Actions, możesz zainstalować SqlPackage w środowisku hosta lub zainstalować SqlPackage podczas uruchamiania, zgodnie z opisem w zarządzanych środowiskach wirtualnych. Jeśli zainstalujesz narzędzie SqlPackage na hoście, pipeline'y uruchamiane na tym hoście nie muszą instalować SqlPackage podczas działania, co może przyspieszyć uruchamianie pipeline'ów. Po zainstalowaniu pakietu SqlPackage na hoście należy regularnie aktualizować pakiet SqlPackage , aby zachować środowisko przy użyciu najnowszej wersji.

Zadania usługi Azure Container Apps mogą służyć do wdrażania samodzielnie hostowanych środowisk uruchomieniowych w kontenerze, który jest wdrażany zgodnie z potrzebami dla każdego wywołania przepływu pracy. Zadania usługi Container Apps umożliwiają kontrolowanie środowiska zgodnie z definicją w pliku Dockerfile i instalowanie pakietu SqlPackage i innych narzędzi zgodnie z potrzebami. Własny moduł uruchamiający można skonfigurować do uruchamiania w określonej wersji pakietu SqlPackage, włączając krok instalacji w obrazie kontenera. Na przykład samouczek zawiera plik Dockerfile, który instaluje curl i jq.

Możemy zmodyfikować ten przykład, aby utworzyć obraz kontenera, który instaluje platformę .NET 8.0 i pakiet 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"]

Śledzenie wdrożeń

Można przechwycić niektóre pliki związane z SqlPackage, aby zrekonstruować potoki i ulepszyć śledzenie wdrożeń. Implementacja i przypadki użycia zależą od określonej architektury i środowiska automatyzacji.

• Plik Dacpac

• Dane wyjściowe pliku diagnostycznego z dowolnej akcji: Użyj parametru /DiagnosticsFile: w dowolnej akcji SqlPackage. Aby uzyskać więcej informacji, zobacz Get SqlPackage diagnostics in a pipeline agent (Uzyskiwanie diagnostyki pakietu SqlPackage w agencie potoku)

• Dane wyjściowe akcji skryptu przed opublikowaniem: Użyj akcji Skrypt SqlPackage przed wywołaniem akcji publikacji

Uzyskaj diagnostykę SqlPackage w agencie potoku danych

Informacje diagnostyczne z pakietu SqlPackage są dostępne w wierszu polecenia za pośrednictwem parametru /DiagnosticsFile, który może być używany w środowiskach wirtualnych, takich jak Azure Pipelines i GitHub Actions. Informacje diagnostyczne są zapisywane w pliku w katalogu roboczym. Nazwa pliku jest określana przez /DiagnosticsFile parametr .

Azure Pipelines (narzędzie do automatyzacji procesów w chmurze Azure)

Dodanie parametru /DiagnosticsFile do pola "Dodatkowe argumenty sqlPackage" w konfiguracji SqlAzureDacpacDeployment usługi Azure Pipeline powoduje zapisanie informacji diagnostycznych sqlPackage do określonego pliku. Po wykonaniu zadania SqlAzureDacpacDeployment plik diagnostyczny jest dostępny poza środowiskiem wirtualnym poprzez publikację artefaktu potoku, jak pokazano w poniższym przykładzie.

- 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 uruchomieniu potoku plik diagnostyczny można pobrać ze strony podsumowania przebiegu w obszarze "Opublikowane artefakty".

Działania GitHub

Dodanie parametru /DiagnosticsFile do pola "argumenty" w konfiguracji sql-action akcji usługi GitHub powoduje zapisanie informacji diagnostycznych sqlPackage do określonego pliku. Po zadaniu sql-action plik diagnostyczny można udostępnić poza środowiskiem wirtualnym, publikując artefakt, jak pokazano w poniższym przykładzie.

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

Treści powiązane

• SqlPackage
• Samouczek: tworzenie i wdrażanie projektu SQL