Microsoft.Build.Sql 1.0.0-rc1

Microsoft.Build.Sql (Preview)

The Microsoft.Build.Sql SDK contains MSBuild support for SQL, similar to Microsoft.NET.Sdk for .NET projects.

Overview

Your database objects are stored as code with Microsoft.Build.Sql SDK-style SQL projects. SQL database objects are aggregated from the .sql files in the project and dotnet build generates a .dacpac artifact for deploying the objects dynamically to a database. Development environment integrations are available for VS Code and Visual Studio:

• SQL database projects extension for VS Code and Azure Data Studio
• Visual Studio SQL Server Data Tools (SSDT), preview

SQL code analysis and other build-time tests can validate database code quality and correctness during continuous integration of code changes. Leverage the Microsoft.SqlPackage .NET tool for deploying objects to databases and updating a project with the contents of a project.

Get started

The Microsoft.Build.Sql SDK requires .NET 8 or higher.

New project

.NET templates are available for quickly setting up a new SQL project. Install the Microsoft.Build.Sql.Templates NuGet package to get started with a new SQL project.

dotnet new -i Microsoft.Build.Sql.Templates

Create a new SQL project using the sqlproj template.

dotnet new sqlproj -n ProductsTutorial

Any .sql files added to the project folder will be included in the build process and generate a .dacpac file. The .dacpac file can be used to deploy the database objects to a database.

From an existing database

An existing database can be scripted out into a SQL project using the Microsoft.SqlPackage .NET tool. The following command will generate a SQL project from an existing database.

sqlpackage /a:Extract /tf:YourProjectFolder /scs:"Data Source=yourservername;Initial Catalog=yourdatabasename;Authentication=Active Directory Interactive" /p:ExtractTarget=SchemaObjectType

Use the Microsoft.Build.Sql.Templates as outlined above to create a new SQL project file for the .sql files generated by the sqlpackage tool.

Convert an existing SQL project

Depending on the complexity of your project, the conversion to a Microsoft.Build.Sql project may be straightforward. Building the project before the process and retaining the .dacpac for comparison after the conversion is highly recommended. The primary step in the conversion is to add the SDK reference. Edit the .sqlproj file by adding

<Sdk Name="Microsoft.Build.Sql" Version="0.2.5-preview" />

inside the <Project> tag.

Depending on where you are developing, additional steps may be required. A walk-through of the conversion process is available at https://learn.microsoft.com/sql/tools/sql-database-projects/howto/convert-original-sql-project.

Resources

• Release notes
• Primary documentation
• CI/CD workflow samples
• GitHub repository

Telemetry

The .NET SDK for SQL includes a telemetry feature that collects usage data and sends it to Microsoft when you use build commands. The usage data includes exception information when the build command fails. Telemetry data helps the .NET team understand how the tools are used so they can be improved. Information on failures helps the team resolve problems and fix bugs.

How to opt out

The .NET SDK for SQL telemetry feature is enabled by default for Microsoft distributions of the SDK. To opt out of the telemetry feature, set the DACFX_TELEMETRY_OPTOUT environment variable to 1 or true. Telemetry feature can also be opt out by opting out .NET SDK telemetry.