--- title: Convert an Original SQL Project description: "Create an SDK-style SQL project from an existing project." author: dzsquared ms.author: drskwier ms.reviewer: maghan, randolphwest ms.date: 09/25/2025 ms.service: sql ms.subservice: sql-database-projects ms.topic: how-to ms.collection: - data-tools ms.custom: - ignite-2024 zone_pivot_groups: sq1-sql-projects-tools --- # Convert an original SQL project to an SDK-style project [!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance FabricSQLDB](../../../includes/applies-to-version/sql-asdb-asdbmi-fabricsqldb.md)] Creating a new SDK-style SQL project is a [quick task](../get-started.md#step-1-create-a-new-project). However, if you have existing SQL projects you can convert them to SDK-style SQL projects in place to take advantage of the new features. Once you convert the project, you can use the new features of the SDK-style project, such as: - cross-platform build support - simplified project file format - package references To complete the conversion carefully, we will: 1. Create a backup of the original project file. 1. Build a `.dacpac` file from the original project for comparison. 1. Modify the project file to an SDK-style project. 1. Build a `.dacpac` file from the modified project for comparison. 1. Verify that the `.dacpac` files are the same. SDK-style projects aren't supported in SQL Server Data Tools (SSDT) in Visual Studio. Once converted, you must use one of the following to build or edit the project: - the command line - the SQL Database Projects extension in Visual Studio Code - the SQL Database Projects extension in Azure Data Studio - the SQL Server Data Tools, SDK-style (preview) in Visual Studio 2022 > [!NOTE] > You might find that your SQL project contains customization that extends the changes required beyond these steps. In addition to this article, the [DacFx GitHub repository](https://github.com/microsoft/dacfx) can be used to understand the changes necessary to upgrade from an original SQL project to SDK-style SQL projects. ## Prerequisites ::: zone pivot="sq1-visual-studio" - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) - [Visual Studio 2022 Community, Professional, or Enterprise](https://visualstudio.microsoft.com/downloads/) - [Install SQL Server Data Tools (SSDT) for Visual Studio](../../../ssdt/download-sql-server-data-tools-ssdt.md) ::: zone-end ::: zone pivot="sq1-visual-studio-sdk" - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) - [Visual Studio 2022 Community, Professional, or Enterprise](https://visualstudio.microsoft.com/downloads/) - [SQL Server Data Tools, SDK-style (preview) installed in Visual Studio 2022](../../../ssdt/sql-server-data-tools-sdk-style.md) ::: zone-end ::: zone pivot="sq1-visual-studio-code" - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) - [VS Code](https://code.visualstudio.com/Download) - [SQL Database Projects extension](/azure-data-studio/extensions/sql-database-project-extension) or [SQL Database Projects extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-mssql.sql-database-projects-vscode) ::: zone-end ::: zone pivot="sq1-command-line" - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) ::: zone-end ## Step 1: Create a backup of the original project file Before you convert the project, create a backup of the original project file. This way, you can revert to the original project if needed. In file explorer, create a copy of the `.sqlproj` file for the project you want to convert with `.original` appended on the end of the file extension. For example, `MyProject.sqlproj` becomes `MyProject.sqlproj.original`. ## Step 2: Build a `.dacpac` file from the original project for comparison ::: zone pivot="sq1-visual-studio" Open the project in Visual Studio 2022. The `.sqlproj` file is still in the original format, so you open it in the original SQL Server Data Tools. Build the project in Visual Studio by right-clicking on the database node in **Solution Explorer** and selecting **Build**. ::: zone-end ::: zone pivot="sq1-visual-studio-sdk" To build a `.dacpac` file from the original project, you must use the original SQL Server Data Tools (SSDT) in Visual Studio. Open the project file in Visual Studio 2022 with the original SQL Server Data Tools installed. Build the project in Visual Studio by right-clicking on the database node in **Solution Explorer** and selecting **Build**. ::: zone-end ::: zone pivot="sq1-visual-studio-code" Open the project folder in VS Code or Azure Data Studio. In the **Database Projects** view of VS Code or Azure Data Studio, right-click the project node and select **Build**. ::: zone-end ::: zone pivot="sq1-command-line" SQL database projects can be built from the command line using the `dotnet build` command. ```bash dotnet build # optionally specify the project file dotnet build MyDatabaseProject.sqlproj ``` ::: zone-end The build process creates a `.dacpac` file in the `bin\Debug` folder of the project by default. Using file explorer, locate the `.dacpac` created by the build process and copy it into a new folder outside of the project directory as `original_project.dacpac`. We use this `.dacpac` file for comparison to validate our conversion later. ## Step 3: Modify the project file to an SDK-style project Modifying the project file is a manual process, best performed in a text editor. Open the `.sqlproj` file in a text editor and make the following changes: ### Required: Add the SDK reference Inside the project element, add an `Sdk` item to reference Microsoft.Build.Sql and the latest version from where `#.#.#` is included in the snippet below. ```xml ... ``` ### Required: Remove unnecessary build target imports Original SQL projects reference several build targets and properties in Import statements. Except for `` items you explicitly added, which is a unique and deliberate change, remove lines that begin with ``. Examples to remove if present in your `.sqlproj`: ```xml ... ... ``` ### Required: Remove Properties folder Original SQL projects have an entry for a `Properties` folder that represented access to the project properties in solution explorer. This item needs to be removed from the project file. Example to remove if present in your `.sqlproj`: ```xml ``` ### Required: Remove Build items included by default Original SQL projects list all `.sql` files representing database objects explicitly in the project file as `` items. In SDK-style SQL projects, any `.sql` files in the project folder tree (`**/*.sql`) are included by default, so removing the `` items for those files is necessary to avoid build performance issues. Lines that should be removed from the project file, for example: ```xml ``` You shouldn't remove `` or `` items, because these nodes dictate [specific behavior](../concepts/pre-post-deployment-scripts.md) for those files. You also shouldn't remove `` items for files that aren't in the SQL project folder tree. ### Optional: Remove SSDT references The original SQL Server Data Tools (SSDT) required extra content in the project file to detect the Visual Studio install. These lines are unnecessary in SDK-style SQL projects and can be removed: ```xml 11.0 True 11.0 ``` ### Optional: Remove default build settings Original SQL projects include two large blocks for Release and Debug build settings, while in SDK-style SQL projects the defaults for these options are known by the SDK. If you don't have customizations to the build settings, consider removing these blocks: ```xml bin\Release\ $(MSBuildProjectName).sql False pdbonly true false true prompt 4 bin\Debug\ $(MSBuildProjectName).sql false true full false true true prompt 4 ``` The [project properties](../concepts/project-properties.md) reference lists the available properties and their defaults. ## Step 4: Solution files Your project file might be referenced in a solution file (`.sln`). If you have a solution file, you should update it to reference the new SDK-style project file. If you do not have a solution file, you can skip this section and proceed to Step 5. ### Option 1: Create a new solution file For a solution file that only contains the SQL project, it is more straightforward to remove the solution file and create a new solution file with the SDK-style project. ```bash dotnet new sln --name MySolution dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj ``` ### Option 2: Edit the solution file When a solution file contains multiple projects, you should update the solution file to reference the new SDK-style project file. You can edit the solution file in a text editor and change the project reference to the new SDK-style project file. The project reference in the solution file should look like this: ```xml Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}" EndProject ``` The `PROJECT_TYPE_GUID` value for a Microsoft.Build.Sql project is `42EA0DBD-9CF1-443E-919E-BE9C484E4577`, and the `PROJECT_GUID` is a unique identifier for the project found in the project file `` element. If you have a solution file with your project, the `PROJECT_GUID` value is not required to be changed and can remain the same as in the original project file. The `PROJECT_TYPE_GUID` value is required to be changed to the Microsoft.Build.Sql project type GUID. ## Step 5: Build a `.dacpac` file from the modified project for comparison ::: zone pivot="sq1-visual-studio" The SQL project is no longer compatible with Visual Studio 2022. To build or edit the project, you must use one of: - the command line - the SQL Database Projects extension in Visual Studio Code - the SQL Database Projects extension in Azure Data Studio - the SQL Server Data Tools, SDK-style (preview) in Visual Studio 2022 ::: zone-end ::: zone pivot="sq1-visual-studio-sdk" The project file is now in the SDK-style format, but to open it in Visual Studio 2022, you must have the SQL Server Data Tools, SDK-style (preview) installed. Open the project in Visual Studio 2022 with [SQL Server Data Tools, SDK-style (preview)](../../../ssdt/sql-server-data-tools-sdk-style.md) installed. ::: zone-end ::: zone pivot="sq1-visual-studio-code" Open the project folder in VS Code or Azure Data Studio. In the **Database Projects** view of VS Code or Azure Data Studio, right-click the project node and select **Build**. ::: zone-end ::: zone pivot="sq1-command-line" SQL database projects can be built from the command line using the `dotnet build` command. ```bash dotnet build # optionally specify the project file dotnet build MyDatabaseProject.sqlproj ``` ::: zone-end The build process creates a `.dacpac` file in the `bin\Debug` folder of the project by default. Using file explorer, locate the `.dacpac` created by the build process and copy it into a new folder outside of the project directory. We use this `.dacpac` file for comparison to validate our conversion later. ## Step 6: Verify that the `.dacpac` files are the same To verify that the conversion was successful, compare the `.dacpac` files created from the original and modified projects. The [schema comparison](../concepts/schema-comparison.md) capabilities of SQL projects allow us to visualize the difference in database models between the two `.dacpac` files. Alternatively, the DacpacVerify command-line utility can be used to compare the two `.dacpac` files, including their pre/post-deployment scripts and project settings. DacpacVerify is available for install as a [dotnet tool](https://www.nuget.org/packages/Microsoft.dacpacverify). To install the tool, run the following command: ```bash dotnet tool install --global Microsoft.DacpacVerify --prerelease ``` The syntax for DacpacVerify is to specify the filepath to two `.dacpac` files as `dacpacverify `. To compare the two `.dacpac` files, run the following command: ```bash DacpacVerify original_project.dacpac modified_project.dacpac ``` You can use the schema compare tool in Visual Studio or Azure Data Studio to compare objects in the `.dacpac` files. ::: zone pivot="sq1-visual-studio" Launch Visual Studio without a project loaded. Go to **Tools** > **SQL Server** > **New Schema Comparison**. Select the original `.dacpac` file as the source and the modified `.dacpac` file as the target. For more on using Schema Compare in Visual Studio, see [using schema compare to compare different database definitions](../../../ssdt/how-to-use-schema-compare-to-compare-different-database-definitions.md). ::: zone-end ::: zone pivot="sq1-visual-studio-sdk" Graphical schema comparison isn't yet available in the SDK-style SQL projects preview in Visual Studio. Use Azure Data Studio to compare schemas. ::: zone-end ::: zone pivot="sq1-visual-studio-code" Schema comparison isn't available in Visual Studio Code. Use Azure Data Studio or Visual Studio to compare schemas. In Azure Data Studio, install the **SQL Server Schema Compare** extension if it isn't already installed. Launch a new schema comparison from the command palette by opening the command palette with `Ctrl/Cmd+Shift+P` and typing `Schema Compare`. Select the original `.dacpac` file as the source and the modified `.dacpac` file as the target. ::: zone-end ::: zone pivot="sq1-command-line" Graphical schema comparison is available in Visual Studio and Azure Data Studio. ::: zone-end When schema comparison is run, no results should be displayed. The lack of differences indicates that the original and modified projects are equivalent, producing the same database model in the `.dacpac` file. > [!NOTE] > The comparison of `.dacpac` files through schema comparison doesn't validate pre/post-deployment scripts, refactorlog, or other project settings. It only validates the database model. Using the DacpacVerify command-line utility is the recommended way to validate that the two `.dacpac` files are equivalent. ## Related content - [What are SQL database projects?](../sql-database-projects.md) - [Get started with SQL database projects](../get-started.md) - [SQL projects package references](../concepts/package-references.md)