Convertir un projet SQL original en un projet de style SDK

S’applique à :SQL Server Azure SQL Database Azure SQL Managed Instance Base de données SQL dans Microsoft Fabric

La création d’un projet SQL de style SDK est une tâche rapide. Cependant, si vous avez des projets SQL existants, vous pouvez les convertir en projets SQL de style SDK afin de bénéficier des nouvelles fonctionnalités.

Une fois le projet converti, vous pouvez utiliser les nouvelles fonctionnalités du projet de style SDK, telles que :

la prise en charge de la génération multiplateforme
le format de fichier projet simplifié
références de paquet

Pour terminer la conversion avec soin, nous allons :

Créer une sauvegarde du fichier projet d’origine.
Générer un fichier .dacpac à partir du projet d'origine à des fins de comparaison.
Modifier le fichier projet pour en faire un projet de style SDK.
Générez un fichier .dacpac à partir du projet modifié à des fins de comparaison.
Vérifiez que les fichiers .dacpac sont identiques.

Les projets de style SDK ne sont pas pris en charge dans SQL Server Data Tools (SSDT) dans Visual Studio. Une fois le projet converti, vous devez utiliser l'une des méthodes suivantes pour le générer ou le modifier :

la ligne de commande
l'extension des projets de bases de données SQL dans Visual Studio Code
l'extension SQL Database Projects dans Azure Data Studio
SQL Server Data Tools, style SDK (préversion) dans Visual Studio 2022

Note

Vous pouvez constater que votre projet SQL contient une personnalisation qui étend les modifications requises au-delà de ces étapes. En plus de cet article, le dépôt GitHub DacFx peut être utilisé pour comprendre les modifications nécessaires à la mise à niveau d’un projet SQL d’origine vers des projets SQL de style SDK.

Prerequisites

SDK .NET 8

Étape 1 : créer une sauvegarde du fichier projet d’origine

Avant de convertir le projet, créez une sauvegarde du fichier projet d'origine. Ainsi, vous pouvez revenir au projet d’origine si nécessaire.

Dans l'explorateur de fichiers, créez une copie du fichier .sqlproj pour le projet que vous voulez convertir avec .original à la fin de l'extension du fichier. Par exemple, MyProject.sqlproj devient MyProject.sqlproj.original.

Étape 2 : générer un fichier `.dacpac` à partir du projet d'origine à des fins de comparaison

Ouvrez le projet dans Visual Studio 2022. Le fichier .sqlproj est toujours dans le format d'origine, vous l'ouvrez donc dans le SQL Server Data Tools d'origine.

Générez le projet dans Visual Studio en cliquant avec le bouton droit sur le nœud de la base de données dans l'Explorateur de solutions et en sélectionnant Générer.

Pour créer un fichier .dacpac à partir du projet d’origine, vous devez utiliser le SQL Server Data Tools (SSDT) d’origine dans Visual Studio. Ouvrez le fichier projet dans Visual Studio 2022 avec le SQL Server Data Tools d’origine installé.

Générez le projet dans Visual Studio en cliquant avec le bouton droit sur le nœud de la base de données dans l'Explorateur de solutions et en sélectionnant Générer.

Ouvrez le dossier du projet dans VS Code ou Azure Data Studio. Dans la vue Projets de base de données de VS Code ou Azure Data Studio, cliquez avec le bouton droit sur le nœud du projet et sélectionnez Générer.

Les projets de base de données SQL peuvent être générés à partir de la ligne de commande à l’aide de la commande dotnet build.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Le processus de génération crée par défaut un fichier .dacpac dans le dossier bin\Debug du projet. En utilisant l'explorateur de fichiers, localisez le fichier .dacpac créé par le processus de génération et copiez-le dans un nouveau dossier en dehors du répertoire du projet comme original_project.dacpac. Nous utilisons ce fichier .dacpac à des fins de comparaison pour valider notre conversion ultérieurement.

Étape 3 : modifier le fichier projet pour en faire un projet de style SDK

La modification du fichier projet est un processus manuel, qu'il est préférable d'effectuer dans un éditeur de texte. Ouvrez le fichier .sqlproj dans un éditeur de texte et apportez les modifications suivantes :

Obligatoire : ajouter la référence du SDK

À l’intérieur de l’élément projet, ajoutez un élément Sdk pour référencer Microsoft.Build.Sql et la dernière version depuis https://www.nuget.org/packages/Microsoft.build.sql, où #.#.# est inclus dans l’extrait de code ci-dessous.

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

Obligatoire : supprimer les importations inutiles de cibles de génération

Les projets SQL d'origine font référence à plusieurs cibles et propriétés de génération dans les instructions d'importation. À l'exception des éléments <Import/> que vous avez explicitement ajoutés, ce qui constitue une modification unique et délibérée, supprimez les lignes qui commencent par <Import ...>. Exemples à supprimer en cas de présence dans votre .sqlproj :

...
<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" />
...

Obligatoire : supprimer le dossier Propriétés

Les projets SQL d'origine ont une entrée pour un dossier Properties qui représentait l'accès aux propriétés du projet dans l'explorateur de solutions. Cet élément doit être supprimé du fichier projet.

Exemple à supprimer en cas de présence dans votre .sqlproj :

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

Obligatoire : Supprimer les éléments de build inclus par défaut

Les projets SQL d’origine répertorient tous les .sql fichiers représentant des objets de base de données explicitement dans le fichier projet en tant qu’éléments <Build Include="..." /> . Dans les projets SQL de style SDK, tous les fichiers .sql dans l’arborescence des dossiers du projet **/*.sql sont inclus par défaut. Par conséquent, la suppression des éléments <Build Include="...." /> pour ces fichiers est nécessaire pour éviter les problèmes de performances de génération.

Lignes qui doivent être supprimées du fichier projet, par exemple :

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

Vous ne devez pas supprimer <PreDeploy Include="..." /> ou <PostDeploy Include="..." /> éléments, car ces nœuds dictent un comportement spécifique pour ces fichiers. Vous ne devez pas également supprimer <Build Include="..." /> les éléments des fichiers qui ne se trouvent pas dans l’arborescence des dossiers du projet SQL.

Facultatif : supprimer les références SSDT

La version d'origine de SQL Server Data Tools (SSDT) nécessitait un contenu supplémentaire dans le fichier projet pour détecter l'installation de Visual Studio. Ces lignes sont inutiles dans les projets SQL de style SDK et peuvent être supprimées :

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

Facultatif : supprimer les paramètres de génération par défaut

Les projets SQL d'origine comprennent deux grands blocs pour les paramètres de génération Libérer et Déboguer, alors que dans les projets SQL de style SDK, les valeurs par défaut de ces options sont connues par le kit SDK. Si vous ne personnalisez pas les paramètres de génération, envisagez de supprimer ces blocs :

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

La référence des propriétés du projet répertorie les propriétés disponibles et leurs valeurs par défaut.

Étape 4 : Fichiers de solution

Votre fichier projet peut être référencé dans un fichier de solution (.sln). Si vous avez un fichier de solution, vous devez le mettre à jour pour référencer le nouveau fichier projet de style SDK. Si vous n’avez pas de fichier solution, vous pouvez ignorer cette section et passer à l’étape 5.

Option 1 : Créer un fichier de solution

Pour un fichier solution qui contient uniquement le projet SQL, il est plus simple de supprimer le fichier solution et de créer un fichier solution avec le projet de style SDK.

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

Option 2 : Modifier le fichier de solution

Lorsqu’un fichier de solution contient plusieurs projets, vous devez mettre à jour le fichier solution pour référencer le nouveau fichier projet de style SDK. Vous pouvez modifier le fichier solution dans un éditeur de texte et modifier la référence du projet au nouveau fichier projet de style SDK. La référence du projet dans le fichier solution doit ressembler à ceci :

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

La valeur PROJECT_TYPE_GUID pour un projet Microsoft.Build.Sql est 42EA0DBD-9CF1-443E-919E-BE9C484E4577, et PROJECT_GUID est un identificateur unique pour le projet trouvé dans l'élément <ProjectGuid> du fichier projet. Si vous avez un fichier solution avec votre projet, la PROJECT_GUID valeur n’est pas nécessaire pour être modifiée et peut rester la même que dans le fichier projet d’origine. La valeur de PROJECT_TYPE_GUID doit être changée en GUID du type de projet Microsoft.Build.Sql.

Étape 5 : Générer un `.dacpac` fichier à partir du projet modifié pour la comparaison

Le projet SQL n’est plus compatible avec Visual Studio 2022. Pour générer ou modifier le projet, vous devez utiliser l’une des méthodes suivantes :

la ligne de commande
l'extension des projets de bases de données SQL dans Visual Studio Code
l'extension SQL Database Projects dans Azure Data Studio
SQL Server Data Tools, style SDK (préversion) dans Visual Studio 2022

Le fichier projet est désormais au format de style SDK, mais pour l’ouvrir dans Visual Studio 2022, vous devez installer SQL Server Data Tools, style SDK (préversion). Ouvrez le projet dans Visual Studio 2022 avec SQL Server Data Tools de style SDK (préversion) installé.

Les projets de base de données SQL peuvent être générés à partir de la ligne de commande à l’aide de la commande dotnet build.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Le processus de génération crée par défaut un fichier .dacpac dans le dossier bin\Debug du projet. En utilisant l'explorateur de fichiers, localisez le fichier .dacpac créé par le processus de génération et copiez-le dans un nouveau dossier en dehors du répertoire du projet. Nous utilisons ce fichier .dacpac à des fins de comparaison pour valider notre conversion ultérieurement.

Étape 6 : Vérifier que les `.dacpac` fichiers sont identiques

Pour vérifier que la conversion a réussi, comparez les fichiers .dacpac créés à partir du projet d'origine et du projet modifié. Les fonctionnalités de comparaison de schéma des projets SQL nous permettent de visualiser la différence entre les modèles de base de données entre les deux .dacpac fichiers. Vous pouvez également utiliser l’utilitaire de ligne de commande DacpacVerify pour comparer les deux .dacpac fichiers, y compris leurs scripts de pré/post-déploiement et leurs paramètres de projet.

DacpacVerify est disponible pour l’installation en tant qu’outil dotnet. Pour installer l’outil, exécutez la commande suivante :

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

La syntaxe de DacpacVerify consiste à spécifier le chemin de fichier pour deux fichiers .dacpac comme dacpacverify <source DACPAC path> <target DACPAC path>. Pour comparer les deux .dacpac fichiers, exécutez la commande suivante :

DacpacVerify original_project.dacpac modified_project.dacpac

Vous pouvez utiliser l’outil de comparaison de schémas dans Visual Studio ou Azure Data Studio pour comparer des objets dans les .dacpac fichiers.

Lancez Visual Studio sans projet chargé. Allez dans Outils>SQL Server>Nouvelle comparaison de schéma. Sélectionnez le fichier .dacpac d'origine comme source et le fichier .dacpac modifié comme cible. Pour en savoir plus sur l'utilisation de la fonctionnalité Comparer les schémas dans Visual Studio, consultez la section sur l'utilisation de la comparaison de schémas pour comparer différentes définitions de bases de données.

La comparaison de schémas graphiques n’est pas encore disponible dans la préversion des projets SQL de style SDK dans Visual Studio. Utilisez Azure Data Studio pour comparer les schémas.

La comparaison de schémas n’est pas disponible dans Visual Studio Code. Utilisez Azure Data Studio ou Visual Studio pour comparer les schémas.

Dans Azure Data Studio, installez l'extension SQL Server Schema Compare si elle n'est pas déjà installée. Lancez une nouvelle comparaison de schémas à partir de la palette de commandes en ouvrant la palette de commandes avec Ctrl/Cmd+Shift+P et en saisissant Schema Compare.

Sélectionnez le fichier .dacpac d'origine comme source et le fichier .dacpac modifié comme cible.

La comparaison de schémas graphiques est disponible dans Visual Studio et Azure Data Studio.

Lorsque la comparaison de schémas est exécutée, aucun résultat ne doit être affiché. Le manque de différences indique que les projets originaux et modifiés sont équivalents, produisant le même modèle de base de données dans le .dacpac fichier.

Note

La comparaison de fichiers par le biais de la comparaison de .dacpac schémas ne valide pas les scripts de pré/post-déploiement, la refactorisation ou d’autres paramètres de projet. Il ne valide que le modèle de base de données. L’utilisation de l’utilitaire de ligne de commande DacpacVerify est la méthode recommandée pour vérifier que les deux .dacpac fichiers sont équivalents.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-09-25