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

Gilt für:SQL Server Azure SQL-Datenbank Verwaltete Azure SQL-Instanz SQL-Datenbank in Microsoft Fabric

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 Buildunterstützung
Vereinfachtes Projektdateiformat
Paketverweise

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

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

SDK-Stilprojekte werden in 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
SQL Server Data Tools, SDK-Format (Vorschau) in Visual Studio 2022

Note

Möglicherweise stellen Sie fest, dass Ihr SQL-Projekt Anpassungen enthält, die die erforderlichen Änderungen über diese Schritte hinaus erweitern. Zusätzlich zu diesem Artikel kann das DacFx GitHub-Repository verwendet werden, um die für das Upgrade von einem ursprünglichen SQL-Projekt auf SQL-Projekte im SDK-Stil erforderlichen Änderungen zu verstehen.

Prerequisites

.NET 8 SDK

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.sql zu verweisen, in der #.#.# im folgenden Codeausschnitt enthalten ist.

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

Erforderlich: Entfernen von unnötigen Buildzielimporten

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 "Properties" entfernen

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

Beispiel, das entfernt werden muss, falls es in Ihrem .sqlproj vorhanden ist.

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

Erforderlich: Standardmäßig enthaltene Buildelemente entfernen

Bei ursprünglichen SQL-Projekten werden alle .sql Dateien aufgeführt, die Datenbankobjekte explizit in der Projektdatei als <Build Include="..." /> Elemente darstellen. In SQL-Projekten im SDK-Stil sind alle .sql Dateien in der Projektordnerstruktur (**/*.sql) standardmäßig enthalten, sodass das Entfernen der <Build Include="...." /> Elemente für diese Dateien erforderlich ist, um Leistungsprobleme beim Erstellen zu vermeiden.

Zeilen, die aus der Projektdatei entfernt werden sollen, z. B.:

  <Build Include="SalesLT/Products.sql" />
  <Build Include="SalesLT/SalesLT.sql" />
  <Build Include="SalesLT/Categories.sql" />
  <Build Include="SalesLT/CategoriesProductCount.sql" />

Sie sollten <PreDeploy Include="..." /> oder <PostDeploy Include="..." /> Elemente nicht entfernen, da diese Knoten bestimmtes Verhalten für diese Dateien diktieren. Sie sollten auch keine <Build Include="..." /> Elemente für Dateien entfernen, die sich nicht in der SQL-Projektordner-Baumstruktur befinden.

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-Buildeinstellungen, während bei SQL-Projekten 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>

Die Projekteigenschaftenreferenz listet die verfügbaren Eigenschaften und deren Standardwerte auf.

Schritt 4: Lösungsdateien

Möglicherweise wird auf Ihre Projektdatei in einer Lösungsdatei (.sln) verwiesen. Wenn Sie über eine Lösungsdatei verfügen, sollten Sie sie aktualisieren, um auf die neue Projektdatei im SDK-Stil zu verweisen. Wenn Sie nicht über eine Lösungsdatei verfügen, können Sie diesen Abschnitt überspringen und mit Schritt 5 fortfahren.

Option 1: Erstellen einer neuen Lösungsdatei

Bei einer Lösungsdatei, die nur das SQL-Projekt enthält, ist es einfacher, die Lösungsdatei zu entfernen und eine neue Lösungsdatei mit dem SDK-Formatprojekt zu erstellen.

dotnet new sln --name MySolution
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj

Option 2: Bearbeiten der Lösungsdatei

Wenn eine Projektmappendatei mehrere Projekte enthält, sollten Sie die Projektmappendatei aktualisieren, um auf die neue Projektdatei im SDK-Stil zu verweisen. Sie können die Lösungsdatei in einem Text-Editor bearbeiten und den Projektverweis auf die neue SDK-Stil-Projektdatei ändern. Der Projektverweis in der Projektmappendatei sollte wie folgt aussehen:

Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
EndProject

Der PROJECT_TYPE_GUID Wert für ein Microsoft.Build.Sql-Projekt ist 42EA0DBD-9CF1-443E-919E-BE9C484E4577, und der PROJECT_GUID ist ein eindeutiger Bezeichner für das Projekt, das im Projektdateielement <ProjectGuid> gefunden wird. Wenn Sie über eine Projektmappendatei verfügen, brauchen Sie den PROJECT_GUID Wert nicht zu ändern, und er kann wie in der ursprünglichen Projektdatei bleiben. Der PROJECT_TYPE_GUID Wert muss in die GUID des Microsoft.Build.Sql-Projekttyps geändert werden.

Schritt 5: Erstellen einer `.dacpac` Datei aus dem geänderten Projekt zum 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
SQL Server Data Tools, SDK-Format (Vorschau) in Visual Studio 2022

Die Projektdatei befindet sich jetzt im SDK-Format, aber um sie in Visual Studio 2022 zu öffnen, müssen Sie die SQL Server Data Tools, SDK-Format (Vorschau) installiert haben. Öffnen Sie das Projekt in Visual Studio 2022, bei dem SQL Server Data Tools, SDK-Stil (Vorschau) installiert ist.

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 6: Ü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 Schemavergleichsfunktionen von SQL-Projekten können wir den Unterschied in Datenbankmodellen zwischen den beiden .dacpac Dateien visualisieren. Alternativ kann das Befehlszeilenprogramm DacpacVerify verwendet werden, um die beiden .dacpac Dateien zu vergleichen, einschließlich ihrer Skripts vor/nach der Bereitstellung und den Projekteinstellungen.

DacpacVerify ist für die Installation als Dotnet-Tool verfügbar. Führen Sie den folgenden Befehl zum Installieren des Tools aus:

dotnet tool install --global Microsoft.DacpacVerify --prerelease

Die Syntax für DacpacVerify besteht darin, den Dateipfad für zwei .dacpac Dateien als dacpacverify <source DACPAC path> <target DACPAC path>anzugeben. Führen Sie den folgenden Befehl aus, um die beiden .dacpac Dateien zu vergleichen:

DacpacVerify original_project.dacpac modified_project.dacpac

Sie können das Schemavergleichstool in Visual Studio oder Azure Data Studio verwenden, um Objekte in den .dacpac Dateien zu vergleichen.

Starten Sie Visual Studio, ohne dass ein Projekt geladen wurde. Wechseln Sie zu >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.

Note

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. Die Verwendung des Befehlszeilenprogramms DacpacVerify ist die empfohlene Methode, um zu überprüfen, ob die beiden .dacpac Dateien gleichwertig sind.

Feedback

War diese Seite hilfreich?

Last updated on 2025-09-25