Convertir un projet SQL original en un projet de style SDK

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceBase 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 déjà des projets SQL, vous pouvez les convertir en projets SQL de type SDK pour tirer parti des nouvelles fonctionnalités.

Après avoir converti le projet, vous pouvez utiliser les nouvelles fonctionnalités du projet de type SDK, telles que :

  • Support des builds multiplateformes
  • Format simplifié de fichier de projet
  • Références de paquets

Pour réaliser la conversion avec soin, suivez ces étapes :

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

SQL Server Data Tools (SSDT) dans Visual Studio ne prend pas en charge les projets de type SDK. Après avoir converti le projet, utilisez l’un des outils suivants pour construire ou modifier le projet :

  • L’extension SQL Database Projects dans Visual Studio Code
  • DevOps pour bases de données dans SQL Server Management Studio (SSMS)
  • Ligne de commande
  • SQL Server Data Tools de type 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

É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 .sqlproj fichier du projet que vous souhaitez convertir avec .original ajoutée à l’extension de 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. 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 avec les outils de données SQL Server d’origine installés.

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 Visual Studio Code. Dans la vue Projets de base de données de Visual Studio Code, cliquez avec le bouton droit sur le nœud du projet, puis sélectionnez 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 avec les outils de données SQL Server d’origine installés.

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.

Vous pouvez générer des projets de base de données SQL à partir de la ligne de commande à l’aide de la dotnet build commande.

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. À l’aide de l’Explorateur de fichiers, localisez le .dacpac créé par le processus de génération et copiez-le dans un nouveau dossier en dehors du répertoire du projet en le renommant original_project.dacpac. Utilisez ce .dacpac fichier pour comparer afin de valider votre conversion plus tard.

É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. Supprimez cet élément du fichier du projet.

Exemple à supprimer si présent 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 type SDK, tous les .sql fichiers de l’arbre de dossiers du projet (**/*.sql) sont inclus par défaut. Supprimez les .sql fichiers spécifiés dans <Build Include="...." /> les éléments pour ces fichiers afin d’éviter les problèmes de performance de la compilation.

Supprimez des lignes comme celles-ci du fichier projet :

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

Ne pas supprimer :

  • <Build Include="..." /> éléments pour .sql fichiers qui ne se trouvent pas dans l’arborescence de dossiers du projet SQL
  • <PreDeploy Include="..." /> ou <PostDeploy Include="..." /> items, car ces nœuds dictent un comportement spécifique pour ces fichiers
  • Des éléments qui ne sont pas .sql des fichiers, comme .publish.xml les fichiers dans <None Include="..." /> les objets, .refactorlog.xml les fichiers dans <RefactorLog Include="..." /> les objets, ou .xsd les fichiers dans <Build Include="..." /> les objets

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 originaux incluent deux grands blocs pour les paramètres de compilation de Release et Debug, tandis que dans les projets SQL de type SDK, le SDK connaît les paramètres par défaut de ces options. 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, mettez-le à jour pour qu’il fasse référence au nouveau fichier projet de type SDK. Si vous n’avez pas de fichier de solution, vous pouvez ignorer cette section et passer à l’étape 5.

Option 1 : Créer un fichier de solution

Si le fichier de solution ne contient que le projet SQL, il est plus facile de supprimer le fichier de solution et de créer un nouveau fichier de solution avec un projet de type SDK.

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

Option 2 : Modifier le fichier de solution

Si le fichier de solution contient plusieurs projets, mettez à jour le fichier de solution pour qu’il fasse référence au nouveau fichier projet de type 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 d’un projet Microsoft.Build.Sql est 42EA0DBD-9CF1-443E-919E-BE9C484E4577. Le PROJECT_GUID est un identifiant unique du projet présent dans l’élément <ProjectGuid> du fichier projet. Si vous avez un fichier solution avec votre projet, vous n’avez pas besoin de changer la PROJECT_GUID valeur. Remplacez la valeur PROJECT_TYPE_GUID par le 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 construire ou modifier le projet, utilisez l’une des options suivantes :

  • Ligne de commande
  • L’extension SQL Database Projects dans Visual Studio Code
  • SQL Server Data Tools de type SDK (aperçu) dans Visual Studio 2022
  • SQL Server Management Studio (SSMS) avec la charge de travail DevOps pour bases de données (version préliminaire)

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

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

Ouvrez le fichier projet dans SQL Server Management Studio (SSMS) avec la charge de travail DevOps de base de données (préversion) installée. Dans l’Explorateur d’objets, cliquez avec le bouton droit sur le projet de base de données, puis sélectionnez Générer.

Vous pouvez générer des projets de base de données SQL à partir de la ligne de commande à l’aide de la dotnet build commande.

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. À l’aide de l’Explorateur de fichiers, localisez le .dacpac créé par le processus de génération et copiez-le dans un nouveau dossier en dehors du répertoire du projet. Utilisez ce .dacpac fichier pour comparer afin de valider votre conversion plus tard.

É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é. Utilisez les capacités de comparaison de schémas des projets SQL pour visualiser la différence entre les modèles de bases de données entre les deux .dacpac fichiers. Sinon, utilisez l’utilitaire en ligne de commande DacpacVerify pour comparer les deux .dacpac fichiers, y compris leurs scripts pré/post-déploiement et les paramètres du projet.

Vous pouvez installer DacpacVerify comme un 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 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 Visual Studio Code pour comparer les schémas.

Dans Visual Studio Code, 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 n’est pas disponible dans SQL Server Management Studio. Utilisez Visual Studio Code ou Visual Studio pour comparer les schémas.

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

Lorsque vous lancez la comparaison de schéma, aucun résultat ne devrait ê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 comparaison de schémas .dacpac ne valide pas les scripts de pré/post-déploiement, le refactorlog 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.

Contenu connexe

  • Last updated on