Freigeben über

Konvertieren eines ursprünglichen SQL-Projekts in ein SDK-Projekt

  • Artikel

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance

Das Erstellen eines neuen SQL-Projekts im SDK-Stil ist eine schnelle Aufgabe. Wenn Sie jedoch über vorhandene SQL-Projekte verfügen, können Sie sie in SQL-Projekte im SDK-Stil konvertieren, um die neuen Features nutzen zu können.

Nachdem Sie das Projekt konvertiert haben, können Sie die neuen Features des SDK-Stilprojekts verwenden, z. B.:

  • Plattformübergreifende Build-Unterstützung
  • Vereinfachtes Projektdateiformat
  • Paketverweise

Um die Konvertierung sorgfältig abzuschließen, werden wir Folgendes ausführen:

  1. Erstellen einer Sicherung der ursprünglichen Projektdatei.
  2. Erstellen einer .dacpac-Datei aus dem ursprünglichen Projekt für den Vergleich.
  3. Modifizieren der Projektdatei zu einem Projekt im SDK-Stil.
  4. Erstellen einer .dacpac-Datei aus dem geänderten Projekt für den Vergleich.
  5. Sicherstellen, dass die .dacpac-Dateien identisch sind.

SDK-Stilprojekte werden von SQL Server Data Tools (SSDT) in Visual Studio nicht unterstützt. Nach der Konvertierung müssen Sie eines der folgenden Elemente verwenden, um das Projekt zu erstellen oder zu bearbeiten:

  • die Befehlszeile
  • die Erweiterung für SQL-Datenbankprojekte in Visual Studio Code
  • die Erweiterung „SQL Server-Datenbankprojekte“ in Azure Data Studio

Voraussetzungen

Schritt 1: Erstellen einer Sicherung der ursprünglichen Projektdatei

Erstellen Sie vor dem Konvertieren des Projekts eine Sicherung der ursprünglichen Projektdatei. Auf diese Weise können Sie bei Bedarf zum ursprünglichen Projekt zurückkehren.

Erstellen Sie im Datei-Explorer eine Kopie der .sqlproj-Datei für das Projekt, das Sie mit .original angefügt am Ende der Dateierweiterung konvertieren möchten. Beispielsweise wird MyProject.sqlproj zu MyProject.sqlproj.original.

Schritt 2: Erstellen einer .dacpac-Datei aus dem ursprünglichen Projekt für den Vergleich

Öffnen Sie das Projekt in Visual Studio 2022. Die .sqlproj-Datei befindet sich noch im ursprünglichen Format, sodass Sie sie in den ursprünglichen SQL Server-Datentools öffnen.

Erstellen Sie das Projekt in Visual Studio, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Datenbankknoten klicken und Build auswählen.

Um eine .dacpac-Datei aus dem ursprünglichen Projekt zu erstellen, müssen Sie die ursprünglichen SQL Server Data Tools (SSDT) in Visual Studio verwenden. Öffnen Sie die Projektdatei in Visual Studio 2022, wobei die ursprünglichen SQL Server-Datentools installiert sind.

Erstellen Sie das Projekt in Visual Studio, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Datenbankknoten klicken und Build auswählen.

Öffnen Sie den Projektordner in VS Code oder Azure Data Studio. Klicken Sie in der Ansicht Datenbankprojekte von VS Code oder Azure Data Studio mit der rechten Maustaste auf den Projektknoten, und wählen Sie Erstellen aus.

SQL-Datenbankprojekte können über die Befehlszeile mithilfe des dotnet build-Befehls erstellt werden.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Der Build-Prozess erstellt standardmäßig eine .dacpac-Datei im bin\Debug-Ordner des Projekts. Suchen Sie mithilfe des Datei-Explorers den vom Buildprozess erstellten .dacpac und kopieren Sie ihn als original_project.dacpac in einen neuen Ordner außerhalb des Projektverzeichnisses. Wir verwenden diese .dacpac-Datei zum Vergleich, um unsere Konvertierung später zu überprüfen.

Schritt 3: Aktualisieren der Projektdatei als Projekt im SDK-Stil

Das Ändern der Projektdatei ist ein manueller Prozess, der in einem Text-Editor am besten ausgeführt wird. Öffnen Sie die Datei .sqlproj in einem Texteditor und nehmen Sie die folgenden Änderungen vor:

Erforderlich: Hinzufügen der SDK-Referenz

Fügen Sie innerhalb des Projektelements ein Sdk-Element hinzu, um auf Microsoft.Build.Sql und die neueste Version von https://www.nuget.org/packages/Microsoft.build.sqlzu verweisen.

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0">
  <Sdk Name="Microsoft.Build.Sql" Version="0.2.0-preview" />
...

Erforderlich: Entfernen von unnötigen Build-Zielimporten

Ursprüngliche SQL-Projekte verweisen auf mehrere Build-Ziele und -Eigenschaften in Import-Anweisungen. Mit Ausnahme von <Import/>-Elementen, die Sie explizit hinzugefügt haben, bei denen es sich um eine eindeutige und absichtliche Änderung handelt, entfernen Sie Zeilen, die mit <Import ...> beginnen. Beispiele, die entfernt werden sollen, wenn sie in Ihrem .sqlproj vorhanden sind:

...
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Condition="..." Project="...\Microsoft.Data.Tools.Schema.SqlTasks.targets"/>
<Import Condition="'$(SQLDBExtensionsRefPath)' != ''" Project="$(SQLDBExtensionsRefPath)\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
<Import Condition="'$(SQLDBExtensionsRefPath)' == ''" Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
...

Erforderlich: Ordner Eigenschaften entfernen

Ursprüngliche SQL-Projekte haben einen Eintrag für einen Properties-Ordner, der den Zugriff auf die Projekteigenschaften im Projektmappen-Explorer darstellt. Dieses Element muss aus der Projektdatei entfernt werden.

Beispiel, das entfernt werden muss, wenn sie in Ihrem .sqlproj vorhanden sind:

<ItemGroup>
  <Folder Include="Properties" />
</ItemGroup>

Optional: Entfernen von SSDT-Verweisen

Die ursprünglichen SQL Server Data Tools (SSDT) benötigten zusätzlichen Inhalt in der Projektdatei, um die Visual Studio-Installation zu erkennen. Diese Zeilen sind in SQL-Projekten im SDK-Stil unnötig und können entfernt werden:

  <PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">11.0</VisualStudioVersion>
    <!-- Default to the v11.0 targets path if the targets file for the current VS version is not found -->
    <SSDTExists Condition="Exists('$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets')">True</SSDTExists>
    <VisualStudioVersion Condition="'$(SSDTExists)' == ''">11.0</VisualStudioVersion>
  </PropertyGroup>

Optional: Entfernen der Standard-Build-Einstellungen

Ursprüngliche SQL-Projekte enthalten zwei große Blöcke für Release- und Debug-Build-Einstellungen, während SQL-Projekte im SDK-Stil die Standardwerte für diese Optionen dem SDK bekannt sind. Wenn Sie keine Anpassungen an den Build-Einstellungen haben, sollten Sie die folgenden Blöcke entfernen:

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <OutputPath>bin\Release\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>False</TreatWarningsAsErrors>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineDebug>false</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <OutputPath>bin\Debug\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineDebug>true</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>

Schritt 4: Erstellen einer .dacpac-Datei aus dem geänderten Projekt für den Vergleich

Das SQL-Projekt ist nicht mehr mit Visual Studio 2022 kompatibel. Um das Projekt zu erstellen oder zu bearbeiten, müssen Sie eine der folgenden Aktionen verwenden:

  • die Befehlszeile
  • die Erweiterung für SQL-Datenbankprojekte in Visual Studio Code
  • die Erweiterung „SQL Server-Datenbankprojekte“ in Azure Data Studio

Die Projektdatei befindet sich jetzt im SDK-Format, aber um sie in Visual Studio 2022 zu öffnen, muss bei den SQL Server-Datentools das SDK-Stil (Vorschau) installiert sein, und das Projekt muss über die Dateierweiterung .sqlprojx verfügen. Öffnen Sie das Projekt in Visual Studio 2022, bei dem SQL Server Data Tools, SDK-Stil (Vorschau) installiert ist.

Öffnen Sie den Projektordner in VS Code oder Azure Data Studio. Klicken Sie in der Ansicht Datenbankprojekte von VS Code oder Azure Data Studio mit der rechten Maustaste auf den Projektknoten, und wählen Sie Erstellen aus.

SQL-Datenbankprojekte können über die Befehlszeile mithilfe des dotnet build-Befehls erstellt werden.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Der Build-Prozess erstellt standardmäßig eine .dacpac-Datei im bin\Debug-Ordner des Projekts. Suchen Sie mithilfe des Datei-Explorers den vom Buildprozess erstellten .dacpac und kopieren Sie ihn in einen neuen Ordner außerhalb des Projektverzeichnisses. Wir verwenden diese .dacpac-Datei zum Vergleich, um unsere Konvertierung später zu überprüfen.

Schritt 5: Überprüfen, ob die .dacpac-Dateien identisch sind

Um zu überprüfen, ob die Konvertierung erfolgreich war, vergleichen Sie die .dacpac-Dateien, die aus den ursprünglichen und geänderten Projekten erstellt wurden. Mit den Funktionalitäten Schemavergleich von SQL-Projekten können wir den Unterschied in Datenbankmodellen visualisieren.

Sie können das Schemavergleichstool in Visual Studio, Visual Studio Code oder Azure Data Studio verwenden, um die .dacpac-Dateien zu vergleichen. Community-Tools, die auf der DacFx .NET-Bibliothek basieren, sind ebenfalls verfügbar.

Starten Sie Visual Studio, ohne dass ein Projekt geladen wurde. Wechseln Sie zu Tools>SQL Server>Neuer Schemavergleich. Wählen Sie die ursprüngliche .dacpac-Datei als Quelle und die geänderte .dacpac-Datei als Ziel aus. Weitere Informationen zur Verwendung von Schemavergleich in Visual Studio finden Sie unter Verwendung des Schemavergleichs zum Vergleichen verschiedener Datenbankdefinitionen.

Der grafische Schemavergleich ist in der Vorschau von SQL-Projekten im SDK-Stil in Visual Studio noch nicht verfügbar. Verwenden Sie Azure Data Studio, um Schemas zu vergleichen.

Der Schemavergleich ist in Visual Studio Code nicht verfügbar. Verwenden Sie Azure Data Studio oder Visual Studio, um Schemas zu vergleichen.

Installieren Sie in Azure Data Studio die SQL Server*Schemavergleich-Erweiterung, wenn sie noch nicht installiert ist. Starten Sie einen neuen Schemavergleich aus der Befehlspalette, indem Sie die Befehlspalette mit Ctrl/Cmd+Shift+P und Eingabe von Schema Compare öffnen.

Wählen Sie die ursprüngliche .dacpac-Datei als Quelle und die geänderte .dacpac-Datei als Ziel aus.

Der grafische Schemavergleich ist in Visual Studio und Azure Data Studio verfügbar.

Wenn der Schemavergleich ausgeführt wird, sollten keine Ergebnisse angezeigt werden. Der Mangel an Unterschieden weist darauf hin, dass die ursprünglichen und geänderten Projekte gleichwertig sind und dasselbe Datenbankmodell in der .dacpac-Datei erzeugen.

Hinweis

Der Vergleich von .dacpac-Dateien über den Schemavergleich validiert keine Skripts vor/nach der Bereitstellung, refactorlog oder andere Projekteinstellungen. Es überprüft nur das Datenbankmodell. Das Konvertieren von .dacpac in ein .zip-Archiv und ein manueller Vergleich der Inhalte kann einen detaillierteren Vergleich ermöglichen.

Zugehöriger Inhalt