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

Gilt für:SQL ServerAzure SQL-DatenbankVerwaltete Azure SQL-InstanzSQL-Datenbank in Microsoft Fabric

Das Erstellen eines neuen SQL-Projekts im SDK-Stil ist eine schnelle Aufgabe. Wenn Sie jedoch bereits SQL-Projekte haben, können Sie diese in SDK-ähnliche SQL-Projekte umwandeln, um die neuen Funktionen zu nutzen.

Nachdem Sie das Projekt konvertiert haben, können Sie die neuen Funktionen des SDK-ähnlichen Projekts nutzen, wie zum Beispiel:

• Unterstützung für plattformübergreifende Builds
• Vereinfachtes Projektdateiformat
• Paketverweise

Um die Umwandlung sorgfältig abzuschließen, folgen Sie diesen Schritten:

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.

SQL Server Data Tools (SSDT) in Visual Studio unterstützt keine SDK-ähnlichen Projekte. Nachdem Sie das Projekt konvertiert haben, verwenden Sie eines der folgenden Werkzeuge, um das Projekt zu erstellen oder zu bearbeiten:

• Die SQL Database Projects-Erweiterung in Visual Studio Code
• Datenbank-DevOps in SQL Server Management Studio (SSMS)
• Die Befehlszeile
• SQL Server Data Tools im SDK-Format (Vorschau) in Visual Studio 2022

Prerequisites

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 Datei .sqlproj für das Projekt, das Sie konvertieren möchten, wobei an die Dateierweiterung .original angehängt wird. Beispielsweise wird MyProject.sqlproj zu MyProject.sqlproj.original.

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

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 im Datei-Explorer nach der vom Buildprozess erstellten .dacpac und kopieren Sie sie unter dem Namen original_project.dacpac in einen neuen Ordner außerhalb des Projektverzeichnisses. Verwenden Sie diese .dacpac Datei zum Vergleich, um Ihre Konvertierung später zu validieren.

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. Entfernen Sie dieses Element aus der Projektdatei.

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 SDK-ähnlichen SQL-Projekten sind alle .sql Dateien im Projektordnerbaum (**/*.sql) standardmäßig enthalten. Entfernen Sie die .sql in den Elementen für diese Dateien angegebenen <Build Include="...." /> Dateien, um Verarbeitungsprobleme zu vermeiden.

Entferne Zeilen wie die folgenden aus der Projektdatei:

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

Nicht entfernen:

• <Build Include="..." /> Elemente für .sql Dateien, die nicht im SQL-Projektordnerbaum enthalten sind
• <PreDeploy Include="..." /> oder <PostDeploy Include="..." /> Elemente, weil diese Knoten ein bestimmtes Verhalten für diese Dateien festlegen
• Elemente, die keine .sql Dateien sind, wie .publish.xml Dateien in <None Include="..." /> Items, .refactorlog.xml Dateien in <RefactorLog Include="..." /> Items oder .xsd Dateien in <Build Include="..." /> Items

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

Originale SQL-Projekte enthalten zwei große Blöcke für Release- und Debug-Build-Einstellungen, während das SDK bei SDK-ähnlichen SQL-Projekten die Standardeinstellungen für diese Optionen kennt. 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 du eine Lösungsdatei hast, aktualisiere sie so, dass sie auf die neue SDK-ähnliche Projektdatei verweisen kann. Wenn Sie keine Lösungsdatei haben, können Sie diesen Abschnitt überspringen und mit Schritt 5 fortfahren.

Option 1: Erstellen einer neuen Lösungsdatei

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

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

Option 2: Bearbeiten der Lösungsdatei

Wenn die Lösungsdatei mehrere Projekte enthält, aktualisieren Sie die Lösungsdatei um die neue SDK-ähnliche Projektdatei zu referenzieren. 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. Die PROJECT_GUID ist eine eindeutige Kennung für das Projekt, die im Element <ProjectGuid> der Projektdatei zu finden ist. Wenn du eine Lösungsdatei mit deinem Projekt hast, musst du den PROJECT_GUID Wert nicht ändern. Ändern Sie den PROJECT_TYPE_GUID-Wert in die GUID des Projekttyps Microsoft.Build.Sql.

Schritt 5: Erstellen einer .dacpac Datei aus dem geänderten Projekt zum Vergleich

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. Mit dem Dateiexplorer finden Sie das vom Build-Prozess erstellte Objekt .dacpac und kopieren es in einen neuen Ordner außerhalb des Projektverzeichnisses. Verwenden Sie diese .dacpac Datei zum Vergleich, um Ihre Konvertierung später zu validieren.

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. Nutzen Sie die Schema-Vergleichsfunktionen von SQL-Projekten, um die Unterschiede in Datenbankmodellen zwischen den beiden .dacpac Dateien zu visualisieren. Alternativ können Sie das DacpacVerify-Kommandozeilenprogramm verwenden, um die beiden .dacpac Dateien zu vergleichen, einschließlich ihrer Vor- und Nachbereitstellungsskripte und Projekteinstellungen.

Du kannst DacpacVerify als Dotnet-Tool installieren. 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 verwenden, um Objekte in den .dacpac Dateien zu vergleichen.

Wenn Sie einen Schema-Vergleich durchführen, 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.

Verwandte Inhalte

• Was sind SQL-Datenbankprojekte?
• Erste Schritte mit SQL-Datenbankprojekten
• SQL-Projekte-Paketverweise